design-editor / crates
CLAUDE.md16 starsChanged 26 days agoMITView on GitHub
Native + web editor chrome implemented in Rust against jian-skia. This is the canonical Design Editor implementation — the original TypeScript editor (apps/web, apps/desktop, apps/cli, pen-*) has been retired, so the Rust shell is the product, not a parity port. // ported from pen-* comments below name the retired TS as historical origin; that code lives only in git history now. Phase 7.3 reorg — read before trusting paths below. The old design-editor-shell-* crates were dissolved/renamed; deeper sections in this…
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- packages/CLAUDE.mdCLAUDE.md
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 172
Import Image or SVG… → ShapeChoice::ImportImageOrSvg (host follow-up).
- Very specific: line 332
All struct fields and intra-module helpers are scoped pub(in crate::widget_host) so submodule impl blocks can reach them while the public …
- Distinctive: line 403
commit-on-blur for property-panel inputs + the variable-row inline editor, then resolve Git-panel / chat-model-picker ownership (the …
- Very specific: line 427
Every input path that reasons about the canvas region MUST derive its rects from canvas_region(…), and every path that reaso
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Rust Shell
Native + web editor chrome implemented in Rust against jian-skia. This is the canonical Design Editor implementation — the original TypeScript editor (apps/web, apps/desktop, apps/cli, pen-*) has been retired, so the Rust shell is the product, not a parity port. // ported from pen-* comments below name the retired TS as historical origin; that code lives only in git history now.
Crate layout
Phase 7.3 reorg — read before trusting paths below. The old
design-editor-shell-*crates were dissolved/renamed; deeper sections in this doc may still cite pre-reorg paths. Map them:design-editor-shell-native→de-host-native,design-editor-shell-web→de-host-web,design-editor→de-host-desktop.design-editor-shell-corewas split, not just renamed: widgets / Document /RenderBackend→de-editor-ui, the MCP wire layer →de-mcp(flatde-mcp/src/*.rs, nomcp/subdir). Thewasm-libc-shim+vendor/skia-safe-opwasm-skia fork are retired — the browser renders through the official CanvasKit skia WASM (loaded separately), so the Rust wasm bundle is pure logic; the "Web runner" section below is stale (it describes the old wasm32 skia-raster + EMSDK path).2026-07 dedupe + split campaign (
839f474a..d2d8104c) — second stale-path layer. Three structural changes ripple through the sections below. (1) The canonical editor state isEditorStateinde-editor-core/src/state.rs; there is nodocument/directory in any crate, so everyshell-core/src/document/*.rspath in the "Document model", pen-tool, colour-picker, and hot-path sections names a file that no longer exists — the behaviour they describe is still accurate, the paths are not. (2) The native↔webwidget_hostfork is single-sourced — see "Shared host logic" below for where the real logic lives. (3) The 800-line cap now holds workspace-wide with zero violations, so nearly every module named below is a spine plus sibling files; a path that resolves to a directory instead of a single file is the split, not a rename.
crates/
├── de-editor-ui/ Platform-free widgets + RenderBackend facade (wasm32-clean); re-exports the render scene from jian-scene + scene_vars from de-editor-core
├── de-editor-core/ Canonical `.de` (PenDocument) editor state + EditorCommand + scene_vars (design-variable resolution)
├── de-editor-host-core/ Transport-free host state machines shared by all hosts
├── de-host-native/ Native host lib: WidgetHostNative + skia-safe GL backend (desktop)
├── de-host-web/ Browser bundle entry: wasm32-unknown-unknown cdylib, CanvasKit renderer
├── de-host-desktop/ Desktop binary `design-editor` (winit + skia-safe GL); also the `--serve-web` daemon
├── de-cli/ `de` command-line tool
├── de-util/ Dependency-free leaf: hex-colour / JSON / XML helpers
└── … de-mcp / de-ai / de-ai-skills / de-codegen / de-orchestrator / de-figma /
de-git / de-opmerge / de-pen-loader / de-design-lint / de-config-store /
de-process-io / de-acp / de-i18n / de-rpc-transport / de-smoke /
de-host-services / de-host-web-server / de-html / de-pptxde-util is the workspace's single source for three helpers that had drifted
into many copies: hex_color (nine divergent implementations, one of which
panicked on non-ASCII input), json_escape (one copy was lossy), and
xml_escape (one copy omitted the quote entity — an attribute-injection gap).
It must stay dependency-free and wasm32-clean: it sits in the browser host's
build graph via de-editor-core / de-editor-ui. Reach for it instead of writing
a local parse_hex / escape_json again.
vendor/jian/ is a submodule providing the rendering primitive layer (jian-skia Skia adapter, jian-host-desktop GL plumbing, jian-core event types + taffy layout, jian-scene canonical render scene — LayoutScene + hit-test + path geometry, consumed by OP and any jian app); vendor/casement is the winit fork; vendor/agent is the cross-product Rust agent runtime. All are referenced by path in the workspace Cargo.toml.
Key invariants
- de-host-native tests need
--features gl-host.gl-hostis a non-default feature (keepsskia-safe/glout of the raster build used by de-host-services), and the entirewidget_hostmodule is gated behind it — a default-featurecargo test -p de-host-nativeruns 55 tests instead of 676 and gives ZERO coverage ofwidget_host/changes. Always test native with--features gl-host. - de-editor-ui (widgets) stays wasm32-clean (spec v19 §1.2). No skia-safe / winit / accesskit_winit. The
RenderBackendtrait is the only seam between widget code and platform. - Widget code lives in de-editor-ui only. Hosts (de-host-native
widget_host.rs, de-host-webwidget_host.rs) are the ONLY files allowed to callde_editor_ui::widgets::*. Boundary script:tools/check-widget-boundary.sh. - Max 800 lines per file — zero violations workspace-wide. As of
d2d8104cno.rsfile incrates/exceeds the cap, and the sibling-module split is the universal shape: a spine keeps the public surface andmoddeclarations, cohesive clusters move into siblings, and re-exports keep every import path and test name stable. Splits are pure code motion — when you split, do not also change behaviour. Test modules follow the same rule (foo_tests.rs, or afoo/tests/directory when the tests themselves outgrow the cap). Check withfind crates -name '*.rs' -exec wc -l {} + | awk '$1>800'. - Blocking on a future from sync host code goes through
de_host_services::chat_runtime::block_on_anywhere. A bareRuntime::block_on(or a privately-built current-thread runtime) aborts with "runtime within runtime" when the caller happens to sit on a tokio worker.block_on_anywherepicks the safe strategy for whichever context it is called from; it is the only sanctioned entry point and is exercised by tests for the no-runtime, multi-thread-worker, and borrowing-non-Send-future cases. - Fallible paths carry typed error enums, not
String. The whole workspace is converted (80+ enums;Result<_, String>survives at exactly two documented boundary sites). Find the domain's enum in its*_error.rs/error.rssibling module (e.g.CliError,ProgramError,WebCanvasError,McpServeError,ExportError,McpLiveError,DocIoError,ImageGenerateError). The pattern to copy: one enum per failure domain in its own sibling module, structured fields instead of pre-formatted text, aDisplayimpl that reproduces the previous message byte-identically (so user-visible strings and their tests don't move), andFromimpls that collapse themap_erradapters at the call sites. New fallible code should introduce or reuse an enum rather than add anotherResult<_, String>. - Web bundle ceiling: 6 MiB gzip + 0 env.* imports. Enforced by
tools/check-wasm-bundle.sh. The CanvasKit bundle carries the full app logic (codegen AI pipeline, Figma parser, AI/live-sync) plus the still-embedded AI skill corpus (~1.1 MiB of markdown viainclude_dir!), so the ceiling sits well above the retired skia raster path's 1 MiB (4.93 MiB today; the ceiling is a runaway-regression tripwire, not a budget). Re-baselined from 8 MiB once the ~2.4 MiB of preview JPEGs moved out — see below. The 0 env.* guard still holds — CanvasKit needs no libc shim. - Product assets are embedded on native and fetched on wasm.
de-editor-core/src/web_assets.rsis the platform-free half: a process-globalroute -> bytesregistry with single-flight, a widget-records / host-drains request queue, andAbsent/Pending/Ready/Failedstates. The widget layer callsweb_assets::request(route)from paint and draws a placeholder;de-host-web/src/web_asset_fetch.rsdrains it once per frame over XHR and installs the bytes. Native keeps itsinclude_bytes!unchanged behind#[cfg(not(target_arch = "wasm32"))], so desktop behaviour is byte-identical. Assets are served from/pkg/assets/…and staged into the bundle bytools/stage-web-assets.sh, whichcheck-wasm-bundle.shruns as step 4 and both the CI workflow andDockerfile.web-rustinherit. Moved: the Prompt Center (~2.1 MiB) and 80 Scene Template preview JPEGs (~3.4 MiB), the 80 scene-template.dedocuments (~6.6 MiB), andiconify-catalog-core.json(~452 KiB) — ~12.6 MiB of staged assets in total, plus the gzipped Material Symbols / phosphor catalogs (~2.5 MiB, #4;runtime-icon-catalogalso pullsflate2to inflate them). Still embedded everywhere: thede-ai-skillscorpus (~1.1 MiB,include_dir!). - The icon-catalog split is opt-in, the rest is
cfg(target_arch = "wasm32").de-editor-ui'sruntime-icon-catalogfeature is enabled only byde-host-web, which has a daemon to fetch from and a frame pump to install on. The desktop hosts keep the embed. Bundle ceiling: de-host-web 6 MiB (5.17 MiB measured).
Document model (shell-core/src/document/)
Single source of truth for editor state — mirrors TS useCanvasStore + useDocumentStore + useAIStore collapsed into one.
Document
├── pages: Vec<Page> (id + name + nodes)
├── active_page_index
├── selected: NodeId (NONE = no selection)
├── tool: Tool (Select / Rect / Ellipse / Polygon / Star / Line / Pen / Text / Frame / Hand)
├── viewport: Viewport (pan_x / pan_y / zoom + zoom_at + pan)
├── chat: ChatState (messages, input, focused, anchor, collapsed)
└── ui: UiState (sidebar_open, layer_panel_width, property_panel_width,
property_focus, property_input: TextInputState,
settings_input: TextInputState,
agent_settings_open, agent_settings (focus, tab, connected[5],
mcp_server, mcp_cli_enabled[8], images_*, hover_provider),
color_picker, pen_in_progress, pen_cursor_doc,
pending_pen_history,
layer_context_menu, page_context_menu,
theme_mode, locale, locale_picker_open,
shape_picker_open, shape_tool,
flex_layout, size_fill_width / fill_height / hug_width /
hug_height / clip_content, fill_type, fill_type_picker_open,
property_tab (Design|Code))Mutators on Document:
commit_property_edit(focus, value)— write parsed f32 to position / size / rotation / stroke width.set_selected_color(is_fill, color)— write hex-parsedColorto fill or stroke.set_selected_bounds(rect)— handle-drag resize.set_selected_rotation(radians)— rotation-ring drag.translate_selected(dx, dy)— node-drag move (recurses into descendants when the matched node is bounded so children don't detach).delete_selected()— remove the selected node from its parent's children (Delete / Backspace shortcut).duplicate_selected(&mut next_id, offset_doc_px)— deep-clone with fresh ids; lifts the allocator pastmax_node_id() + 1(checked_addsou64::MAXreturns None instead of colliding).reorder_selected(ReorderDirection::Up | Down)— swap with next/prev sibling ([/]).deselect_all()— clear selection (Escape last tier).max_node_id()— largest raw id across pages + children, for the duplicate allocator guard.node_at_doc_point(p)— top-most-first hit-test honoring per-node rotation.start_pen_path/add_pen_point/finish_pen_path(document/pen.rs) — multi-anchorNodeKind::Pathbuilder; history snapshot captured BEFORE the first anchor so undo restores pre-pen state; finish strips 1-anchor (invisible) paths instead of polluting the undo stack.group_selected/ungroup_selected(document/grouping.rs) — Cmd+G / Cmd+Shift+G; group wraps selected siblings under a freshNodeKind::Groupwhoseaggregate_boundscovers the union.add_page/duplicate_page/remove_page/rename_page_committed(document/page_mutators.rs).open_color_picker(target, click_y)(document/color_picker.rs) — anchors a floating HSV picker; HSV stays anchored across the RGB-rounding cycle so dragging the hue slider doesn't visibly snap.
Node.rotation: f32 (radians, cw +); paint applies RenderBackend::rotate(radians, pivot) around the node's centre. Bounded-Frame drag carries descendants — children's bounds are document-space-absolute. Node.corner_radius: f32 (doc-px) is honored by Rect / Frame paint via fill_round_rect / stroke_round_rect when radius * zoom > 0.5; below that threshold paint collapses to fill_rect / stroke_rect.
Node::aggregate_bounds returns child-union bounds for container nodes (Group / unbounded Frame) so the property panel reports meaningful W/H.
NodeKind now spans Frame / Group / Rect / Ellipse / Polygon / Line / Text / Path / Other; each has its own canvas paint (oval, triangle polygon, diagonal line, fill+stroke rect, polyline through node.points, shaped text). The RenderBackend trait grew fill_oval / stroke_oval / fill_polygon / stroke_polygon / rotate / fill_svg_path so both native + web backends can paint them; fill_svg_path covers brand logos that ship as filled SVG paths in a non-24×24 viewBox.
FillType { Solid, LinearGradient, RadialGradient, Image } + FlexLayout { Free, Vertical, Horizontal } drive the property panel's dropdowns / button groups; both live on Document.ui so toggles persist across selection changes.
Widgets (shell-core/src/widgets/)
| Widget | Section | File |
| FilePill / CanvasActions | Floating chrome over the canvas (#30, no title bar): file pill top-left (home · name → File menu · save state), action group top-right (</> Code view · Preview · Download · Export), panel toggle above the tool rail (#86); one ChromeHit enum | file_pill.rs, canvas_actions.rs, panel_toggle.rs, chrome_hit.rs, chrome_tooltip.rs; window-control dots in window_strip.rs |
| Floating cards | Editor v3 (#86): left card (Agent / Layers / Components / Images) and properties card over a full-bleed canvas, the panel motion (panel_reveal, 220 ms) and paint_card | floating_panels.rs; core motion in editor_ui_state/panel_motion.rs |
| LayerPanel | Left rail — Pages + Layers sections | layer_panel.rs |
| Toolbar | Vertical floating column — Select / shape slot / Ellipse / Pen / Pencil / Text / Frame / Note / Image / Hand | toolbar.rs |
| ShapePicker | Toolbar shape-slot dropdown (Rect / Polygon / Star / Line / Icon; a star is a polygon with innerRadius, geometry in de-editor-ui/src/polygon_geometry.rs) | shape_picker.rs |
| CanvasViewport | Center — node tree + grid + viewport transform | canvas_viewport.rs |
| PropertyPanel | Right rail (272) — pinned header (selection glyph + name + kind, or the Code view with ✕, property_panel_header.rs) + sections + interactive inputs (Position X/Y/W/H/Rot/R, hex, stroke width) + Auto layout with the fill/hug/clip boxes + fill-type picker + closing Code chips (property_panel_code_chips.rs) | property_panel.rs + the property_panel_*.rs family + property_panel/, property_panel_snapshot/, property_panel_tests/ |
| AIChatPlaceholder | Floating — chat with drag + 4-corner snap + collapse pill | ai_chat_panel.rs |
| LocalePicker | File ▸ Language dropdown under the file pill (15 native names + Check) | locale_picker.rs |
| StatusBar | Floating bottom-right — zoom controls | status_bar.rs |
| icons | lucide d-string library (50+ icons; 24×24 viewBox stroke art) | icons.rs |
| brand_icons | Claude / OpenAI / Gemini / Copilot / Antigravity / Grok filled logos + OpenCode primitive logo | brand_icons.rs |
| ColorPicker | HSV overlay (Cmd-Shift-C or fill/stroke swatch click) — sat/value box + hue strip + hex input | color_picker.rs |
| LayerContextMenu | Right-click overlay on layer rows + page tabs (Rename / Duplicate / Delete / Group / Ungroup / Lock / Hide; subset on page tabs) | layer_context_menu.rs |
| AgentSettings | Cmd+, modal — up to 960×760, sidebar nav (Agents / MCP / Images / Fonts / System) + scrollable body; Agents is list + detail | agent_settings_panel.rs + agent_settings_{agents,i18n,images,mcp,system}*.rs |
| theme | shadcn-dark palette tokens (incl. canvas_surface) | theme.rs |
| i18n | 15 canonical locale catalogs, 1,860 direct keys each, sharded main → _git → _panel → _collab in the de-i18n crate | de-i18n/src/i18n/{en,zh_cn,zh_tw,ja,ko,fr,es,de,pt,ru,hi,tr,th,vi,id}{,_git,_panel,_collab}.rs |
Theme + i18n
Document.ui carries chrome-level state including theme_mode (Dark/Light), locale, and locale_picker_open:
theme_for(ui)returns the activeTheme— since #30 Home's v2 tokens mapped onto the shadcn slots (home_surface_palette::chrome_theme), so the editor, Settings and the chat share one palette. Widget builders read it instead of hardcodingTheme::dark(), so flipping the theme (File menu footer) reflows the entire chrome. The chrome font is Manrope (text_metrics::CHROME_FONT_FAMILY).Document::t(key)translates viai18n::translate(self.ui.locale, key). Keys retain the retired TS app's dot.case convention (common.untitled,pages.title,layers.title,ai.newChat,ai.tipSelectElements,layout.flexLayout,fill.title,stroke.title,effects.title,export.title,property.createComponent,topbar.agentsAndMcp), but the Rust tables are now the canonical source.- 15 supported locales (matches TS dropdown order): EnUs / ZhCn / ZhTw / Ja / Ko / Fr / Es / De / Pt / Ru / Hi / Tr / Th / Vi / Id. Each carries a
display_name()(English / 简体中文 / 繁體中文 / 日本語 / 한국어 / Français / Español / Deutsch / Português / Русский / हिन्दी / Türkçe / ไทย / Tiếng Việt / Bahasa Indonesia). - File ▸ Language (the menu's footer globe) opens a
LocalePickerdropdown under the file pill. Native applies a clicked locale immediately; web closes the picker but keeps the old locale while an uninstalled runtime catalog is pending, then mutatesDocument.ui.localeonce the JSON is ready. Clicking outside (or the Globe again) closes silently. The picker paints as the top-most overlay so it covers chat / status / canvas. - Multi-script chrome strings (한국어 / हिन्दी / ไทย / Tiếng Việt) render against per-codepoint typeface lookups (
FontMgr::match_family_style_charactercached peri32inNativeBackend), with each string broken into contiguous-typeface segments before draw. Locale tables are hand-maintained in Rust, and each locale is four files, chained by fall-through: the main table
<locale>.rsends itsmatchwith_ => return super::<locale>_git::lookup(key), the Git shard ends with_ => return super::<locale>_panel::lookup(key), the_panelshard ends with_ => return super::<locale>_collab::lookup(key), and the_collaboverflow shard ends with_ => return None. The catalog is 1,860 direct keys per locale (catalog_integrity_tests.rsasserts the exact number). Native builds compile all 15 tables. On wasm32,de-host-webenablesde-editor-ui's forwardingruntime-locale-catalogfeature;de-i18n's source-side feature + target double gate then keeps only en-US + zh-CN embedded.tools/export-i18n-catalogs.pyvalidates the same 1,860-key equality and generates the other 13 BCP-47 JSON files fortools/stage-web-assets.shto place under/pkg/assets/i18n/.Adding a new key: put it in
<locale>_collab.rs(the terminal overflow shard), in all 15 locales. The main tables sit close to the repo's 800-line ceiling (zh_cn.rsanden.rsare 775 lines), so new entries do not belong there — the_panelshards exist precisely to absorb overflow and have room. Only edit a main or_gittable when you are changing the wording of a key that already lives there. Then bump the expected count incatalog_integrity_tests.rsand run:cargo test -p de-i18nCatalog integrity tests enforce the exact cross-locale key set across all four shards, reject duplicate or unsupported match arms, and require every translation to preserve the English placeholder set. The
i18n/mod.rstests were split into sibling modules alongside it (tests.rs,catalog_integrity_tests.rs, plus per-feature key guards:figma_property_panel_key_tests.rs,html_import_key_tests.rs,missing_fonts_key_tests.rs,preview_device_key_tests.rs,vector_fidelity_property_keys.rs) — add a feature's key guard next to those rather than growingmod.rs.tools/convert-locales.pyis a deliberate failing shim because its retired TypeScript source no longer exists. Runtime lookup still falls back through English and then the raw key for debug visibility, while the tests prevent shipped locale gaps.
Toolbar shape-tool dropdown
The toolbar's compound ShapeSlot paints whichever shape variant is current (ui.shape_tool, default Rect) plus a small chevron-down in the gutter directly below the button (SHAPE_SLOT_BOTTOM_EXTRA = 10 px). Click anywhere on the slot — including the chevron — to toggle ui.shape_picker_open.
ShapePicker::for_editor_ui(ui) paints a 220 × 5-row dropdown anchored to the right of the slot (Ellipse, Pen and image import have their own rail buttons since #30):
- Rectangle / Polygon / Star / Line →
ShapeChoice::Tool(Tool::*)— the host writesui.shape_tool+doc.tooland closes the panel. A star (#87) is aPolygonNodewithinnerRadius; the panel shows Points + Inner radius for it. - Icon →
ShapeChoice::OpenIconPicker(host follow-up). - Import Image or SVG… →
ShapeChoice::ImportImageOrSvg(host follow-up).
Click anywhere outside the panel closes it silently. Locale lookups for the row labels (shapes.rectangle / polygon / star / line / icon) come from the locale tables; missing keys fall back to English literals.
PropertyPanel input editing
Document.ui carries the focused property field and a shared text input state:
property_focus: Option<PropertyFocus>—PositionX / PositionY / Rotation / PositionR / SizeW / SizeH / Opacity / FillHex / StrokeHex / StrokeWidth. All 10 variants are wired end-to-end: numeric focuses go throughDocument::commit_property_edit(PositionRwritesnode.corner_radius), hex focuses throughset_selected_color(is_fill, color).property_input: TextInputState— live keystrokes, caret, select-all, blink, and composition state accumulate here.apply_textis focus-aware:- Numeric focuses (Position / Size / Rotation / Opacity / StrokeWidth) gate
[0-9], leading-, and a single.. - Hex focuses (FillHex / StrokeHex) preserve a sticky
#prefix, accept[0-9a-fA-F]only, and cap the draft at 7 chars (#RRGGBB). No select-all-on-focus — backspace removes one char at a time, typing appends one. Padding(the Auto layoutPadfield, #83) takes digits,.and spaces: a CSS shorthand of 1–4 values (16,96 120,8 16 4,8 16 8 4), parsed / formatted byde-editor-core/src/padding_shorthand.rsand committed throughcommit_padding_shorthand.
- Numeric focuses (Position / Size / Rotation / Opacity / StrokeWidth) gate
property_input_draft/ caret fields are legacy mirrors while older preset-name and compatibility paint paths are retired.
Hex parsing is forgiving: parse_hex_color zero-pads 1-5 char inputs to 6 and expands CSS shorthand #RGB → #RRGGBB, so mid-edit commits don't visibly "reset" the colour.
PropertyPanel::for_selection_at(doc, now_ms) is the entry point. The host calls panel.hit_test(panel_rect, point) to map clicks onto a PropertyFocus, and panel.hit_test_action(panel_rect, point) to map clicks onto a PropertyPanelAction. Commit on Enter, discard on Escape, auto-commit on click outside the property panel.
Buttons + checkboxes — PropertyPanelAction
PropertyPanelAction
├── SetFlexLayout(FlexLayout) Free / Vertical / Horizontal
├── ToggleSizeFillWidth / FillHeight
├── ToggleSizeHugWidth / HugHeight
├── ToggleSizeClipContent
├── ToggleLayoutAlignPopover Auto layout header button → 3×3 grid + Packed / Space between / Space around
├── ToggleFillMenu(index) a fill row's `⋯` menu
├── ToggleFillTypePicker(index) the menu's type trigger
├── SetFillType { index, fill_type } Solid / LinearGradient / RadialGradient / Image / …
└── ToggleExportSection Export header "+" / "−"The hit-test walker action_button_rects_with_fill_picker(panel_rect, visible, …) lives in property_panel_layout.rs and emits one Rect per action. Every y-walk starts each section at section_tops(...) (property_panel_section_tops.rs, built from the VisibleSections height helpers: component_block_h, position_section_h, size_section_h, and the per-section height fns): the action walker, editable_input_rects, the text section's anchor walk and PropertyPanel::paint, which debug_asserts that each painted section ends at the next top. Fill rows step through fill_row_tops. Open popovers (the alignment popover, a fill ⋯ menu) win hit_test_action over the sections they overlap.
Fill rows and the ⋯ menu (#83)
Each fill is one row (fill_row_rects): swatch, hex in JetBrains Mono (text_metrics::MONO_FONT_FAMILY; a gradient / image fill shows its type instead), opacity, the colour-variable button on the primary fill, and a trailing ⋯. The menu (property_panel_fill_menu.rs, editor_ui.fill_menu_open) holds the type and blend triggers, move up / down and remove; the fill-type and blend pickers anchor to those triggers through the action walker, so the menu stays open under them. A focused hex keeps the mono face because BaselineAdjustingBackend can override the family jian's TextInputView draws and measures with. Bodies under the primary fill:
- Solid — none (the hex is on the row).
- LinearGradient — Angle row + 色标 header + 2 default stops.
- RadialGradient — 色标 header + 2 stops (no angle).
- AngularGradient (#7) — Angle row (the start rotation, 0° = 12 o'clock, clockwise) + 色标 header + stops, like Linear. Native paints a skia sweep, web a CanvasKit
MakeSweepGradient, HTML exportconic-gradient, SVG export a wedge<pattern>, PPTX rasters it. - MeshGradient — Rows and Columns steppers over a two-column grid of vertex swatches (
property_panel_fill_mesh_shader.rs); a swatch click opens the HSV picker throughColorTarget::GradientStop(i), because the snapshot lists mesh vertices as the primary fill'sgradient_stops(#90). A stepper (EditMeshLattice, coremesh_lattice.rs, #142) adds or removes a whole row / column, 2–5 per axis: an add inserts the middle line with neighbour-midpoint colours, a remove drops the middle interior line, corners never move, and the stops are rewritten row-major (a missing vertex becomes transparent, as rendered). One undo step each throughupdates_document. - Shader — one preset row (Noise = the
turbulencepreset, Fade, Glow:de_editor_core::shader_presets). A custom program adds a trailing Custom cell (#141): picking a preset stashes the program per node ineditor_ui.custom_shader_bodies(UI state, cleared on document replace), and Custom restores it as an ordinary undoable edit. Under it (#164,property_panel_shader_body.rs) one row per user uniform the SkSL declares, read from the doc comment in front of eachuniform(de_editor_core::shader_uniform_specs:@label,@range a, b/@min/@max,@colororlayout(color),@default;size/time/mouse,@time/@mouse/@resolutionanduniform shaderchildren get none): a ranged float is a slider + number (DragShaderUniform, first step snapshots history), other floats / vectors are numbers (PropertyFocus::ShaderUniform), a colour opens the HSV picker (ColorTarget::ShaderUniform). The fill walkers carry the row count ingradient_stop_count(primary_body_items). Then the Code row: it opens the floating source editor (widgets/shader_source_editor.rs, state + keys in coreshader_source_editor.rs; Enter keeps the indent, Tab indents, Apply is one undo step and keeps it open, Close / Escape drop the draft) and shows whether the program compiles. Core has no SkSL compiler: each frame the hosts compile the sources the panel shows (shader_check::refresh, nativeRuntimeEffect::make_for_shader, webopCk.shaderCompileError) and the panel reads the cached result. Writes go throughEditorCommand::SetShaderUniform/SetShaderSource(shader_edit.rs, checked against the declarations), also MCPset_shader_uniform/set_shader_source. - Image — trigger row (thumbnail + current mode name) opening a 220px popover (
property_panel_image_fill.rs): mode toggle (Fill / Fit / Crop / Tile / Stretch for image fills,ImageFillMode::modes_for; an Image node has no Stretch; Crop enables drag-to-reframe on canvas with edge clamping), Tile scale input, upload well, 7 color-adjust sliders + reset. SchemaImageFillBody.transformis honored by both skia and CanvasKit renderers.
fill_body_height_with_stops(fill_type, stops) returns the body height per variant. Outside clicks close the menu and pickers through the hosts' dismiss tiers in apply_press; Escape closes a picker first, then the menu.
The rest of the compact panel (#83): Auto layout is the direction segments plus one Gap | Pad row, with alignment in the header popover (property_panel_flex.rs); Create component is an icon in the pinned header (property_panel_header::create_component_rect); an Interactions section with no action and the Export section (collapsed by default, editor_ui.export_section_open) are their header and "+".
Interactions and Motion (#154): the Interactions section lists one row per authored trigger (Tap = onTap, Hover = onHoverEnter, Long press = onLongPress) with its action (Navigate to a page screen / Back), plus a Slide | Fade row under a navigate (the verb: push slides, replace cross-fades). Its "+" lists the unauthored triggers and "Animation"; the Motion section (property_panel_motion.rs) appears below once the node has animations. Since #190 every localized control owns its row so the longest of the 15 translations fits (a test sweeps them): an animation is property dropdown + remove / trigger dropdown / From | To / Duration / Delay (PropertyFocus::MotionValue), a custom one is label + remove / trigger, the node transition is label + remove / easing / duration, and the Slide | Fade cells take their whole row. MotionProperty::Fill tweens a hex colour (From / To on a row each, PropertyFocus::MotionColor; a new one starts at the solid fill and ends 20% darker, lighter when near black). One popover serves every row (editor_ui.interaction_menu_target, property_panel_interactions_menu.rs), so the hosts' popover routing is unchanged; it drops below its row when it fits the section viewport, else opens above, else is pinned inside (interaction_menu_viewport, the fill-type picker's bounds). Navigate targets leave out the screen holding the selection. The writes live in core (interaction_edit.rs, motion_edit.rs) and rebuild the whole events / animations value through PatchNodeData (a shallow merge would drop sibling handlers); they are in updates_document, one undo step each. Since #176 a trigger's popover also offers Scroll to <section> (scroll_to, the named frames under the selection's page root, document_section_targets), Open URL (open_url with a URL input row, PropertyFocus::InteractionUrl) and Change to <trigger> (moves the actions, move_selected_interaction); the "+" offers Transition, the node-level transition (easing dropdown + duration, transition_edit.rs, PropertyFocus::TransitionDuration) shown at the top of the Motion section. The orchestrator's tap wiring (wire_screen_navigation::apply_on_tap, also used by the web-link and backfill passes) merges into the node's existing events the same way.
Model-only options the panel exposes since #90: the Position header's flip buttons (property_panel_flip.rs, core selection_flip.rs, also Shift+H / Shift+V), the Stroke section's style rows under the colour / width rows (property_panel_stroke_style.rs: Inside / Center / Outside, then Cap / Join / Dash rows from #89; the Dash row is Solid / Dashed / Dotted presets, a custom pattern highlights no cell; Dotted writes a Round cap and a None / Square cap click while Dotted is active switches the dash to Solid, #141), and Inner shadow in the Effects add menu (MCP: add_node_effect kind: inner_shadow, the same body via fills::panel_shadow_body, #142). The arms dispatch from property_panel_dispatch_paint.rs; segmented rows share property_panel_segments.rs.
Rich stroke paints (#13): a stroke whose paint is more than one plain solid keeps its stack on SceneNode::stroke_fill_layers (loader: StrokePayload::fill_layers). canvas_viewport_stroke_paint.rs lays the stack over the stroke's outer box with the node-fill painters, then masks it with the stroke geometry drawn in white (push_mask_source_layer); every primitive's stroke code goes through with_stroke_paint and only takes the colour it is handed. SVG / HTML / PPTX exports keep the solid fallback colour.
Linear burn / linear dodge (#14) have no skia or CanvasKit built-in: both run as SkSL runtime blenders (de-host-native/src/backend/skia/blender.rs, the same programs in op_ck_bridge.js, a test keeps them in sync), falling back to Multiply / Plus. HTML export writes plus-darker / plus-lighter.
Placeholder frames (#16): FrameNode.placeholder (pen.dev's flag) paints the generation-scan panel and sweep under the frame's children on the editor canvas only (canvas_placeholder.rs, inside canvas_viewport's with_overlay scope), at 20 fps through canvas_shader_clock::mark_animated.
Annotations (#12): note / context / prompt are PenNode variants sharing jian's NoteNode (content, size, text style, a prompt's model; kemalcalak/jian#13). PenNode::type_tag() names every kind in one table, PenNode::annotation() / is_canvas_only() let consumers treat them together; PenNode::is_canvas_only_tag is the one tag list that de_editor_ui::canvas_only and codegen's JSON strip read. The loader builds NodeKind::Other(tag) (annotation_to_payload); widgets/canvas_annotation.rs paints the sticky card (light / dark palettes per kind) only inside the editor canvas (with_annotations, like canvas_placeholder), so PNG / PDF exports and screenshots leave them out; SVG / HTML / PPTX skip them through canvas_only::is_canvas_only, codegen through node_hidden and strip_canvas_only_json. The body is a derived text node (annotation_body), so inline editing (double-click) uses the text editor. Toolbar Note tool (N) drops a 240×160 note; the panel's Annotation section (property_panel_annotation.rs, core annotation_edit.rs) switches the kind and edits content / model. pen.dev import keeps all three kinds.
Live browser node (#20): PenNode::Browser (jian BrowserNode: url, deviceId, zoom, scrollX / scrollY, width / height, cornerRadius, stroke, effects; pen.dev's browser) is canvas-only like the annotations. The loader builds NodeKind::Other("browser") with the frame, corners and stroke, and the address / device on the widget descriptor (de-pen-loader/src/adapter/browser.rs); widgets/canvas_browser.rs paints the page box only inside the editor canvas (canvas_annotation::editor_canvas_dark) and the preview (browser_preview::with_clip, see "Preview pages (#324)"), and its drop shadows go through the shared pass (shapes::casts_drop_shadow). Device presets and the url / zoom / scroll rules live in de_editor_core::browser_devices (a known preset resizes the node; an unknown pen.dev id is kept), the writes in browser_edit.rs (one PatchNodeData each). The panel's Browser section (property_panel_browser.rs) edits URL, device (Desktop / Tablet / Phone), zoom and scroll; the shape menu's Browser row is Tool::Browser (drops 1440 × 900). MCP insert_node takes kind: browser; the pen.dev import keeps browser nodes (no longer in DROPPED_KINDS).
Live pages (#20): the painter notes the browser nodes its last page frame showed and draws the newest snapshot (widgets/browser_textures.rs, through canvas_viewport_image::paint_cached_raster); it never renders anything itself. Both hosts drive the shared widgets/browser_render_queue.rs once per frame: a quiet frame compares a stamp (document revision, reload generation, load gate, visible set) and walks nothing; a changed de_editor_core::browser_live::BrowserRenderRequest key is returned for rendering (300 ms debounce, a first picture or Reload at once, at most two in flight, failed keys not retried) and the result goes back through finish. On desktop (de-host-desktop/src/browser_render_host.rs) workers render with the user's headless Chrome / Chromium / Edge / Brave through the new de-browser-render crate (own thin CDP client on tungstenite, DE_BROWSER_PATH override, one process-wide browser, BrowserPool::shared, ended by start_idle_reaper after 60 s without renders or open tabs, on app or daemon exit, and on Unix by a sh watchdog when the app dies without exiting) and wake the loop with DesktopEvent::BrowserFrameReady; the decode and pan-cache refresh are the image path's (raster_generation). Off-screen nodes are never noted, so never loaded. A document opened from disk that holds browser nodes keeps its pages held (EditorState::hold_browser_pages_if_any, called by the desktop open and the web host's ingest_document_source; MCP browser refuses its nodes meanwhile) until the panel's Load pages row (AllowBrowserPages) or a typed address; Reload is ReloadBrowser. Measured: a quiet pump with 50 visible browsers ~40–60 µs per frame (debug), first render with browser start ~1.4 s, warm render ~0.2 s, and a page answering after 6 s caused no frame over 32 ms (DE_SLOW_FRAME_LOG=1). The web host (de-host-web/src/widget_host/browser_snapshot_fetch.rs, from CkInner::repaint) sends the queue's requests to the serve-web daemon's POST /api/browser/snapshot (de-host-services/src/web_browser_snapshot.rs, outside the state lock, two renders at once): once a serve-web daemon starts, every page address in that process (snapshots and MCP browser alike) passes de-host-services/src/browser_url_policy.rs: import_html_url's URL screen (public http(s) plus the DESIGN_EDITOR_WEB_AI_ENDPOINT_ALLOWLIST), and on a daemon listening on loopback also loopback hosts and file addresses; refused addresses show Blocked. The request body is de_editor_core::browser_live::BrowserSnapshotSpec, one wire shape for both ends. The screen covers the page address, not the page's own subresources.
Live page streams on the web daemon (#324, phases 3a–3b): de-host-services/src/web_browser_live.rs (plus web_browser_live/{plan,source}.rs) gives each web client ONE multiplexed channel at /api/browser/live, so live nodes do not use up the browser's per-origin connection limit. GET is a server-sent event stream (first event hello with the client id, then frame / blocked / ended), POST replaces that client's live set (its selected browser nodes: a node streams only while selected, like pen.dev; a deselected node drops out of the set and stops); the wire shapes are de_editor_core::browser_live_wire. The hub runs de_browser_render::PageStream screencasts, at most WEB_LIVE_MAX_STREAMS (3) per client at WEB_LIVE_MAX_FPS (10), frames up to 2048 px, behind the snapshot's checks (web_browser_snapshot::checked_spec) and browser_url_policy; a set change stops, resizes (set_viewport / set_settings) or opens streams (opens in parallel, no lock held), and a failed spec is not reopened until it changes. The client's connection thread is its writer: it takes a node's frame only right before writing it, so a slow client gets the newest frame and its streams are acked later instead of queueing. A failed write (client gone) stops every stream of that client; the pool's idle reaper does the rest. Nothing on this path takes the daemon's state lock beyond reading the document folder. Both methods first refuse Sec-Fetch-Site: cross-site (origin_guard::fetch_site_allowed; a request without the header passes only on a loopback Host), since a cross-site <script src> GET carries no Origin and would hold one of the MAX_CLIENTS (8) slots. A frame event is written straight to the (buffered) connection: the JPEG is base64-encoded into the writer, never held as a base64 or JSON string (write_frame_event, byte-identical to the serde shape). The streams sit behind a LiveSource / LiveStream trait pair, so the tests run on a fake; the real-Chrome test is --ignored.
Live streams (#324): like pen.dev, a browser node on the canvas plays live only while it is selected (in Preview every page on screen does, see "Preview pages (#324)"), or interactive ( BrowserLiveState::interactive_node, the hook phase 4's interaction mode sets; interactive implies live); every other node keeps the snapshot queue's still. de_editor_core::browser_stream holds the rules: pick_live_pages (selected or interactive nodes on screen, at most MAX_LIVE_PAGES = 3 of a multi-selection, interactive first, then the larger ones on screen), stream_tier (desktop 30 fps, web 10 fps = the daemon's WEB_LIVE_MAX_FPS; frames up to 2048 × 4096), stream_frame_width (on-screen width × DPI in power-of-two steps from 128 with shrink slack, so zooming re-encodes only across a step) and BrowserStreamSpec (the snapshot request's layout plus a quarter-stepped device scale for own tabs, frame size and rate). The "Live pages" switch (Settings ▸ System, BrowserLiveState::live_pages, on by default, desktop ui.json) turns streaming off. widgets/browser_stream_queue.rs is the shared scheduler: hosts pump it after the snapshot queue (its visible set and the painter's on-screen sizes, browser_textures::visible_size) and carry out Start / Update / Stop; a quiet frame walks nothing. A Stop with keep_frame (deselected, scrolled away, window unfocused or hidden) keeps the last frame up as the node's picture until the next still lands (browser_textures::end_live, cleared by install), so the canvas never flashes back to an older still; the setting off, held pages, a lost page or a new document drop it (forget_live). Each streamed node has one stable texture id (browser_textures::live_texture); a host overwrites it with each decoded frame (latest wins, never the data-url cache) and marks it with set_live_frame; the painter draws it when resident, else the still snapshot, and a running stream records its box with canvas_animation_regions::record_live, so the native host keeps a retained canvas layer (rest_animation_layer_wanted takes AnimationRegions::live) and a landed frame repaints only that node's region; NativeBackend::install_live_raster keeps the raster generation for a replacement (bumping it only for a slot's first frame) so the layer's full restore never runs per frame. Desktop (de-host-desktop/src/browser_live_host.rs + browser_live_driver.rs): one driver thread per streamed node owns its de_browser_render::PageStream — on the MCP tool's kept-open tab for the node (PageSessions::is_kept / stream, key browser_stream::node_page_session_key, kept at 1×) when the agent opened one, else on its own tab, moving onto the MCP tab once one appears — decodes each JPEG off the UI thread and wakes the loop with BrowserFrameReady; the next frame is taken only after the UI installed the last (backpressure), frames of a stopped stream are dropped, and focus loss (WindowEvent::Focused), occlusion or a zero-size window pause the streams. Zoom steps retune a running stream (set_settings / set_viewport), never reopen it. Web (de-host-web/src/widget_host/browser_live_stream.rs, pumped from CkInner::repaint after the snapshot pump; transport-free state in widget_host/browser_live_client.rs): one EventSource on the daemon's /api/browser/live, opened once something streams, and the whole set POSTed whenever it changes (each node streams under <node id>#<n>, a Reload takes a new key so the daemon opens a fresh page); a failed set call is retried after 1 s, a broken stream is closed and reopened with backoff (reconnect_delay_ms: RECONNECT_BASE_MS doubling to RECONNECT_MAX_MS) and the next hello re-sends the set; coming back from a hidden or unfocused tab gives every stream a new key (the daemon reopened its pages and counts frames from 1 again); once nothing streams and the daemon holds the empty set the stream closes, so an idle tab holds no client slot. Each frame's JPEG is decoded by createImageBitmap (one decode per node, only the newest frame waits) and installed before the next paint under the node's stable texture id (canvaskit/live_frames.rs, the image cache's liveImages map: never evicted, a lazy texture image when CanvasKit has MakeLazyImageFromTextureSource); images no node shows any more are freed after the pump. A hidden or unfocused tab posts an empty set at once from its visibilitychange / blur listener (a hidden tab paints nothing) and drops frames. The CanvasKit host has no retained canvas layer, so a landed frame repaints the whole canvas.
Interaction mode (#324, phase 4): like pen.dev, a click selects a browser node (selected = live) and a double-click on it enters interaction mode (EditorState::enter_browser_interaction, from either host's canvas press double-click arm; de_editor_core::browser_interact); the node becomes the single selection and BrowserLiveState::interactive_node. Escape, any press off the page (canvas or chrome, so keys stop going to the page once a panel field is clicked) or any selection change leaves it (sync_browser_interaction, once per redraw). Only a browser with an address, its pages allowed and live pages on can be driven. The canvas marks it with a 3 px accent ring just outside the box and hides the resize handles (canvas_selection_overlay::paint_interaction_ring). widgets/browser_interact_flow.rs (BrowserInteraction) is the shared routing: pointer, wheel and key events over the node's box (not over a floating card) become de_editor_core::browser_input::BrowserInputEvents in the page's CSS px (PageMapping: the layout viewport fills the node box; the canvas zoom enters through the screen → document step, a wheel scrolls the page one screen px per screen px), a press on the page keeps the pointer until its release, the page gets its own click counts, and moves / wheel steps coalesce (InputBatch). The canvas never sees those events, so it cannot pan, zoom or drag the node from inside. Desktop: app_handler/browser_interaction_events.rs offers every window event to it first (winit keys in DOM terms: browser_input_keys.rs; IME composition is not enabled for the page yet, keys carry their text; AltGr types), and BrowserLiveHost::send_input hands the batch to the node's driver thread, which wakes its frame wait (PageStream::interrupt_handle) and sends the calls (de_editor_core::browser_input_cdp: Input.dispatchMouseEvent / dispatchKeyEvent with a Windows key code, macOS editing commands such as deleteBackward / selectAll, Input.insertText) on a connection of its own to the stream's tab (PageStream::input → de_browser_render::PageInput, Input.* only; a JavaScript dialog the input opens is answered at once, since a headless tab shows none: an alert / beforeunload is accepted, a confirm / prompt cancelled, so a click never says yes for the user), so it always reaches the page on screen (the MCP tab when the stream shares it). PageInput maps each mouse position from the frame's px to the page's layout-viewport CSS px through the tab's visual viewport (Page.getLayoutMetrics cssVisualViewport, re-read for every press, else at most 100 ms old): a Tablet / Phone tab lays a page without width=device-width out 980 px wide and shows it scaled down, and unmapped clicks landed beside the field they aimed at, so it never took focus (wheel deltas stay in frame px; the --ignored tablet test covers it). No button or key is left held on the page: every input queue (the desktop driver's browser_live_input.rs, the daemon's lane, the web outbox) holds at most MAX_QUEUED_INPUT_EVENTS (4 × MAX_INPUT_EVENTS), past which InputBatch::extend_within cuts it down to the last release of each button or key and every press still waiting for one (browser_input::keep_held_state; a dropped click leaves its release, which a page that never got the press ignores), and input a call did not get through goes back the same way (restore_held_state) and is tried again on a new connection after INPUT_RETRY_AFTER_MS (a call Chrome refuses is skipped, not retried). A stream that ends takes its page with it, so nothing is held there any more. A button still held when the mode ends (or the window loses focus) is released on the page. Rotated or flipped nodes are mapped as upright boxes. The serve-web daemon takes POST /api/browser/input (de-host-services/src/web_browser_input.rs, screened like /api/browser/live): a BrowserInputBatch for one of the client's live keys, checked and coalesced, handed to the live hub (LiveHub is the InputSink, web_browser_live/input.rs): each running stream that took input has a worker thread with its own PageInput on the stream's tab (opened at the first batch, LiveStream::input), the request only queues the batch (429 when a slow page has MAX_QUEUED_INPUT_EVENTS waiting; its releases and still-held presses are queued even then), and the worker goes with the stream's entry when the stream stops or its client leaves. The web editor (de-host-web/src/canvaskit/mount_browser_interaction.rs, window capture listeners; host arm widget_host/browser_interact.rs, double-click in node_drag.rs, sync per repaint) feeds the same BrowserInteraction from DOM pointer, wheel and key events (DOM key / code as they come, a one-character key types it) and stops what the page took from reaching the editor; the hidden IME input is focused while a node is interactive and its compositionend goes to the page as insertText; a window blur releases held buttons. widget_host/browser_input_post.rs posts the queue as a BrowserInputBatch for the node's live key (LiveClientState::input_target, once the daemon holds the set), one request in flight, the rest folded into the next; a refused batch is not sent again (a 404 means the stream and its page are gone, a 429 already queued its releases). The real-Chrome click-and-type tests (Desktop and Tablet layouts) are --ignored (page_input_chrome_tests.rs).
Preview pages (#324): in Preview (▶) a browser node behaves like an embedded page. The preview painter shows its page (live frame, else still; light placeholder) in every pass: de-preview-core's paint_scene, paint_framed (content and pinned strips) and the screen-transition layers run inside widgets/browser_preview.rs::with_clip(<pass clip>), and canvas_browser calls browser_preview::note, which records the node's on-screen box (and the part inside the clip) and notes it for the snapshot and stream queues — but only inside a host's preview frame (browser_preview::begin_frame / end_frame, both hosts' preview paint arm), so capture_preview and tests never move the editor's visible set. Preview has no selection: the stream queue makes every page the preview frame showed a candidate (LiveCandidate::in_preview: live and interactive), at most MAX_LIVE_PAGES = 3, the larger on screen first, at the same tiers; the "Live pages" switch off or held pages leave stills, and leaving the preview stops the streams (their last frame kept until the still lands). Opening the preview ends the canvas interaction mode (sync_browser_interaction). Input needs no double-click: BrowserInteraction's preview_* methods (widgets/browser_interact_preview.rs) route pointer, wheel and keys over any page whose live frame is on screen (PreviewPage::live; a page still loading takes none) through a PageMapping over its box on screen, so the preview's camera or device frame enters through where it was painted and a wheel scrolls one screen px per px; a press keeps the pointer until release and gives that page the keys until a press elsewhere or Escape (a second Escape is the preview's). EditorState::preview_page_layout gates it like can_interact_with_browser. Native: widget_host/browser_preview_input.rs keeps the preview chrome in front (floating chrome, device switcher, browser bar, screen pills, chat) and turns pages off while a deck presents; desktop app_handler/browser_preview_events.rs is offered every window event first and hands the queue to BrowserLiveHost::send_input; sync_preview_pages releases a held page when the preview closes. Web paints and streams preview pages through the same flows; its page input waits for the web live client's /api/browser/input wiring.
MCP browser (#20, de-host-services/src/mcp_serve/browser_tool{,_driver,_canvas,_canvas_shots,_fonts}.rs), pen.dev's tool: action load-page / return-screenshot / return-element / cdp / screenshot-to-canvas / import-to-canvas on a browser node (nodeId, any page; its tab laid out like the node at 1× and following the node's address) or the tool's own page. On a node, load-page and cdp also install what the tab shows as the node's canvas picture (browser_tool_canvas::install_canvas_picture, keyed like the queue's request so it is kept; browser_textures::set_ready_notifier wakes the desktop loop), so the canvas follows the page the agent drives. Tabs stay open between calls (de_browser_render::PageSessions, closed after 5 min unused), so a page loaded once is clicked (cdp Input, DOM, Page, Runtime, Emulation, CSS, Accessibility only) and read later. load-page on a node also writes its url (one undo step); screenshot-to-canvas inserts an image node beside the node; import-to-canvas runs the Chrome extension's snapshot extractor in the page (download and clipboard hand-off caught) and imports it through import_web_snapshot's path. A whole-page capture's root (document.body, 0 tall when every box is position: fixed) is grown, on an axis where the body box is empty, to the viewport and (height) to the bottom of its unclipped, non-fixed descendants; a body with content keeps its box; the lone-child chain of empty, unclipped wrappers above a fixed overlay grows with it (de-html/src/snapshot_root.rs, #323). expandScroll: true lays each vertical scroll container that holds more than it shows out in full for the capture (inline overflow: visible; max-height: none; height: auto, plus flex-shrink: 0; flex-basis: auto in a flex column and bottom: auto when absolutely placed; horizontal scrollers are left alone; restored with the scroll offsets afterwards) and marks the snapshot expandedScroll, which drops the clipped-scroll warning. layout: auto (#292) imports it as auto-layout instead of pinned boxes: HtmlImportOptions::snapshot_auto_layout drives de-html/src/snapshot_auto_layout*.rs, which reads the extractor's per-element layout box (flex direction, wrap, grow, padding, border, gap) and checks every decision against the captured rects (gap = smallest neighbour space, wider spaces become spacer frames, ml-auto a filling one, wrapped lines row frames, overlapping children stay layout: none, overlays stay placed; #298: a box that left no free space or is shrink-wrapped around its widest child hugs, text-align breaks alignment ties, a truncate run the browser cut becomes textOverflow: ellipsis (jian TextNode.text_overflow, scene text_ellipsis: the painter cuts the line with "…" instead of shrinking it, canvas_text_edit::ellipsis_cut; caret geometry keeps the whole line), and the extractor emits a form field's value or placeholder as a text run; #322: a text run sits in the flow by its px line box even when the glyphs overhang it (leading-none), a line whose items overlap (an avatar pulled up over a banner) is a fixed-size layout: none layer in the stack, and so is a flex column's band of overlapping items and a stack item with a cross offset of its own (ml-4 beside full-width siblings); a box a CSS transform moved (transform, v4 translate / scale / rotate) flows by its untransformed layout box, which the extractor adds as flowRect (read with the element's own transform cleared for one measure, its style attribute restored), and is drawn where the transform put it inside a fixed layout: none slot of that box (a rotation or scale is drawn as before); text-transform is baked into the content in both modes, and the extractor finishes running animations before it walks the page; an inline-flex pill hugs its label: a vector icon is spaced by its element box (the inset artwork rides in a frame of that box) and a margin step under FREE_SPACE is a fixed spacer, not free space); a fixed / absolute box the extractor marks escapesClip (an overflow clip lies between it and its containing block: Radix's open submenu inside the menu's overflow-hidden panel) leaves the clipper in both modes and is placed, in front, by the first unclipped element above it (de-html/src/snapshot_escape.rs); folded text segments carry their background-clip: text background, so an inline gradient <span> paints its first stop, and a run one gradient paints whole (or under a clipping block) keeps the gradient as the text node's fill; lucide <svg>s become icon_font nodes in either mode when the host's catalog knows the name (HtmlImportOptions::icon_known, browser_tool_canvas::icon_known). Measured against the browser in de-pen-loader/tests/snapshot_auto_layout.rs. An import then makes the fonts its text names available (#301, browser_tool_fonts.rs): the first non-generic family of each stack goes through load_fonts' Google Fonts path (FontHost::load), one Google lacks through the page's own @font-face files (the extractor's fontFaces, fetched by the page itself with PageOp::FetchFonts, WOFF/WOFF2 decoded by wuff, registered for the session only by FontHost::register_page_faces, never stored; a file whose own family differs renames the family in the imported stacks); the result lists fontsLoaded / fontsMissing. Without a font host (--serve-web) nothing is fetched. A canvas the page cannot read back (a WebGL / WebGPU one without preserveDrawingBuffer reads back blank, a tainted 2D one not at all) is tagged canvasShot with its document rect by the extractor when the host asks (canvasShots: true; the Chrome extension does not, so its import is unchanged), and the import puts a clipped page screenshot in as its image (browser_tool_canvas_shots.rs, #323): de_browser_render::ShotTarget::Rect captures a rect on screen as it stands, scrolls one that fits the viewport into view (two frames, scroll put back), and lays the page out beyond the viewport only for a larger one; at most 16 shots and 24 MiB per import, the first failed shot ends them, and every canvas left with its own read-back is a line in the result's warnings (canvasShots counts captured of tagged). The shot holds whatever the page painted over the canvas too. target: selection is refused (no element picker). Calls block their MCP connection thread, never the UI thread. The in-app design agent does not get the tool.
Script nodes (#19): PenNode::Script(ScriptNode) (kemalcalak/jian#17) embeds a FrameNode (flattened) plus script (the JavaScript source, inline), scriptUri (pen.dev provenance), inputs (number / bool / string values; "$name" binds a variable) and scriptHash. Everything that matches frames takes it through PenNode::Frame(n) | PenNode::Script(ScriptNode { frame: n, .. }) (or PenNode::frame_body()), so it lays out, paints (scene NodeKind::Frame), clips, exports and is culled like a frame holding its generated children; is_container is false so nothing is inserted into it (the batch_design DSL refuses a script as a parent too).
Script nodes, program: the program declares @input name: type = default (de_editor_core::script_inputs), reads pencil.width / pencil.height / pencil.input and returns nodes.
Script nodes, regeneration (de_editor_core::script_regen): a fingerprint (FNV-64 of source, resolved inputs, size) is compared with the saved scriptHash. Inputs resolve under the theme in effect at the node (active theme plus node / ancestor theme scopes); a fixed axis runs at its size, a fill_container axis at the size the host's layout gives it (LaidOutSize; desktop: the canvas scene, file MCP: a layout built only when a script is fill-sized, de_mcp::script_node::ScriptLayout), a hug or unset axis at 0 (a hug box would follow the run's own output; the panel says so). take_script_jobs walks the document only when the document revision, the active theme or the active page moved, caches each source's hash and @input specs, and never hands out a second job for a running node; land_script_output drops a result whose fingerprint the node has moved past, assigns <id>-<n> ids and writes without an undo step (every snapshot already carries its own children and hash); a failed run keeps the last children and is not retried until the fingerprint changes. Variable rename / delete rewrites or freezes input bindings.
Script nodes, engine and hosts: the engine is de_mcp::script_node (QuickJS, feature script: 1 s, 16 MiB, 2000 nodes, seeded Math.random, output through the batch_design node normalizer). The desktop runs jobs on one worker thread (de-host-desktop/src/script_node_host.rs, DesktopEvent::ScriptNodesReady; an engine panic fails the run, not the worker; runs are tagged with the document epoch like the web's, and both hosts land first, then take new jobs against the rebuilt scene); the file-backed MCP servers call regenerate_stale_scripts after each write, and the serve-web daemon runs them after the write with its state lock released, landing under a short re-lock. The CanvasKit web editor has no engine of its own: it sends each job to the daemon's POST /api/scripts/run (de-host-services/src/web_canvas_server/script_routes.rs, a stateless sensitive route that never takes the state lock) and lands the answer on a later frame (de-host-web/src/web_script_runner.rs); both sides spell the request and answer through de_editor_core::script_wire, and the editor tags each request with its document epoch (an answer for a replaced document is dropped), keeps at most three out at once and queues the rest. A page with no daemon (no answer, or a 404 / 405 that is not a script answer) shows script.engineUnreachable as the run status; that is not recorded as a failed run, so the next edit retries it (#219).
Script nodes, measured in a release build (de-mcp/src/script_node_bench_tests.rs, 10k-node document, 20 scripts): 0.13 ms per scan, 0.2 ms with 50 KB sources, 64 ns per unchanged frame, a 2000-node run 17 ms on the worker, landing it 2 ms on the UI thread (plus the normal scene rebuild of a document edit).
Script nodes, panel: the Script section (property_panel_script.rs, core script_edit.rs) shows one row per input (text field PropertyFocus::ScriptInput, boolean checkbox, enum click-to-cycle), Edit script (the source editor with SourceTarget::Script, never sent to the SkSL check) and the run status. pen.dev import inlines the scriptUri file (de-pen-loader/src/pen_dev/script.rs) and keeps input bindings. MCP: batch_design / insert_node (kind: "script" or data) / update_node; guide get_guidelines topic script.
Stroke cap / join / dash (#89) ride on the scene stroke: SceneStroke::style (jian's Copy StrokeStyle, kemalcalak/jian#6) is filled by the scene builder (de-pen-loader/src/layout_scene/stroke.rs, via de_editor_core::fills::render_stroke_style). The canvas painter hands it to the backend with RenderBackend::set_stroke_style per node, dash scaled by zoom, re-sets it after the children for the container stroke and leaves the plain style when the node ends; widget glyphs, generation overlays and the reveal ghost paint plain (canvas_viewport_paint/shapes.rs::unstyled). Wrapping backends must forward set_stroke_style. Backends: de-host-native/src/backend/skia/stroke_style.rs, de-host-web/src/canvaskit/stroke_style.rs + op_ck_bridge.js (which sends the native per-primitive default for an unset field). SVG export writes the same style. MCP: set_node_stroke_style.
Text fill stacks (#179): a text node whose fill_layers is more than one Normal solid (de-editor-ui/src/text_fill_stack.rs::text_needs_fill_stack) paints the whole stack clipped to its glyphs. widgets/canvas_viewport_text_fill.rs pushes a composite layer, paints paint_fill_layers in world space over the node box (solid fallback ink in a band around it for overflowing glyphs), then draws the glyphs as a push_mask_source_layer (DstIn) source; canvas_viewport_text.rs::TextPass splits the text paint into the selection wash, the mask glyphs and the overlay (own-fill runs, IME underline, caret). Greeked text and backends without pixel masks keep the solid fill. PNG export shares the painter; the SVG writer (svg_export/text.rs) puts the glyphs in a <clipPath> and the layers in an isolated group with mix-blend-mode (shader → fallback colour).
Outlined text (#282): TextNode.stroke (kemalcalak/jian#21) outlines the glyphs, never the box. de_editor_ui::text_outline::text_outline_stroke is the one rule for which text is outlined (widget text keeps its stroke as the field border, width > 0); the canvas, SVG and PPTX writers all ask it. The canvas (widgets/canvas_viewport_text_stroke.rs) turns alignment into paint order around the fill: outside = 2× width under it, centre = width over it, inside = 2× width over it cut to the glyphs (TextPass::Coverage mask; centred without pixel masks), through with_stroke_paint so dashes and rich stroke paints work; the dash is set unscaled in doc space, and while editing TextPass::Caret repaints the caret over the outline. Backends implement Painter::stroke_text: native strokes ShapedSegment::outline_path() (jian-skia merges each glyph's overlapping variable-font contours once per cached segment) and the Paragraph path for complex scripts; CanvasKit's bridge (strokeText / strokeShapedText, canvaskit/text.rs) strokes per-character Path.MakeFromText outlines merged with simplify and rasters browser-drawn text with 2D strokeText (variable fonts there keep inner contour lines, as in Chrome's own text-stroke). Exports: SVG writes the text again with no fill (svg_export/text_outline.rs), HTML -webkit-text-stroke (inside centred; outside centred over a background-clip: text fill), PPTX a run <a:ln> (centred). Lint reports a text stroke as Info (detect_text_stroke), never auto-fixed.
Shader textures (#165, de_editor_core::shader_textures): a fill or effect program's children are object (the node: in a fill the fills under it), background (the backdrop, mirrored past the box), an @sdf-tagged child (the signed distance field of the node's silhouette, in an effect of the content's alpha; red = node px, positive inside, green/blue = unit gradient, y down) and images; @mipmap on a child's doc comment mipmaps it. The paint side (widgets/canvas_shader_textures.rs) makes them through jian's Painter shader-texture calls (capture_shader_backdrop, begin/end_shader_texture, release_shader_texture, shader_texture_ready; SDFs stay across frames under a silhouette-keyed id) and binds each child by a texture id in the image-id encoding. Native draws them through redirects on NativeFrameBackend (backend/frame_redirect.rs: the frame canvas points at an offscreen surface; an object pass that samples more than object closes by drawing the program with every child bound, since skia's runtime-shader image filter binds one child) and stores them in NativeBackend::frame_textures (skia/shader_textures.rs, SDF via signed_distance_field on a read-back alpha). The CanvasKit bridge mirrors it (frameTextures, opCkSignedDistanceField). Textures keep the device origin they were made at and bind with the exact device → program mapping; a backdrop capture reads the frame's own surface (not an open redirect's offscreen), so content still inside an open save-layer is missing from it (same gap as web backdrop passes). Known limits: an effect's @sdf is recomputed (GPU read-back) every paint; effects still crop to the node box, where pen.dev runs them over the visual bounds; a fill's object has no shadows. The trait items of these calls expand from a forwarding shader_texture_items! macro in frame_redirect.rs and canvaskit/shader_textures.rs, because both RenderBackend impl blocks sit at the 800-line cap.
Shader effects (#6): PenEffect::Shader { sksl, uniforms, visible } runs an SkSL program whose uniform shader object; child samples the node's own output or whose uniform shader background; child (without object) samples the backdrop inside its silhouette (de_editor_core::shader_effects); an object pass may also sample the backdrop, images and an @sdf child (#165). The loader resolves it to scene Effect::Shader (de-pen-loader/src/effects_shader.rs, size always bound); paint opens backdrop passes after background blur and object passes inside the composite layer (canvas_viewport_paint/shader_effects.rs) through Painter::push_shader_effect_layer. Native runs SkImageFilters::RuntimeShader in device space with a wrapped program that maps back to document px (backend/skia/shader_effect{,_source}.rs); CanvasKit has no such filter, so op_ck_bridge.js redirects an object pass into a reused offscreen surface and snapshots the surface for a backdrop pass. The Effects add menu offers Shader (default pixelate program); its row has eye and remove, and under it the same uniform rows and Code row as a shader fill (#164, ShaderTarget::Effect; every Effects walker steps by effect_block_height).
Instance descendants (#166): a Ref's descendants keys are id paths, a component child id (matched at any depth) or nested/leaf through nested instances, which the resolver forwards into the nested instance's own map (outer wins); an entry with type replaces the whole descendant subtree, a patch with children fills a slot (de-editor-core/src/instance_descendants.rs, used by render, inspector display and detach). instance_anchor.rs resolves a canvas anchor (inst__child, inst__nested__leaf) or an id path to the DescendantTarget a write lands on: descendants[path], or in place inside instance-owned content (a replacement or slot children). Writes go through the panel's instance-write scope or EditorCommand::EditInstanceDescendant (instance_edit.rs: Patch / Replace / InsertChildren / Reset; the first insert into a master node replaces its default children). MCP: batch_design U / R / I and update_node / batch_get take instanceId/childId paths (de-mcp/src/batch_program_instance.rs; R binds instanceId/newId). The layer panel lists an instance's owned content under its row (layer_panel_instance_rows.rs, anchors, never drop targets) and the property panel offers Reset override on an overridden descendant. The pen.dev import keeps typed overrides as replacements.
pen.dev shader paints (#163): a .pen shader fill / effect names a WebGL 1.0 GLSL file next to the document. The import (de-pen-loader/src/pen_dev/shader.rs) reads it once, translates it to SkSL by rewriting the token stream (pen_dev/glsl{,_lex,_bindings}.rs: main + gl_FragColor → half4 main(float2), gl_FragCoord flipped to GL's bottom-left origin, @resolution / @time / @mouse → size / time / mouse, a colour vec3 bound as a float4 hex uniform read through .rgb, texture2D → child .eval, pencil:object / pencil:background → the object / background children in fills and effects, @sdf samplers → @sdf children read through pen_sdf (gradient y flipped to GL), image files → image children with textureSize from an @internal pen_size_<child> uniform; every effect declares object, so it replaces the node as on pen.dev; #165) and, with the sksl-check feature (default; off in the CanvasKit web build and the CLI), drops a program Skia will not compile. A preprocessor runs first (pen_dev/glsl_preprocess.rs: #if / #ifdef / #elif / #else, object- and function-like #define, #undef, #error; #165), discard returns transparent (from a helper through a pen_Discard flag), and the other WebGL 1.0 built-ins map to their fragment values. int / ivec uniforms stay SkSL ints (native binds them rounded through shader_children::set_uniform, CanvasKit casts floats); a bool becomes an int read through bool() with @bool added to its doc comment, which the panel shows as a checkbox (UniformKind::Bool, ToggleShaderUniform). A $variable uniform stays a reference ("u_x": "$name") that variables_resolve/shader_uniforms.rs resolves per theme like fill colours (the panel shows the resolved value); a chain or a kind mismatch is resolved once and reported as shader uniform variable (fixed value). Missing values take the GLSL @default. Failures are dropped and reported (shader fill (GLSL file missing | unsupported GLSL | unsupported texture | SkSL compile failed)).
Per-NodeKind section filtering
SectionCapabilities::for_kind(NodeKind) returns which sections paint for the current selection (Frame omits Stroke, Text omits Effects/Export, etc.). The returned VisibleSections is threaded through every paint routine and both layout walkers so hidden sections cause subsequent rects to shift up by the right amount.
File split
The panel is a property_panel_*.rs family in de-editor-ui/src/widgets/ (plus the property_panel/, property_panel_snapshot/, and property_panel_tests/ directories) — one file per section or concern, all under the 800-line ceiling. The load-bearing entries:
property_panel.rs—PropertyPanel, snapshot,SectionCapabilities, hit-test entry points.property_panel_sections.rs— section paint routines +PropertyLabels+EditContext.property_panel_inputs.rs— shared paint helpers (label / divider / input variants), layout constants,format_color_hex,to_jian_color.property_panel_layout.rs—VisibleSections/SizeFlags/fill_body_height+ the two layout walkers.property_panel_fill.rs(+_fill_body,_fill_image_body,_fill_picker,_fill_menu) — fill-type label table, picker overlay, the single fill row, body variants, the⋯menu.property_panel_section_tops.rs—section_tops, the shared section origins every y-walk uses.property_panel_dispatch.rs(+_support),property_panel_commit.rs,property_panel_layout_ops.rs— the host-shared action dispatch / draft lifecycle / layout writers; see "Shared host logic" below. These are not paint code and are called by both hosts.
Everything else (_code*, _effects, _export, _stroke, _text, _typography, _image_*, _instance, _interactions, _icon, _compositing, …) follows the same one-concern-per-file rule.
PropertyLabels::for_document(doc) resolves every section title (位置/弹性布局/尺寸/图层/填充/描边/效果/导出), the Code view title, the 创建组件 button, and the size checkboxes (填充宽/高 / 适应宽/高 / 裁剪内容) via Document::t, falling back to English when a key isn't in the TS locale table.
RenderBackend trait
fill_rect / stroke_rect / draw_text / clip_rect
save / restore / translate
stroke_line / fill_round_rect / stroke_round_rect / stroke_svg_path
resize / dpi_scalestroke_svg_path parses lucide d-strings via skia_safe::utils::parse_path::from_svg. PaintCap::Round + PaintJoin::Round to match lucide's stroke style.
Native widget_host layout
crates/de-host-native/src/widget_host.rs is a spine (~690 lines) holding the public surface — the WidgetHostNative struct, CursorHint / PanelResizeKind enums, the constructor and small accessors (set_now_ms / chat_focused / next_animation_deadline_ms) — plus the mod declarations for ~130 sibling submodules under widget_host/. Its web twin, de-host-web/src/widget_host.rs (~500 lines), has the same shape. The drag-state structs are not declared here any more: both hosts share them from de_editor_core::host_drag_state.
The directory is too large to table exhaustively; the naming scheme tells you where to look:
| Pattern | Contents |
press.rs + press_ctx.rs + press_*_tiers.rs | The apply_press hit-test ladder — spine, per-event scratch struct, and the ordered tier bodies (see "Hit-test order") |
input.rs + cursor_move_ctx.rs + cursor_move_*.rs | The apply_cursor_move hover ladder, same spine/ctx/tier shape (native only; web's cursor path lives in cursor_input.rs) |
keyboard.rs + keyboard_*.rs | Key dispatch split by concern — caret, clipboard, delete, escape, send, IME |
*_dispatch.rs | Thin platform arms over the shared de-editor-ui dispatch flows (property, image panel, settings, font picker) |
paint.rs, paint_pan_cache.rs, scene_state.rs | The composition pass and its caches |
host_lifecycle.rs, host_requests.rs | Host boot / teardown and outbound request plumbing carved off the spine |
geometry.rs, overlay_rects.rs, helpers.rs | Thin forwarders to the shared geometry in de-editor-ui plus the few genuinely platform-specific rects |
*_tests.rs / *_tests/ | Per-concern test siblings; a directory means the tests themselves outgrew the cap |
NativeFrameBackend (the RenderBackend impl over NativeBackend + &Canvas) moved out of widget_host/ — it lives in de-host-native/src/backend/frame_backend.rs alongside frame_offscreen.rs and the skia/ split.
The three input ladders
apply_cursor_move (native) and both hosts' apply_press used to be single 900–1150 line methods. Each is now a short spine that calls Option-returning tier helpers in ascending priority order, with per-event scratch state in a PressCtx / CursorMoveCtx struct instead of a long argument list. A tier returning Some(consumed) ends the event; None falls through to the next tier.
The call order in the spine is the behaviour. The decomposition was verified mechanically — every tier body is byte-identical to its original line range and the spines invoke tiers in strictly ascending original order — so reordering a call is a behaviour change, not a refactor. Read "Hit-test order" below before touching either spine.
All struct fields and intra-module helpers are scoped pub(in crate::widget_host) so submodule impl blocks can reach them while the public surface stays minimal.
Keyboard shortcuts
Native (design-editor) + web (shell-web) both dispatch the following P1 keyboard shortcuts through WidgetHostNative / WidgetHost methods. The desktop runner reads modifier state from WindowEvent::ModifiersChanged (zoom_modifier = Cmd/Ctrl, shift_modifier = Shift); the web shell reads evt.meta_key() || evt.ctrl_key() and evt.shift_key() from KeyboardEvent.
| Key | Method | Behaviour (TS parity: use-edit-shortcuts.ts + use-clipboard-shortcuts.ts) |
Backspace | apply_backspace | Pops a char when an input is focused; else delete_selected(). |
Delete | apply_delete | delete_selected() regardless of which non-text overlay is open. |
Cmd/Ctrl+D | apply_duplicate | duplicate_selected(&mut next_node_id, 10.0) and selects the clone. |
ArrowUp/Down/Left/Right | apply_nudge(dx, dy) | Translates selection by 1 doc px, or 10 with Shift. |
[ | apply_reorder(Down) | Swap with previous sibling (back in z-order). |
] | apply_reorder(Up) | Swap with next sibling (forward in z-order). |
Shift+H / Shift+V | apply_flip (web: apply_flip_shortcut) | flip_selection: toggle flip_x / flip_y on every editable selected node, one undo step. Matched before the bare-letter tool router. |
Escape | apply_escape | One layer per press, in priority order: property-focus → locale picker → shape picker → fill-type picker → fill ⋯ menu → chat focus → selection. |
Enter | apply_send | Commits property edit or sends chat. |
Cmd/Ctrl+[ / ] (Preview) | preview_history_step | Back / forward through the preview's browsing history (#153); the mouse Back / Forward buttons do the same. Bare [ / ] stay z-order reorder. |
The shared implementation of these lives in de_editor_core::host_keyboard_transitions + host_escape_transitions; the host keyboard*.rs files are the platform arms.
Browsing the preview (#153)
A routed (APP MODE) preview browses like a website. de-preview-core/src/browse.rs keeps browser-style history over every committed screen switch (whatever verb caused it), the address (page title + route), the clickable under the pointer (pointer cursor, derived hover / pressed state) and section links: a scroll_to aimed at the page itself becomes a PageScrollRequest the host applies to its device-frame scroll or Canvas pan. The browser bar widget is de-editor-ui/src/widgets/preview_browser_bar.rs (under the device switcher; the screen pills sit below it); its paint / press / hover / release flow, the cursor and the scroll / pan math are host-shared in de-preview-core/src/browse_chrome.rs, and the host arms are widget_host/preview_browser.rs in both hosts. Preview entry's auto-wire also runs de_orchestrator::wire_screen_navigation::wire_web_nav_links (header / footer links → pages or same-page sections), desktop only like the rest of auto-wire.
Entry and site (#223): Preview opens on the top-level board holding the selection (an instance child resolves to its instance's board), else the top-left-most screen-like board (de_editor_core::preview_screen_set::preview_entry_root; every host passes it to PreviewSession::enter_with_host_motion_preference, MCP capture_preview takes entryNodeId). In APP MODE that board is re-rooted as the entry (session_entry::reroot_projection) so history starts there; in workbench mode it is the framed root (present::framed_scene_root). The routed boards are the entry's site, preview_screen_set: same width, instance or not (and the same theme for instances), sharing the entry's first-child header component, or screen-like boards of that width when it has none. Auto-wire expands instances first and runs wire_preview_screens on the clone, filling gaps around authored markers. Headers / footers are also found by place (first child ≤ 200 px with ≥ 2 texts, last child with ≥ 2 texts), and labels match through de_orchestrator::label_match (case + generic-diacritic folding, exact > word / prefix > stem or spaceless-script containment, strongest unique wins, page before section). Only the site's boards are link targets; tab bars keep the generation pass's strict first-match rule; routes are named from the board's name in any script (screen_marker_edit::unique_route_path, shared with the panel); with no selection an authored / frame is the entry. No new rule reads a name's language (the older English surface words still apply alongside). The web host has no auto-wire: there the selection only picks the framed root or an authored screen as entry. The Interactions section's "+" offers Mark as screen on an unmarked top-level frame; a marked one shows its route plus Set as start screen / Remove screen (screen_marker_edit, MCP set_screen).
Pointer motion, Present and slide transitions (#155 #157 #158)
- Pointer motion (#155):
animationstriggers aremount/inView/hover/tap(jianMotionTrigger, kemalcalak/jian#10).de-preview-core/src/motion_pointer.rsplays a hover / tap animation forward while the pointer is over / pressing the node or a descendant and back on leave / release (from wherever it is), synced after each pointer event and on paint.width/heightare motion properties: motion tracks for them (PreviewAnimationState::start_motion) interpolate continuously and invalidatePaintOnly(the painted box resizes; children keep their layout), unlike the action layer's discrete relayout. HTML export plays pointer animations on:hover/:active. - Animations through HTML and decks (#245): the HTML importer turns two-stop
@keyframesover opacity / transform intomountanimations (de-html/src/mapper_motion.rs; atransform-originscale becomes scale plus a centre-shift translate, because nodes scale about their centre; CSSinfiniteisde_util::motion::INFINITE_ITERATIONS); anything else imports static withmotion.keyframes_static. Present replays the arriving slide'smountanimations (PreviewSession::replay_board_mount_animations, called by both hosts' slideshow step). Deck exports read motion off the document (de-host-services/src/deck_motion.rs): the slideshow HTML wraps each animated node in adata-de-motion-nodebox animated under.slide.is-current(opacity / translate / scale / rotation only), the PPTX writes entrance effects (export_pptx/motion.rs, preset table there). - Present (#157): Cmd/Ctrl+Enter (
toggle_present,widget_host/preview_present.rson both hosts; macOS View ▸ Present; File menu ▸ Present on every host, chord spelled per platform byfile_menu_paint::platform_chord) setspreview.present, soslideshow_for_documentpresents the active page's top-level frames whatever the scenario; the same chord leaves. - Slide transitions (#158):
slideTransition(none / fade / slide / push, duration, easing) on a slide's node base. A step starts aSlideTransitionRun(de-editor-core/src/slide_transition.rs: the arriving slide's on next, the left slide's mirrored on previous);PreviewSession::paint_slide_transition(de-preview-core/src/slide_paint.rs) paints both slides fitted like the slideshow camera. Authored in the Slides panel's Transition row (selected slides, else the deck; one undo step), whose label line carries a duration stepper (#190,SlidesPanelTarget::TransitionDuration,step_slides_transition_duration: 100 ms steps, 100 ms – 5 s, shown while every target shares one kind other than none), and over MCP (set_slide_transition). The deck exports play it (#245): the slideshow HTML's player runs the same layers in the browser, the PPTX writesp:fade/p:cover/p:pushat the nearest PowerPoint speed.
Desktop binary (design-editor/)
crates/design-editor/src/main.rs is the production desktop entry. It owns the winit ApplicationHandler, opens a GL window via SharedSkiaContext::new_desktop, and dispatches every WindowEvent onto WidgetHostNative::apply_*. Behaviour:
- DPI scale via
canvas.scale((dpi, dpi))per frame (preceded byreset_matrix()so it doesn't compound) - LOGICAL viewport sizes (physical / dpi)
- Cursor position cached on
CursorMoved, dispatched onMouseInput - Wheel and trackpad both route through
de_editor_core::host_wheel_routing(#303, Figma's mapping): no modifier pans (Shift = horizontal), Cmd/Ctrl zooms;LineDeltabecomes pixels first (line_delta_px: Windows reads the system lines per notch, 100 px at the default 3; macOS 40 px per line).PinchGesturezooms - Cursor flips to
EwResizewhen over a panel-resize gutter (host.panel_resize_hover) WaitUntil(host.next_animation_deadline_ms())pumps the caret-blink redraw
Native font path bypasses jian-skia's textlayout (which builds a fresh FontCollection per call → 605ms chrome frame): NativeBackend caches a Roboto Typeface + per-codepoint system fonts (resolved via FontMgr::match_family_style_character, cached per i32) so multi-script chrome (한국어 / हिन्दी / ไทย / Tiếng Việt) renders against the right font. draw_text paints each run as the per-segment glyph blobs FontResolver::shape_run caches (kerned, #197).
Run: cargo run -p design-editor --release.
Web runner (shell-web/)
Single mount(canvas_id) entry point exposed to JS. Wires DOM listeners on the canvas + window:
- mousedown/mousemove/mouseup → apply_press / apply_cursor_move / apply_release
- wheel → apply_wheel
- keydown (window) → apply_text / apply_backspace / apply_send
- IME composition (hidden textarea) → apply_ime stubs
Skia surface: wasm32-unknown-unknown raster (N32_PREMUL) + put_image_data. Fonts: embedded Roboto-Regular.ttf (~35 KB) + NotoSansCJK-Subset.ttc (~8.7 KB) loaded via FontMgr::custom_empty().new_from_data.
Build: needs EMSDK env var pointing at an emsdk install (brew emscripten won't work — needs the real emsdk layout $EMSDK/upstream/emscripten/llvm/bin/clang++). Once set: tools/check-wasm-bundle.sh runs the full bundle gate (cargo → wasm-bindgen → wasm-opt -Oz, asserts 0 env.* imports + ≤1 MiB gzip).
Smoke: crates/design-editor-shell-web/smoke/step-1b.html — start python3 -m http.server 8000 from crates/design-editor-shell-web/ and open http://localhost:8000/smoke/step-1b.html.
Hit-test order
This section is the canonical statement of the ladder — the tier modules point back here by name. Hit-test runs in REVERSE paint order so the topmost overlay always wins, and each spine's call order encodes it literally.
apply_press (native widget_host/press.rs) — the prelude first blur-commits an in-flight layer rename and text edit, with one exception: a press inside the edited text node places the caret instead of committing (TS textarea parity). Then:
press_topmost_overlay_tiers— modals, floating panels, context menus- commit-on-blur for property-panel inputs + the variable-row inline editor, then resolve Git-panel / chat-model-picker ownership (the floating Git panel paints over the right rail, so every rail tier below skips a click inside its rect)
press_menu_modal_tiers— shape picker; file / export / figma modals; import + locale dropdownspress_rail_overlay_tiers— image-fill popover, StatusBar, resize gutter, the model-picker slice over the floating chromepress_chrome_tier— the floating chrome (file pill + canvas action group) and its blank-press paddingpress_preview_tier— Preview (Play) mode swallows everything belowpress_property_overlay_tiers→press_panel_dispatch_tiers→press_property_panel_tierpress_git_and_chat_tierspress_toolbar_tierspress_layer_and_click_tiers— LayerPanel rows / Page rows + chat-defocuspress_canvas_tier→press_canvas_select_tier— empty-canvas press clears selection (collapsing the right rail) and starts the pan / marquee drag
Web's apply_press runs the same order with two extra tiers split out (press_import_locale_tiers, press_variables_tiers, press_font_and_picker_tiers) because its overlay set differs; the relative priority is identical.
apply_cursor_move (native widget_host/input.rs) runs its own 10-tier ladder: modals → floating panels → a live rail-resize drag → in-flight property/text/crop/node/pen drags (pointer capture) → menus + Git panel → property-panel popovers → StatusBar/align/model-picker → floating chrome → the left rail's slides tab → the single-shot chat probe (deliberately non-consuming, so the late drags still run) → late pointer-capture drags → base hover. The rail resize sits with the early pointer-capture drags rather than the late ones because its pointer travels back over the rail it is resizing, where the slides-tab hover tier would otherwise claim the move — which is exactly why the left rail could once be dragged wider but never narrower. It keeps one owned PropertyPanel snapshot per event in CursorMoveCtx::property_panel_probe so the expensive snapshot/i18n work happens at most once.
Coordinate invariant
There is no title bar (#30), and since editor v3 (#86) the canvas is full-bleed: outside the workspace dock canvas_region is the whole window and never changes when a panel opens, so artboards stay put. Everything floats over it: the window controls and file pill top-left, the action group top-right, the panel toggle + tool rail on the left edge, the zoom pill bottom-right, the left card (layer_panel_rect = floating_panels::left_card_rect) and the properties card (property_panel_rect = right_card_rect, from under the action group to just above the zoom pill). over_canvas excludes the cards and the toggle (over_floating_card), so no press, hover, wheel or drop reaches the canvas through them. The rest of the chrome (file pill, action group, toggle, tool rail, zoom pill) is over_floating_chrome; the shader mouse uniform reads the pointer only when it is over the canvas, off both, and off the host's chat rect (#141). A press on the canvas's top band where no chrome or node sits drags the window (WidgetHostNative::editor_window_drag_at).
The left card opens and closes with a 220 ms ease-out (EditorUiState::toggle_panel_animated, used by the toggle, ⌘\ and File ▸ Show / Hide panel). sidebar_open flips at once; the hosts tick panel_motion once per paint and every rect reads panel_reveal, so paint and hit-test agree mid-motion. While it runs the chat is the composer pill travelling between the bottom-centre spot and the card's composer slot (pinned_chat → composer_pill); it pins into the card once the card lands. A direct write to sidebar_open stays instant.
The rail's tab row (Agent · Layers · Components · Images · Slides) picks what fills rail_body_rect; slides_panel_flow::body_tab is the one answer, and the layer tree only takes input while Layers is on show (layers_tab_active). Components is the UIKit browser (component_browser_panel.rs, rail mode only — Cmd+Shift+K opens the tab with its search focused). Images (images_tab.rs, core document_images.rs) lists the page's image nodes; a thumbnail selects and frames its node, and Search / Generate open the property panel's image popovers on the selected image node, or on a placeholder inserted for them — there is no second search pipeline.
Every input path that reasons about the canvas region MUST derive its rects from canvas_region(…), and every path that reasons about a panel from layer_panel_rect / property_panel_rect. Never reuse layer_panel_width / property_panel_width as an edge for hit-test — the cards are inset and slide. Sites that proved this rule by violating it: over_canvas, apply_wheel cursor offset, toolbar hit rect in apply_press / apply_click. Web apply_wheel zoom anchor + toolbar_rect() follow the same rule.
The invariant now has one implementation: de-editor-ui/src/widgets/host_canvas_geometry.rs owns canvas_origin / canvas_region / canvas_rect / over_canvas / canvas_doc_point[_unclamped] / canvas_centre_doc_point / layer_panel_rect / left_rail_rect / property_panel_rect / chrome_layout / chrome_hit_at / window_drag_band_at / toolbar_rect* / status_bar_rect / marquee_rect / path_anchor_hit, and each host's widget_host/geometry.rs is a thin forwarder. Both hosts previously carried byte-identical copies of this math — exactly the drift the invariant exists to prevent. Sixteen inline screen-to-doc conversions were routed through the shared helper as part of the same pass; do not add a seventeenth by hand.
Settings modal (Cmd+,)
agent_settings_panel.rs + its tab modules render a modal (at most 960×760, shrunk to fit) opened from the File menu footer or Cmd+,. Sidebar nav: Agents / MCP / Images / Fonts / System. The body scrolls; the modal paints last (over a dim scrim) so it covers every other widget.
- Agents (#26) — a list on the left and the selected entry's detail on the right (
agent_settings_agents.rsspine;_agents_list,_api_detail+_api_preset_menu,_cli_detail,_acp_detail, shared_detail_chrome). The list: API providers (saved ones plus the featured presets not set up yet) closed by "Add custom endpoint", then the agents on this machine (CLI agents, ACP agents) closed by "Add ACP agent"; the web build lists API providers only. Selection isAgentSettings::agents_selected(by id; read it throughresolved_agents_entry). API detail: API format, base URL, masked key with a reveal eye, a model checklist fed by the catalog (free text when the endpoint cannot list models), Fetch models / Save. CLI detail: probe status with Check again, the agent's discovered models as a checklist whose unticked ids persist ascli_hidden_modelsand leave the chat picker, Connect / Disconnect. ACP detail: preset + connection segments, command/args or URL, install hint, environment. Host tests press controls throughAgentSettingsPanel::point_for_hitrather than copied coordinates. - MCP — server status card with port input + Start/Stop button, then a grid of 7 CLI integration toggles (Claude Code / Codex / OpenCode / Kiro / GitHub Copilot / Antigravity / Grok Build). Port input is editable (see "Settings input editing" below).
- Images — Image Search Ready/Not-configured indicator + collapsible Advanced section (Openverse OAuth Client ID / Secret + Register link + Test button), then Image Generation section with
+ Addempty state. - System — Appearance, auto-update switch with the release probe's status line, Experimental, Pencil cursor (the AI generation overlay), Pencil smoothing (#88, the Pencil tool's fit tolerance). When a newer release is known the auto-update row carries an Update button (desktop only); it opens the in-app update modal (#111,
update_modal.rs, stateeditor_ui_state/update_state.rs), which the desktop host drives throughupdate_install.rs(download with progress, SHA-256 check againstSHA256SUMS.txt, stage) andupdate_install_platform.rs(macOS bundle swap / Windows silent NSIS / Linux binary rename fromdesign-editor-linux-x86_64.tar.gz, #51, then relaunch).
agent_settings_i18n.rs is a thin widget-layer adapter over the shared de-i18n lookup. All settings.* strings (settings.tab.* / settings.agents.* / settings.mcp.* / settings.images.* / settings.system.* / settings.provider.*) live directly in every one of the 15 canonical locale tables.
Settings input editing
SettingsFocus { McpPort } is to settings inputs what PropertyFocus is to property-panel inputs. Click on the port field → AgentSettingsHit::FocusMcpPort → agent_settings.focus = Some(McpPort) + EditorUiState.settings_input: TextInputState seeded from current port. apply_text / apply_backspace / caret movement / select-all route through the shared text-input state FIRST (swallowing every keystroke so non-digit chars don't leak into chat / rename / text-edit). apply_send commits, parsing u16 and clamping ≥1024. apply_escape clears focus and the shared input. Close / Outside / SelectTab / re-Focus all commit any pending draft first so a typed value isn't silently lost.
Mirrored on native (widget_host/property_dispatch.rs::commit_settings_focus_if_any) and web (widget_host/keyboard.rs::commit_settings_focus).
Pen tool
document/pen.rs builds a NodeKind::Path with points: Vec<Point2D> (doc coords). State on Document.ui:
pen_in_progress: Option<NodeId>— the path being authored (None when idle).pen_cursor_doc: Option<Point2D>— last cursor doc coord, drives the rubber-band preview from the last anchor to the cursor while authoring.pending_pen_history: Option<DocumentSnapshot>— snapshot captured BEFOREstart_pen_pathmutates the tree. Pushed onto the undo stack only when the path commits with ≥ 2 anchors; a lone-anchor (invisible) path is stripped without polluting history.
Press while tool == Pen calls start_pen_path or add_pen_point depending on pen_in_progress. Enter / Escape / tool change → finish_pen_path. Canvas paints the path through node.points as a polyline, plus a dashed preview line from points.last() to pen_cursor_doc while authoring.
Pencil tool (#88)
Tool::Pencil (rail button after Pen, Shift+P). A press starts ui.pencil_stroke (UI state only; the document is untouched during the drag), cursor moves append samples at least 1 screen px apart, and the release runs de_editor_core::pencil_fit::fit_freehand_path (Schneider least-squares bezier fit) at editor_ui.pencil_smoothing.tolerance_screen_px() / zoom, then inserts one ordinary PenNode::Path with anchors and pushes one history entry. A click without a drag inserts nothing. Escape mid-drag discards the stroke (host_escape_transitions::escape_pencil_stroke, after the rename / text-edit rungs and before the pen rung in both ladders, #141). Tool switch and undo / redo drop an in-flight stroke; a native wheel / pan cancel commits it. The live preview is canvas_path_overlay::paint_pencil_preview. Host arms: widget_host/pencil_press.rs in both hosts.
Color picker (HSV)
document/color_picker.rs + widgets/color_picker.rs. State: ColorPickerState { target (Fill|Stroke), hue, sat, val, drag (None|SvBox|HueSlider), anchor_y }. Open via Cmd-Shift-C or fill/stroke swatch click. HSV stays anchored across the RGB-rounding cycle — dragging the hue slider rewrites only hue and reconstructs RGB from the cached (hue, sat, val), so the saturation+value crosshair doesn't visibly snap as round-trip rounding pulls a slightly different RGB out of the same HSV.
Hit-test order on the picker: hex input row → SvBox → HueSlider → close X. Outside-click closes silently. apply_cursor_move reads state.drag to feed live SvBox / HueSlider updates.
Layer panel right-click + drag-into-container
widgets/layer_context_menu.rs paints a 200×N overlay on right-click of a layer row or page tab. Rows are gated on LayerContextTarget:
- Layer: Rename / Duplicate / Delete / Group / Ungroup / Lock / Hide (most rows route to dedicated
Document::*_selectedops; Group/Ungroup live indocument/grouping.rs). - Page: Rename / Duplicate / Delete (
document/page_mutators.rs).
Cursor-move feeds hovered_row so the menu highlights the row under the cursor. Outside-click closes silently. The menu paints AFTER the layer panel and BEFORE the settings modal so it sits below modals but above everything else.
Layer-panel drag now supports cross-parent reparenting: a drag whose drop-target falls inside a container row (Frame / Group with children) reparents the dragged node under that container instead of just reordering siblings. The walker in widgets/layer_panel_walkers.rs returns a DropTarget { parent, before, into_container } triple so the commit step can call move_into_container vs reorder_in_place.
Performance gotchas
- Native chrome paint: ~30 text draws × jian-skia textlayout's per-call
FontCollection::new()= ~600ms/frame. Fix is the cached typeface path described above. Don't add new draw_text calls without cache awareness. - skia canvas matrix is stateful across
with_frame—canvas.reset_matrix()before applying DPI scale each frame, otherwise scale compounds. - jian-skia's
DrawOp::Rect/DrawOp::Textgo through its image-cached path.stroke_line/fill_round_rect/stroke_round_rect/stroke_svg_path/fill_svg_pathbypass jian and call skia canvas directly (necessary because jian doesn't have those DrawOp variants).
Hot-path optimizations (v0.8.0)
- History via VecDeque (
document/mutators.rs) —pop_front+push_backcapped at 100 entries; the oldVec::remove(0)was O(n) on every commit past the cap. Document::treturns&'static str— every locale value is a string literal, so chrome paint stores&'static strinstead of cloning aStringper frame.PropertyLabelsis aCopystruct of static slices; widget builders propagate the'staticlifetime so no per-paint allocations happen for labels.- Viewport culling (
widgets/canvas_viewport.rs) —paint_nodetakes acull: Rect(canvas region + 64 px stroke/handle margin). Leaf nodes outside the cull skip paint entirely; containers always recurse so off-screen-parent / on-screen-child still renders. - Redraw scheduler (
design-editor/src/main.rs) —request_redraw(dirty: bool)+ aprepare_redrawstep that skips paint when only a tracked redraw fired and no visible state changed (kills the first-click chip flicker because macOS GL swap chain didn't perfectly hidecanvas.clear(BLACK)between same-output frames). - Cursor-move coalescing —
apply_cursor_movecached aspending_cursor_move, drained onRedrawRequestedAND right beforeapply_press/apply_release/apply_right_press(so the final drag-end frame isn't dropped). Without the press-time drain a fast drag-release could fire press before the queued cursor-move and the release saw stale hover state. - Font cache prewarm (
de-host-native/src/backend/skia.rs) —NativeBackend::newwalksPREWARM_CJK_CODEPOINTS(~50 chars covering every CJK glyph used in the chrome + settings modal) throughFontMgr::match_family_style_characterat startup. Without this the first cross-tab paint stutters because each unseen CJK char triggers a synchronous system font scan.
Shared host logic (the native↔web widget_host fork is single-sourced)
de-host-native/src/widget_host/ and de-host-web/src/widget_host/ used to be a copy-pasted twin pair, and the copies had silently drifted apart — web's Interactions actions were dead no-ops, native's shift-drag skipped the undo snapshot, native painted two variables menus at once, web's marquee release never synced the entered container, and so on. Every one of those was a real user-visible bug found only because the twins were diffed. The fork is now single-sourced.
Before adding logic to either host, check whether it belongs in one of these. A host file should be a thin platform arm: hit-test, call the shared flow, run the platform tail. Genuinely platform-specific behaviour stays host-side with a comment saying why.
Pure state transitions — no widget types, wasm32-clean — live in de-editor-core/src/:
| Module | Owns |
host_ui_transitions.rs | Chrome-state transitions (the byte-identical twin blocks) |
host_press_transitions.rs | Press-path chrome transitions |
host_keyboard_transitions.rs | Keyboard-driven editor-state transitions |
host_escape_transitions.rs | The Escape ladder — exactly one layer dismissed per press |
host_drag_state.rs | The transient pointer-drag structs both spines used to declare separately |
host_drag_transitions.rs | Canvas press/drag state transitions |
host_variables_transitions.rs | VariablesPanel press arms |
host_variables_commit.rs | VariablesPanel draft commits (header renames + per-row Name/Number/String/Color drafts) |
host_settings_commit.rs | Settings-modal draft commit |
host_image_panel_transitions.rs | Image-node panel transitions (Search / Generate popovers) |
host_preset_name_draft.rs | The variables preset "save as name" input |
host_wheel_routing.rs | Wheel / trackpad routing (pan vs zoom, Shift axis) + line → px per notch (#303) |
request_snapshot.rs | narrowed_snapshot — see below |
agent_reveals.rs | Before/after node-id diff + staggered reveal bookkeeping for freshly inserted subtrees; one batch's queue is capped at ~6 s (REVEAL_QUEUE_CAP_MS, #17) |
agent_indicators_wake.rs | reveal_wake: the generation overlay's wake needs split by purpose (animating, next start, settle, erase frame) + the per-thread burst-smoothing switch |
Widget-typed shared logic lives in de-editor-ui/src/widgets/:
| Module | Owns |
press_flow.rs | Press dispatch — hosts map a hit-test result through it and run only the tail |
chat_click_flow.rs | Chat-panel click dispatch (apply_chat_hit) |
property_panel_dispatch.rs + _support.rs | PropertyPanel action dispatch (was two ~500-line near-verbatim copies) |
property_panel_commit.rs | Both ends of the PropertyPanel draft lifecycle (property_focus_initial + commit) |
property_panel_layout_ops.rs | Layout / sizing / typography writers behind the button groups |
drag_flow.rs | Canvas node-drag flow |
marquee_flow.rs | Marquee-release commit (screen→doc rect walk + additive/replace selection) |
image_crop_flow.rs | Figma-style image-fill crop gesture |
image_popover_input_flow.rs | Mouse selection in the image Search / Generate text inputs |
scroll_flow.rs | Panel wheel / trackpad-pan scrolling |
cursor_hover_flow.rs | Cursor-move hover resolution |
missing_fonts_flow.rs | Missing-font prompt: scroll, press dispatch, detection/refresh bookkeeping |
variables_panel_geometry_flow.rs | Floating VariablesPanel placement + resize clamping |
agent_settings_press_flow.rs + _entries.rs + _focus.rs | Agent-settings modal press dispatch, list-entry arms, and input focus seeding |
host_canvas_geometry.rs | The coordinate invariant (see "Hit-test order") |
host_overlay_geometry.rs | On-screen rects for dropdowns, the three draggable floating panels, StatusBar actions |
host_frame_bookkeeping.rs | Per-frame work both spines do around paint (cache owner rotation, layout transitions, animation deadlines) |
menu_paint.rs | Shared dropdown row chrome (hover tint, hit rect, divider) for the file menu |
settings_form.rs | Shared card-form chrome for the Agent settings sections |
canvas_generation_visibility.rs | What the last canvas frame showed of the generation overlay; generation_deadline_ms keeps 60 fps only for that (#17), both hosts |
test_capture_backend.rs | Test-only RenderBackend stub recording fill_round_rect calls |
de-editor-ui/src/accessibility_regions.rs (crate root, not widgets/) single-sources the a11y region walk behind native's widget_host/a11y.rs and web's a11y_bridge.rs.
Outside the widget hosts the same rule applies: settings payload serde lives in de-editor-host-core/src/settings_payload.rs, image generate / search in de-host-services/src/web_image_{generate,search}.rs, and the --mcp / --mcp-http / --serve-web argv dispatch in de_host_services::cli_modes (shared by de-host-desktop and de-host-web-server, which differ only in what an unknown mode means); every mode runs on its own 64 MiB-stack thread (cli_modes::on_mode_stack), because a debug daemon outgrows Windows' 1 MiB main thread (#227). Desktop no longer carries drifted copies of any of them.
EditorUiState split + narrowed snapshots
de-editor-core/src/editor_ui_state.rs is a spine over seven siblings (chrome, defaults, git_panel, groups, methods, pickers, tests), with re-exports keeping every import path stable. Three measured field clusters became substructs in editor_ui_state/groups.rs — PreviewState, SizeToggleState, DesignMdPanelState (192 → 176 flat fields). Larger clusters were rejected on workspace touch-count, so don't group further without measuring.
request_snapshot::narrowed_snapshot(&mut EditorState) is the sanctioned way to hand editor state to a worker thread. The MCP request path, the chat-launch path, and the desktop design pump's per-apply-ack all use it: it drops chat / codegen / theme_presets, which grow with session length and are read by no consumer on the worker side. A full EditorState::clone() on a request path is a bug.
Canonical .de loader (v0.8.0+)
The document extension is .de; .op and the old .pen alias no longer open. pen.dev .pen files are an import only: they open as an untitled document and are never written back.
design-editor/src/pen_doc_adapter.rs bridges the canonical jian_ops_schema::PenDocument into the desktop's private DocPayload so files saved by the TS editor, Jian apps, or any other tool emitting the canonical schema load through the shared parser. Adapter responsibilities:
- Variant routing — all 12
PenNodevariants (frame / group / rectangle / ellipse / line / polygon / path / text / text_input / image / icon_font / ref) becomeNodePayload. Image / TextInput / IconFont degrade where their renderer isn't wired yet (image → grey placeholder rect; text_input → text node with seeded value / placeholder; icon_font →NodeKind::Other("icon_font")withiconFontNamestashed intext). - Layout via
jian_core::layout::LayoutEngine— taffy-backed flex solver, with the canonicalclipContent/justifyContent/alignItemssemantics. Each page-root gets its own engine pass; harvested rects are offset by(base.x, base.y)so multi-design files (e.g.pencil-demo.op's 14 side-by-side mock-ups) spread across the infinite canvas instead of overlapping at origin. - Text measurement via
jian_skia::SkiaMeasure— real skia paragraph shaper plugged in withLayoutEngine::with_backend(Rc::new(SkiaMeasure::new())). Replaces the defaultEstimateBackend(~10% character-count heuristic) sofit_contenttext frames size against the same glyph advancesdraw_textpaints with. - Version tolerance —
persistence::load_canonicalretries withversionrewritten to"1.0"when the canonical schema rejects on a legacy major (e.g. pencil-demo.op'sversion: "2.8"), so older TS files still load best-effort.
pen_doc_path_bounds.rs ports pen-core/src/path-anchors.ts::getPathBoundsFromAnchors — cubic Bezier derivative roots + extrema sweep — so authored paths with handles/curves scale into their width / height box the same way the canonical renderer paints.
Linked component libraries (#15)
A document links other .de / pen.dev .pen files as live component libraries. Links persist in editorMeta.libraries ({path, alias?, masters[], variables[]}; paths relative to the document folder, absolute only before the first save). Types: de-editor-core/src/library_link.rs; sync (pure): library_sync.rs; files: de-pen-loader/src/library_files.rs.
- Library masters are cached on the hidden
Componentspage with ids verbatim, sorefinstances resolve through the normal cross-page resolver and keep rendering when a library goes missing.mastersrecords ownership: a re-sync replaces exactly those nodes; a master whose ids a local node already uses is skipped (statusconflicts). Owned variables follow the library, local names win; theme axes are add-only. doc_io::load_editor_state_with_reportre-reads every link on open (pen.devimportsbecome links,alias:prefixes are dropped);set_file_name_displayrebases links on Save As. Desktoplibrary_io.rspolls link stamps once a second on a thread and re-syncs onDesktopEvent::LibraryChanged.- Sync is not an undo step;
undo/redocallreconcile_library_mastersso history cannot roll a library back. Unlink keeps masters an instance still uses as local components. - Surfaces: the Components tab's Libraries section (
component_browser_libraries.rs; Link / Reload queueLibraryRequest, the web host answers with a toast), MCPlist_libraries/add_library/remove_library(de-mcp/src/library_tools.rs,EditorCommand::Library).
PowerPoint import (#246)
de-pptx (pure Rust, wasm32-clean: zip + roxmltree) turns a .pptx into a PenDocument: one layout: none frame per slide at sldSz, in sldIdLst order, on a 4-column grid (80 px gaps), speaker notes as note annotations under their boards. Placeholders inherit box and text style slide → layout (by idx, then type) → master (by family) → txStyles → shape fontRef → defaultTextStyle; colours resolve through the colour map and theme with the DrawingML modifiers. Pictures ride as op-image: refs resolved inside image_src::intern::with_load_scope, so a logo repeated on every slide is one allocation. Charts / SmartArt / OLE / media take their stored fallback picture or a labelled placeholder and are counted in PptxImport::warnings. Entry points: doc_io::load_editor_state_with_report (desktop Open / drop / Import ▸ PowerPoint; unbound like pen.dev, refuse_overwrite blocks saving onto a .pptx), the web host's dom_io/pptx_import.rs, MCP import_pptx, CLI de import:pptx. Imported decks are tagged EditorState::tag_as_deck. Motion (de-pptx/src/motion.rs) is the export's mapping (#245) read backwards: <p:transition> → slideTransition (p14:dur when present, else the named speed), each main-sequence entrance → a two-stop mount animation (fade filter → opacity, ppt_x / ppt_y formula start → translate in slide px, ppt_w / ppt_h → scale, accel / decel → easing, repeatCount → iterations), with-previous / after-previous / on-click steps flattened into delays from the slide's start; exits, emphasis and motion paths stay static with a warning. The name tables (EntrancePreset, TRANSITION_ELEMENTS, TRANSITION_SPEEDS) live in de_pptx::motion_table, which export_pptx/motion.rs uses too.
Font weight + text wrapping
- Numeric-string
fontWeight—.defiles emit weights as JSON strings ("700","600","normal"). Bothvendor/jian/.../layout/mod.rs::resolve_weightandpen_doc_adapter::resolve_font_weightparse numeric strings first, then fall back to lucide-style named weights (bold/semibold/medium/light/thin/normal/regular/extralight/extrabold/black/heavy/demibold/ultralight/ultrabold/hairline). Node.text_wrap: bool— set only when the schema authoredtextGrowth: fixed-width(orfixed-width-and-height). Canvas paint wraps text only when this flag is true; otherwise paints single-line at the authored width so font-fallback overshoot doesn't break lines the TS app shows on one line.\ncharacters split into multiple lines either way.wrap_text(canvas_text_wrap.rs) — greedy CJK-aware line breaker mirroringpen-renderer/paint-utils.ts::wrapLine. Per-character breaks for CJK codepoints (CJK Unified + Extension A, Hiragana/Katakana, Hangul, CJK symbols, full-width), word breaks for Latin runs, blank-line preservation on empty\nsegments. Takes aTextFace(family, weight, italic) and measures throughmeasure_text_family_styled, so lines break where the painted face does (#178); the caret, alignment and auto-width shrink incanvas_text_edituse the same face. Lines break at the node's exact width (canvas_text_wrap::wrap_width, #186; the retired TSmin(5%, fontSize / 2)slack is gone). Layout gives wrapping text the width it measured at, before taffy rounds boxes to whole pixels (LayoutEngine::compute_with_text_widths, kemalcalak/jian#15, harvested inde-pen-loader/src/adapter/pages.rs), so afill_containertext box can be fractional and the painter breaks where layout did (#202). The greedy algorithm itself isde_editor_core::text_wrap::wrap_text_measured, and layout runs it too:de-pen-loader/src/painter_wrap_measure.rswraps jian'sSkiaMeasureand, for wrapped text in one style and a simple script, counts lines with that function over jian-skia'sFontResolveradvances (the painter's measure, through the resolverSkiaMeasureitself uses), sofit_contentheights hold exactly the painted lines; wrapped text at the default line height advances 1.2 × size per line there, like the painter. Mixed-style and complex-script text keeps Skia's paragraph breaks. Native Preview takes the same measure (de_pen_loader::layout_measure_backend). The CanvasKit web editor still sizes heights with jian'sEstimateBackend. Unset text styles come fromde_editor_core::text_defaults(14 px, 400, 1.2,system-ui), which the painter, the exports and the layout measure share.- Kerned text (#197) —
FontResolver::measure_textandFontResolver::shape_run(jian-skiashaped_words.rs) shape text with HarfBuzz word by word, Blink-style: words, single spaces and single CJK characters are shaped once per (typeface, size, skew) with unhinted, subpixel advances and cached with their glyphs (cleared onfont_generation). Nativedraw_textpaints the cached per-segment blobsshape_runbuilds, so paint and measure use one set of advances. CanvasKit mirrors it inop_ck_bridge.js(shapeWord/kernedWidth/drawKerned, paragraph shaper over aTypefaceFontProviderholding every registered face's bytes). Letter-spaced and justified lines place each glyph at the kerned advance of the text before it (canvas_viewport_text::draw_slice). RenderBackend::measure_text_weighted(text, font_size, weight)— every backend (NativeBackend,WebBackend,NativeFrameBackend) overrides this. Native keys its per-codepoint typeface cache on(codepoint, weight)and picks the face with CSS matching (below). Web measures throughmeasure_text_styledwith the weight. The trait default forwards tomeasure_textfor the heuristic fallback.- Weight → face (#300) — a family's face is picked by CSS font matching (CSS Fonts 4 §5.2; the rules live in jian-skia
font_match.rs), so 500 on a Regular + Bold family (Arial) is Regular, as in Chrome. Native: jian-skiafont_match::match_family_style_css, used byFontResolverinstead ofFontMgr::match_family_style(CoreText's descriptor match handed 500 the Bold face); Skia Paragraph already matched this way. CanvasKit: system families collect every Local Font Access face (web_fonts.rs, OS/2 style fromfont_meta::parse_style), andopCkMatchFontFacepicks one; imported and bundled web families still hold one face. - Synthetic bold — both native and web
draw_textsetPaintStyle::StrokeAndFill+stroke_width = font_size * 0.06for weights ≥ 600 when the picked face is lighter than 500 (opCkSyntheticBoldon web), so the bundled single-weight Roboto-Regular paints heavy when the file asks for bold and a real Bold face is never stroked again. Natively a variable font is instanced on itswghtaxis instead (jian-skiavariable_weight.rs, #197), so bundled VF faces (Inter, Manrope, …) paint their real bold; CanvasKit has no variation API and keeps the synthetic stroke.
Icon coverage
icons.rs + icons_data.rs (sibling — keeps icons.rs under cap as the catalogue grows) cover ~75 lucide variants spanning chrome glyphs (Plus / Minus / Search / Settings / etc.) plus first-party iconFontName strings from packages/pen-core/src/element-builders/ (calendar, clock, map-pin, more-vertical, chevron-left, trending-up/-down, compass, refresh-cw, layout-dashboard, users, package, zap, sliders-horizontal, activity, loader, focus, chart-line, settings-2, arrow-right, check-circle, alert-triangle, alert-octagon, sticky-note, bar-chart-2, bold/italic/underline/strikethrough, shopping-cart/-bag, send, message-circle, rocket, menu, credit-card, x-circle, mail, smartphone, chrome, apple, user). All d-strings copied verbatim from node_modules/.bun/lucide-react@0.545.0/dist/esm/icons/*.js.
Icon::from_name(&str) -> Option<Icon> resolves kebab-case glyph names plus common aliases (back / forward / cart / bag / hamburger / card / cancel / house / chart-bar / like / team / etc.). The unknown-name fallback strokes the canonical FALLBACK_ICON_D (M12 12m-3 0a3 3 0 1 0 6 0a3 3 0 1 0 -6 0) — a small centred dot, matching pen-renderer/node-renderer.ts::FALLBACK_ICON_D — so unsupported icons read as "unknown glyph" instead of a solid block.
paint_icon_font_node_weighted(backend, family, name, weight, rect, fill) (icons_font_node.rs, re-exported from icons.rs; paint_icon_font_node = weight 0) is the canvas entry point: scales the glyph's viewBox to min(w, h), centres it, strokes at (size / 24) * 2 widths to match lucide's 2 px reference stroke. The scene carries an icon's weight in font_weight (0 = unset).
Icon families (#4). icon_family.rs canonicalises iconFontFamily / iconFontName (case-insensitive, spaces / underscores as hyphens; material-symbols → -outlined, ph → phosphor) and resolves weight: phosphor snaps to its thin / light / regular / bold glyphs (the name suffixes still work), Material Symbols draws the weight-400 master plus a same-colour outline for 500–700, lucide / feather ignore it. lookup_icon applies the canonicalisation, so every consumer (canvas, HTML export, picker) agrees. Material Symbols (outlined / rounded / sharp, FILL 0) and phosphor (no duotone) live in two gzipped catalogs, de-editor-ui/assets/iconify-catalog-{material-symbols,phosphor}.json.gz (~2.5 MB together vs ~10 MB as JSON), handled by icon_catalog_extended.rs: native embeds them and inflates a family on first lookup; de-host-web fetches /pkg/assets/…json.gz on first miss and installs it in web_asset_fetch.rs. icon_font.weight (IconFontNode.weight, the text node's FontWeight: 700, "700", "bold") persists the weight; icon_font_to_payload maps it to font_weight with the text mapping, clamped to 0..1000. A picker swap (replace_selected_icon) keeps it.
Hover state across menus + panels
Every dropdown / sidebar / row list paints a per-row tint when the cursor is over it. State lives on Document.ui (or the appropriate sub-struct) and is updated by the host's apply_cursor_move:
| Surface | State | Tint |
File menu (file_menu.rs) | Document.ui.file_menu_hover: Option<FileMenuChoice> | theme.muted row wash |
Locale picker (locale_picker.rs) | Document.ui.locale_picker_hover: Option<Locale> | theme.muted |
Shape picker (shape_picker.rs) | Document.ui.shape_picker_hover: Option<ShapeChoice> | theme.muted |
| Layer panel rows | Document.ui.hovered_layer_id / hovered_page_index | theme.muted row wash |
| AgentSettings nav (sidebar tabs) | agent_settings.hover_nav: Option<AgentSettingsTab> | theme.accent |
| AgentSettings Agents list | agent_settings.hover_agents_row: Option<usize> | theme.muted row wash |
| Layer context menu | layer_context_menu.hovered_row: Option<u8> | row highlight |
Every host close path clears its respective hover state so reopening starts un-hovered.
File-menu polish
- Action labels strip the trailing
…(Open file / Save As / Export image — pure label, no Mac-convention ellipsis). - Recent file rows truncate long file names with a CJK-aware
truncate_to_widthhelper that reserves space for the age column on the right. - Compact row metrics (
ROW_HEIGHT = 30,HEADER_HEIGHT = 22,PAD_Y = 6,MENU_WIDTH = 300) — the menu reads tighter than the default 36/28/8/320.
Open / Save / Export error dialogs
persistence.rs::show_error_dialog pops a native rfd::MessageDialog on every failed load / save / export with a bilingual (EN / ZH per Document.ui.locale) title + path + detail body. OpenRecent failures additionally prune the stale entry from Document.ui.recent_files.
MCP server (de-mcp)
The de-mcp crate carries the MCP wire layer that mirrors the retired TS packages/pen-mcp server: a flat de-mcp/src/*.rs module set with lib.rs as the spine (types + ToolRegistry + run_stdio*). There is no mcp/ subdirectory. A serde-free hand-rolled JSON-RPC parser keeps the wasm32 bundle small.
Tool catalog
153 static-schema tools registered today. The authoritative list
is de-host-services/src/mcp_serve/schemas.rs — TOOL_SCHEMAS
(JSON inputSchemas; DEBUG_TOOL_SCHEMAS is gated out of the
production catalog) — plus the register_tool! calls in
de-host-services/src/mcp_serve.rs, guarded by an exact-count
assertion test in mcp_serve/tests.rs
(tools_list_response_includes_all_registered_tools). A further
37 kit-component tools (insert_<component>, one per built-in
UIKit component — 6 starter-kit + 31 shadcn) are appended dynamically
via de_mcp::element_tools::insert_kit_component_tools and ride
alongside the static schemas in the tools/list response. These 37
tools are what remains of the old TS element ecosystem — the ~188
add_* element-alias tools, their per-category builders/shards, and
the layered element manifest (emit_elements) are retired; callers
that need an arbitrary tree reach for batch_design instead.
By category:
- Read (18) —
get_document_info/get_selection/get_node/get_node_children/get_node_parent/list_pages/list_variables/get_active_theme/list_components/get_component/snapshot_layout/get_canvas_bounds/find_node_by_name/count_nodes/list_node_kinds/get_history_depth/get_viewport/get_selection_set. Each snapshotsDocumentstate at registration. - Node write (insert/update/delete/move/copy/replace) —
de-mcp/src/write_tools.rs. - Per-node attribute writers —
set_node_rotation/_text/_corner_radius/_font_size/_font_weight/_stroke_hex/_stroke_width/_fill_hex/_name(de-mcp/src/node_attr_tools.rs). - Selection / clipboard / canvas ops —
set_selection/set_selection_set/toggle_node_selection/clear_selection/duplicate/delete/nudge/group/ungroup/reorder/align_selected/copy_selected/cut_selected/paste_clipboard/set_active_tool/set_viewport/set_node_hidden|locked|collapsed/undo/redo(de-mcp/src/selected_ops_tools.rs+de-mcp/src/component_tools.rs). - Preview capture —
capture_preview(#156,de-host-services/src/mcp_serve/capture_preview_tool.rs): builds a headlessPreviewSessionfrom the registration snapshot, runsscreen+actions(tap/hover/navigate/back/wait, each settling 400 ms;de_preview_core::capturedrives the clock frame by frame like a host), waitstimeMs, and returns a PNG of the shown screen root (ornodeId). The editor's own preview and the document are untouched.entryNodeIdopens on the board holding that node, like the editor's selection (#223). - Preview screens —
set_screen(#223,de-mcp/src/screen_tools.rs):nodeId+modemark / start / remove, the property panel's screen-marker writes (de_editor_core::screen_marker_edit), oneBatch(one undo step). - Path booleans —
boolean_op(nodeIds+union|subtract|intersect|exclude;de-host-services/src/mcp_serve/boolean_op_tool.rs). Runs the desktop canvas's ownde_host_native::boolean_ops::compute_boolean_opon the snapshot (on every host; the web canvas keeps its axis-aligned fallback) and commits throughEditorCommand::CommitBooleanResult(one undo step). The command carries the predicted path id and the snapshot's document revision, so a document edited since the snapshot rejects. Sources with children are refused. The canvas boolean (desktop skia, web axis-aligned fallback) commits through the same command viaEditorState::commit_canvas_boolean, minting the id from the host'snext_node_idcounter. On the canvas a source with children is refused up front with a Warn toast (refuse_boolean_on_containers, #141). - Image generation (#10) —
generate(pen.devGenerate:typeai|stock,nodeId,prompt|query) andget_generation_status(de-host-services/src/mcp_serve/generate_tool.rs). Async: the call writes ade:pending-image-<id>image fill and returns; a worker in the process-globalde_host_services::generate_jobs::GenerateJobsruns the user's own provider (resolve_image_profile: active Images-tab profile, else an OpenAI / Gemini chat key →gpt-image-1/gemini-2.5-flash-image, else a "configure a provider" error and no write). Hosts drain finished jobs into ordinaryPatchNodeDatawrites computed against the current document: the live editor inMcpLiveServer::pump(the jobs' listener wakes the UI thread), the file-backed--mcp/--mcp-httpservers per request and after a bounded wait at session end (they load the user's saved provider settings), and the--serve-webdaemon per request and from the listener (custom endpoints SSRF-screened there). Failure removes the pending fill.enrich_imagessends explicitGenerateslots to the same provider and reports every slot (slots). #11 adds the frame types —svg(the first ready built-in chat agent writes SVG,generate_jobs/svg_llm.rs) andvectorize-image(localvtracer,generate_jobs/vectorize.rs): the call marks the frameplaceholder: true, the landing imports the SVG throughde_editor_core::svg_import::svg_nodes_fitted(fitted to the frame, no 400 px cap) as oneInsertSubtree+ flag clear — and the background transforms (remove-background/replace-background,generate_jobs/image_edit.rs): provider image edits (OpenAIimages/editswithbackground: transparent; Gemini edit + local green chroma key, since Gemini has no alpha; Replicate / Atlas refused at call time) returning a pending url; a failed edit rewrites it back to the source (LandingTarget::Edit). Sources (imageUrlalready in the document, orsourceNodeId) are checked against pen.dev's JPEG/PNG/WEBP, 16 MB, 256-4096 px limits (vectorize from 16 px). Artwork is checked on the worker (svg_llm::check_artwork: at least one, at most 5,000 nodes). The web daemon refuses remote source urls and custom endpoints for transforms. - Pages + components —
add_page/rename_page/delete_page/duplicate_page/reorder_page/set_active_page/instantiate_component/create_component/delete_component/rename_component(de-mcp/src/component_tools.rs). - Variables + themes —
set_variable_color|number|string|boolean/create_variable/delete_variable/rename_variable/set_active_axis_value/cycle_active_axis_value(de-mcp/src/scalar_vars.rs+de-mcp/src/component_tools.rs). - Batch design —
batch_design/design_skeleton/design_content/design_refine(de-mcp/src/batch_design.rs).batch_designaccepts exactly one ofnodes_json(a flat descriptor array),operations(the insert-onlyI(parent, node)program DSL), orscript— a JavaScript program sandboxed throughde_mcp::script_runner(featurescript, native-only; 64 MiB memory / 2 s wall-clock / 4096 recorded-line / 256 KiB source-size limits) whose only effect is callingI(parent, node)to emit the same program. The orchestrator's subagents share this exact runner: script-gen (a real JS program drivingI(...)) is THE generation protocol on every subagent rung. The reduced-complexity / minimal-skills retry rungs only narrow the loaded skill set; they do not switch output protocol.parse_nodesremains available for the separate modify/chat paths that still consume flat node JSON.
Read tools snapshot Document state at registration time. Write tools stay &self: they validate args and return ToolOutcome::OkWithCommand(result, command) for the host to apply via Document::apply_mcp_command(command). The apply path follows pre-validate-then-mutate discipline (id space, target existence, geometry, hex, container-children consent) so a bad arg never leaves the document half-mutated.
New page roots are placed before apply (#37). mcp_serve::process_message_with_write_applier (and its process_message_with_applier wrapper) passes each write command through de_mcp::root_placement::place_new_roots, so every MCP transport (stdio, live UI, snapshot ingest, serve-web, filePath) applies the same result. For the content tools places_new_roots lists, the command is tried on a narrowed copy, the roots it created are measured with the snapshot_layout layout, and de_editor_core::root_placement decides: a root without x/y goes right of the page content (ROOT_GAP, top-aligned), positioned roots move as a group only when one overlaps an existing root (allowOverlap: true keeps them), and every new root comes to the front (index 0). Nodes moved to the root (M()) and roots replaced in place (R()) are not new. The command becomes one Batch of the insert plus UpdateNode / MoveNode, so it undoes in one step. The live UI thread applies McpWrite::unplaced instead when its document revision moved on after the connection's snapshot, because the placement names nodes by predicted ids. Duplicate / paste, use_scene_template, page tools and parented inserts are untouched. The in-app design agent (de-chat-agent) does not run this yet, which is why the allowOverlap property and the placement note are added only to what the MCP host serves (tools/list and ToolSearch, via advertise_root_placement), not to the shared TOOL_SCHEMAS.
Agent pages, boards and follow (#264, #270). MCP add_page without children makes an empty page (the canvas's blank starter frame is for a person). A generated root frame takes the place of an empty root frame only when that frame carries the starter's name or none (de_editor_core::blank_starter::is_replaceable_starter_frame, shared by the core subtree insert and the batch_design program path); a named empty board stays. execute places new roots too. On the desktop the live pump hands the host the page root a content tool just added (McpLiveServer::take_follow_target, pages matched by id); the host switches to its page and brings it into view when it is off screen, keeping the zoom unless it does not fit (host_overlay_geometry::reveal_node). The web canvas has no live pump, so nothing follows there.
Write checks (#265–#268). Insert payloads pass batch_design_normalize::prepare_insert_payload after normalization: a path's pen.dev geometry becomes d, a path with neither d nor anchors (nor iconId) is refused with an error naming d, and an image node src / image fill url written as an absolute path or file:// url is read once and embedded as a data: url (de_mcp::local_image; patches through inline_local_images_in_patch). de-mcp does no file IO: the desktop binary installs the reader (de_host_services::local_image_reader, 16 MB cap) outside --serve-web, and anywhere without one the write fails with an error naming the url. A batch_design script's low-contrast text or icon colour is kept and reported in warnings (the prelude's __note, run_script_to_program_with_notes), never repainted. The MCP host's batch_design (with_overlap_warnings) also warns about overlapping siblings the write creates (de-mcp/src/layout_overlaps.rs: one side visible text, no non-text box holding the other whole, the orchestrator's text-collision thresholds; allowOverlap: true skips it); the in-app agent's registry leaves it off.
HTML slide decks import as boards (#244). de_html::deck finds a deck in an imported page (aria-roledescription="slide" outside a carousel, @media print page breaks read from the raw inline CSS by deck_print.rs, or a run of sibling section / .slide elements outside a carousel that a player toggles off screen or that share one px size; two or more; opacity: 0 scroll-reveal sections and print breaks that are not content siblings do not count). deck_visibility.rs shows the slides a player keeps hidden by adding the state class it would (on, active, current, …, else an inline style), and each slide maps through map_element_scoped with its real ancestors to its own top-level board: its own px size or its stage's, document order, DECK_COLUMNS per row, DECK_GAP apart, nothing outside the slides. Every import path gets this (file import, import_html, import_html_url, CLI), and since a page's top-level frames are its slides, export_deck exports the result. Imported children resolve against their parent's content box and absolute ones against the positioned ancestor's padding box (mapper_box::enter_box). An absolute child pinned by bottom / right on an axis where its positioned ancestor's or its own size is only known after layout (a flex: 1 slide body) moves into an Anchor frame (mapper_anchor.rs: role: overlay, fill both ways, justifyContent / alignItems end, insets as padding); Jian keeps fill_container on such absolute children (kemalcalak/jian#19). import_html / import_html_url take viewportWidth (CLI --viewport-width), a body declaring a px width keeps it, and the x/y offset moves every root. import_html_url refuses Claude artifact links (claude.ai/artifact/<id>, de-host-services/src/claude_artifact.rs) at once with the saved-HTML route: the link is a script shell whose *.claudeusercontent.com content claude.ai serves only to a regular browser, not the headless one the importer could drive; the saved HTML imports through the file import, decks included.
Resolved reads and clipping (#169), pen.dev's Get options. read_nodes takes resolveVariables (computed values under the active theme, variables_resolve::resolve_roots_for_canvas), resolveInstances (refs expanded by the canvas expander, de_editor_core::instance_path::expand_instances_with_paths, which renames the virtual ref__child ids to ref/child paths) and includePathGeometry (path d / anchors are omitted by default); nodeIds also takes an instance path. Writes: cmd_update_node / cmd_patch_node_data route a two-segment instance/child id as an instance override (apply_instance_override, the property panel's route); update_node and batch_design U() / R() / I() take any instance path, nested ones included, through EditInstanceDescendant (#166). Structural patch keys are refused. snapshot_layout entries carry problems: "partially clipped" | "fully clipped" against the intersection of their clipContent ancestors' boxes (de-mcp/src/layout_problems.rs), plus overlaps <id> for each sibling they cover (#265, layout_overlaps.rs), comma-joined.
execute: read and write in one script (#168). pen.dev's execute API over the QuickJS runtime batch_design(script) already embeds (rquickjs, feature script, native-only, so wasm builds are untouched; the same 64 MiB memory and 256 KiB source limits, a 10 s budget). de-mcp/src/script_execute.rs is the spine (tool, ScriptRenderer trait, result), script_execute_session.rs the host calls, script_execute_tree.rs the visitor tree (ctx.bounds parent-relative from the snapshot_layout layout, ctx.problems from layout_problems.rs), script_execute_prelude.rs the JS API. Writes go one by one through the batch_design DSL executor (batch_program::execute_line on a ProgramCtx), so reads see them and ids are the ones the host assigns; the recorded commands ship as one EditorCommand::Batch (one undo step). A throw, a caught failed write or the time limit returns an error and applies nothing. TakeScreenshot / Export record a copy of the state and render after success through de-host-services/src/mcp_serve/execute_tool.rs (images ride ToolOutcome::OkJsonWithImages, ToolResponse::Ok.images). execute writes verbatim (no write repairs) and is MCP-only: the in-app design agent's tool set is unchanged (#199). Guide: get_guidelines topic execute (de-ai-skills/skills/knowledge/execute-script.md).
Repairs and finalize touch only generated work (#107, #116). A de_editor_core::write_scope::WriteBaseline captured before a write (or before a whole design-agent run) diffs into a WriteScope: roots created, roots extended, nodes created or changed. Bare-MCP writes (mcp_serve::write_repairs) and each design-agent batch_design repair only that scope; the agent's finalize and unfilled-screen marking (de_orchestrator::agent_run_finalize, used by the desktop session, its teardown backstop and run_design_agent) and file-mode auto-finalize cover only the roots the run or session created, through de_orchestrator::loop_finalize_scoped. Boards a person made or imported next to them stay as authored. Imports are a person's content too: every import_* tool and browser write verbatim (write_repairs::writes_verbatim), so they get no write repairs and never arm auto-finalize (#299). An explicit finalize_design call still finalizes the whole page.
McpCommand::ReplaceNode.drop_children: bool is a destructive-swap guard — replacing a container without explicit drop_children=true is refused at apply time so a Frame / Group can't silently lose its subtree.
Wire-format hardening
de-mcp/src/parser.rs::parse_tool_call accepts both the real MCP tools/call envelope and the legacy direct-method shape. Multiple stop-gates baked in:
- Structured args reject the parse.
parse_flat_object_bodyreturnsNoneon{or[for any value;parse_tool_callpropagates that through a tri-state (ParamsResult::Missing/Body/Malformed). No scalar tool ever sees an object or array as a string-typed arg — earlier sentinel approaches were dropped because a literal{...}could collide with a real variable name. argumentsfield is a top-level walker.arguments_fielditerates top-level key/value pairs in the params body so a nestedmeta.argumentscan't shadow the real top-level field, and"name":"arguments"doesn't false-positive.- No client hangs on parse failure.
run_stdio_with_applierrecovers the JSON-RPCidviaparser::extract_request_idand writes a typedToolErrorCode::InvalidArgumentresponse so the client correlates + fails fast. Id-less lines drop silently — nothing to correlate against. - Read-only path refuses write tools.
run_stdio(no applier) demotes anyOkWithCommandresponse toToolErrorCode::Internal; clients can't see a "wrote: true" for an unapplied mutation.
File layout
All paths below are de-mcp/src/ — flat, no subdirectory:
lib.rs Spine: types + ToolRegistry + run_stdio*
json_serializer.rs JSON-RPC wire serializer (response_to_json + helpers)
parser.rs Wire parse — tri-state arguments_field, top-level walker
tools.rs Core read tools
read_tools.rs / read_nodes.rs / extra_read_tools.rs / read_tools_extra.rs
Read-tool families carved off tools.rs at the 800-cap
write_tools.rs Core node write tools (insert/update/delete/move/copy/replace)
write_tools_import_svg.rs SVG import arm of write_tools
write_tools_variables.rs Variable-write arm of write_tools
node_attr_tools.rs Per-node attribute writers (rotation/text/font/stroke/fill/name)
selected_ops_tools.rs Selection ops (dup/delete/nudge/group/align/clipboard)
component_tools.rs Components + selection/viewport/flag/tool/undo tools
page_tools.rs Page CRUD tools
batch_design.rs BatchDesign tool + hand-rolled nodes_json parser
batch_design_{dsl,normalize,fill_normalize,result,wire}.rs
The batch_design DSL, normalizers, and wire shapes
batch_program*.rs The `I(parent, node)` program DSL: parse / resolve / exec
batch_program_error.rs `ProgramError` (typed InvalidValue / ValueOutOfRange variants)
batch_layered.rs Layered design workflow
batch_layered_guidelines.rs Its guideline text (split off at the cap)
scalar_vars.rs Scalar + Color variables + create/delete/rename_variable
script_runner.rs Sandboxed JS runner behind `batch_design { script }`
script_execute*.rs The `execute` tool: read + write script, one undo step
element_tools.rs insert_<component> kit-component tools
*_tests.rs Per-module sibling test files (800-line cap convention)
mcp_tests.rs Cross-cutting: stdio dispatch, parser invariantsHost wiring
design-editor --mcp <path> (crates/de-host-services/src/mcp_serve.rs, shared by the desktop binary and de-host-web-server via de_host_services::cli_modes) runs a JSON-RPC stdio MCP server backed by the .de file at <path>. External CLIs (Claude Code / Codex / OpenCode / Kiro / Copilot / Antigravity / Grok Build) spawn the binary in this mode to drive the Rust editor. The module is itself a spine over mcp_serve/ siblings: schemas.rs (the TOOL_SCHEMAS catalog), wire.rs, sniff.rs (top-level method / id sniffing), error.rs (McpServeError, which separates protocol faults from socket failures), file_path.rs, doc_sync.rs, and the export / screenshot tool arms.
- Handshake:
initializereturns protocol version + capabilities + serverInfo;tools/listenumerates the full catalog with JSON inputSchemas;notifications/initialized+pinghandled inline. - Per-call lifecycle: re-build the
ToolRegistryagainst the live document (so read-tool snapshots reflect prior writes) → dispatch throughrun_stdio_with_applier→ applier closure mutates the doc + saves to disk on each successful write. - Top-level method / id sniffing uses the same key-walker discipline as the wire parser so nested keys can't shadow the real top-level fields.
Pending
- A real JSON Node parser would unlock
replace_node's subtree path + grow batch_design / design_skeleton beyond leaf-only. - Per-phase apply semantics for the design_* workflow (e.g. design_refine emitting UpdateNode batches against existing nodes instead of fresh inserts).
- HttpServer / streamable-http MCP transport (lifecycle scaffold exists in
chat_http_server.rs; wire protocol unverified).
AI chat (real provider integration)
The floating chat panel (widgets/ai_chat_panel.rs) is wired to
real CLI agents, not a stub:
ChatState::begin_send(shell-coredocument/chat.rs) — the native send path: pushes the user message + an empty assistant bubble, raiseschat.pending_send. The web shell (with thecodegenfeature — the production bundle) drains it intoweb_chat.rsand streams the turn through the daemon's/api/ai/stream; a transport-less build reports an honest per-send error (the oldsend()echo stub is retired from the web send path).ChatProvider(shell-corechat_provider.rs) is the transport-free trait; real impls live desktop-side:chat_runtime.rs(BuiltInProvider, agent-rs),chat_claude.rs(ClaudeCodeProvider,anthropic-agent-sdk),chat_subprocess.rs(SubprocessProviderfor Codex/Antigravity/Grok Build),chat_copilot.rs,chat_http_server.rs(OpenCode).chat_session.rs—ChatSessionruns a turn on a worker thread (ChatProvider::sendis a blocking iterator).launch_if_pendingdrainspending_send→provider_for_agent(chat_selected_agent);pumpstreams deltas into the transcript each frame. The winit loop wakes ~30 fps while a turn runs.- Model chip — the chat panel's bottom-left chip shows the selected
agent (
AgentProvider::name); clicking it cyclesui.chat_selected_agentthroughagent_settings.connectedviaDocument::cycle_chat_agent(AIChatHit::CycleModel). - Codex / OpenCode have no
ChatProviderbridge yet — selecting them writes an expliciterror: … not wired yetinto the transcript rather than silently rerouting to another agent.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

