agentleFS
kemalcalakkemalcalak/design-editor/crates/CLAUDE.md

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…

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
  1. Very specific:

    Import Image or SVG… → ShapeChoice::ImportImageOrSvg (host follow-up).

    line 172
  2. Very specific:

    All struct fields and intra-module helpers are scoped pub(in crate::widget_host) so submodule impl blocks can reach them while the public …

    line 332
  3. Distinctive:

    commit-on-blur for property-panel inputs + the variable-row inline editor, then resolve Git-panel / chat-model-picker ownership (the …

    line 403
  4. Very specific:

    Every input path that reasons about the canvas region MUST derive its rects from canvas_region(…), and every path that reaso

    line 427

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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-core was split, not just renamed: widgets / Document / RenderBackend → de-editor-ui, the MCP wire layer → de-mcp (flat de-mcp/src/*.rs, no mcp/ subdir). The wasm-libc-shim + vendor/skia-safe-op wasm-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 is EditorState in de-editor-core/src/state.rs; there is no document/ directory in any crate, so every shell-core/src/document/*.rs path 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↔web widget_host fork 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-pptx

de-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-host is a non-default feature (keeps skia-safe/gl out of the raster build used by de-host-services), and the entire widget_host module is gated behind it — a default-feature cargo test -p de-host-native runs 55 tests instead of 676 and gives ZERO coverage of widget_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 RenderBackend trait 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-web widget_host.rs) are the ONLY files allowed to call de_editor_ui::widgets::*. Boundary script: tools/check-widget-boundary.sh.
  • Max 800 lines per file — zero violations workspace-wide. As of d2d8104c no .rs file in crates/ exceeds the cap, and the sibling-module split is the universal shape: a spine keeps the public surface and mod declarations, 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 a foo/tests/ directory when the tests themselves outgrow the cap). Check with find 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 bare Runtime::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_anywhere picks 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.rs sibling 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, a Display impl that reproduces the previous message byte-identically (so user-visible strings and their tests don't move), and From impls that collapse the map_err adapters at the call sites. New fallible code should introduce or reuse an enum rather than add another Result<_, 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 via include_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.rs is the platform-free half: a process-global route -> bytes registry with single-flight, a widget-records / host-drains request queue, and Absent/Pending/Ready/Failed states. The widget layer calls web_assets::request(route) from paint and draws a placeholder; de-host-web/src/web_asset_fetch.rs drains it once per frame over XHR and installs the bytes. Native keeps its include_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 by tools/stage-web-assets.sh, which check-wasm-bundle.sh runs as step 4 and both the CI workflow and Dockerfile.web-rust inherit. Moved: the Prompt Center (~2.1 MiB) and 80 Scene Template preview JPEGs (~3.4 MiB), the 80 scene-template .de documents (~6.6 MiB), and iconify-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-catalog also pulls flate2 to inflate them). Still embedded everywhere: the de-ai-skills corpus (~1.1 MiB, include_dir!).
  • The icon-catalog split is opt-in, the rest is cfg(target_arch = "wasm32"). de-editor-ui's runtime-icon-catalog feature is enabled only by de-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-parsed Color to 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 past max_node_id() + 1 (checked_add so u64::MAX returns 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-anchor NodeKind::Path builder; 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 fresh NodeKind::Group whose aggregate_bounds covers 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/)

WidgetSectionFile
FilePill / CanvasActionsFloating 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 enumfile_pill.rs, canvas_actions.rs, panel_toggle.rs, chrome_hit.rs, chrome_tooltip.rs; window-control dots in window_strip.rs
Floating cardsEditor 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_cardfloating_panels.rs; core motion in editor_ui_state/panel_motion.rs
LayerPanelLeft rail — Pages + Layers sectionslayer_panel.rs
ToolbarVertical floating column — Select / shape slot / Ellipse / Pen / Pencil / Text / Frame / Note / Image / Handtoolbar.rs
ShapePickerToolbar 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
CanvasViewportCenter — node tree + grid + viewport transformcanvas_viewport.rs
PropertyPanelRight 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/
AIChatPlaceholderFloating — chat with drag + 4-corner snap + collapse pillai_chat_panel.rs
LocalePickerFile ▸ Language dropdown under the file pill (15 native names + Check)locale_picker.rs
StatusBarFloating bottom-right — zoom controlsstatus_bar.rs
iconslucide d-string library (50+ icons; 24×24 viewBox stroke art)icons.rs
brand_iconsClaude / OpenAI / Gemini / Copilot / Antigravity / Grok filled logos + OpenCode primitive logobrand_icons.rs
ColorPickerHSV overlay (Cmd-Shift-C or fill/stroke swatch click) — sat/value box + hue strip + hex inputcolor_picker.rs
LayerContextMenuRight-click overlay on layer rows + page tabs (Rename / Duplicate / Delete / Group / Ungroup / Lock / Hide; subset on page tabs)layer_context_menu.rs
AgentSettingsCmd+, modal — up to 960×760, sidebar nav (Agents / MCP / Images / Fonts / System) + scrollable body; Agents is list + detailagent_settings_panel.rs + agent_settings_{agents,i18n,images,mcp,system}*.rs
themeshadcn-dark palette tokens (incl. canvas_surface)theme.rs
i18n15 canonical locale catalogs, 1,860 direct keys each, sharded main → _git → _panel → _collab in the de-i18n cratede-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 active Theme — 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 hardcoding Theme::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 via i18n::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 LocalePicker dropdown 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 mutates Document.ui.locale once 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_character cached per i32 in NativeBackend), 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>.rs ends its match with _ => return super::<locale>_git::lookup(key), the Git shard ends with _ => return super::<locale>_panel::lookup(key), the _panel shard ends with _ => return super::<locale>_collab::lookup(key), and the _collab overflow shard ends with _ => return None. The catalog is 1,860 direct keys per locale (catalog_integrity_tests.rs asserts the exact number). Native builds compile all 15 tables. On wasm32, de-host-web enables de-editor-ui's forwarding runtime-locale-catalog feature; de-i18n's source-side feature + target double gate then keeps only en-US + zh-CN embedded. tools/export-i18n-catalogs.py validates the same 1,860-key equality and generates the other 13 BCP-47 JSON files for tools/stage-web-assets.sh to 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.rs and en.rs are 775 lines), so new entries do not belong there — the _panel shards exist precisely to absorb overflow and have room. Only edit a main or _git table when you are changing the wording of a key that already lives there. Then bump the expected count in catalog_integrity_tests.rs and run:

    cargo test -p de-i18n

    Catalog 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.rs tests 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 growing mod.rs. tools/convert-locales.py is 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 writes ui.shape_tool + doc.tool and closes the panel. A star (#87) is a PolygonNode with innerRadius; 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 through Document::commit_property_edit (PositionR writes node.corner_radius), hex focuses through set_selected_color(is_fill, color).
  • property_input: TextInputState — live keystrokes, caret, select-all, blink, and composition state accumulate here. apply_text is 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 layout Pad field, #83) takes digits, . and spaces: a CSS shorthand of 1–4 values (16, 96 120, 8 16 4, 8 16 8 4), parsed / formatted by de-editor-core/src/padding_shorthand.rs and committed through commit_padding_shorthand.
  • 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 export conic-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 through ColorTarget::GradientStop(i), because the snapshot lists mesh vertices as the primary fill's gradient_stops (#90). A stepper (EditMeshLattice, core mesh_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 through updates_document.
  • Shader — one preset row (Noise = the turbulence preset, Fade, Glow: de_editor_core::shader_presets). A custom program adds a trailing Custom cell (#141): picking a preset stashes the program per node in editor_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 each uniform (de_editor_core::shader_uniform_specs: @label, @range a, b / @min / @max, @color or layout(color), @default; size / time / mouse, @time / @mouse / @resolution and uniform shader children 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 in gradient_stop_count (primary_body_items). Then the Code row: it opens the floating source editor (widgets/shader_source_editor.rs, state + keys in core shader_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, native RuntimeEffect::make_for_shader, web opCk.shaderCompileError) and the panel reads the cached result. Writes go through EditorCommand::SetShaderUniform / SetShaderSource (shader_edit.rs, checked against the declarations), also MCP set_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. Schema ImageFillBody.transform is 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_scale

stroke_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:

PatternContents
press.rs + press_ctx.rs + press_*_tiers.rsThe 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_*.rsThe apply_cursor_move hover ladder, same spine/ctx/tier shape (native only; web's cursor path lives in cursor_input.rs)
keyboard.rs + keyboard_*.rsKey dispatch split by concern — caret, clipboard, delete, escape, send, IME
*_dispatch.rsThin platform arms over the shared de-editor-ui dispatch flows (property, image panel, settings, font picker)
paint.rs, paint_pan_cache.rs, scene_state.rsThe composition pass and its caches
host_lifecycle.rs, host_requests.rsHost boot / teardown and outbound request plumbing carved off the spine
geometry.rs, overlay_rects.rs, helpers.rsThin 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.

KeyMethodBehaviour (TS parity: use-edit-shortcuts.ts + use-clipboard-shortcuts.ts)
Backspaceapply_backspacePops a char when an input is focused; else delete_selected().
Deleteapply_deletedelete_selected() regardless of which non-text overlay is open.
Cmd/Ctrl+Dapply_duplicateduplicate_selected(&mut next_node_id, 10.0) and selects the clone.
ArrowUp/Down/Left/Rightapply_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+Vapply_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.
Escapeapply_escapeOne layer per press, in priority order: property-focus → locale picker → shape picker → fill-type picker → fill ⋯ menu → chat focus → selection.
Enterapply_sendCommits property edit or sends chat.
Cmd/Ctrl+[ / ] (Preview)preview_history_stepBack / 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): animations triggers are mount / inView / hover / tap (jian MotionTrigger, kemalcalak/jian#10). de-preview-core/src/motion_pointer.rs plays 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 / height are motion properties: motion tracks for them (PreviewAnimationState::start_motion) interpolate continuously and invalidate PaintOnly (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 @keyframes over opacity / transform into mount animations (de-html/src/mapper_motion.rs; a transform-origin scale becomes scale plus a centre-shift translate, because nodes scale about their centre; CSS infinite is de_util::motion::INFINITE_ITERATIONS); anything else imports static with motion.keyframes_static. Present replays the arriving slide's mount animations (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 a data-de-motion-node box 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.rs on both hosts; macOS View ▸ Present; File menu ▸ Present on every host, chord spelled per platform by file_menu_paint::platform_chord) sets preview.present, so slideshow_for_document presents 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 a SlideTransitionRun (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 writes p:fade / p:cover / p:push at 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 by reset_matrix() so it doesn't compound)
  • LOGICAL viewport sizes (physical / dpi)
  • Cursor position cached on CursorMoved, dispatched on MouseInput
  • Wheel and trackpad both route through de_editor_core::host_wheel_routing (#303, Figma's mapping): no modifier pans (Shift = horizontal), Cmd/Ctrl zooms; LineDelta becomes pixels first (line_delta_px: Windows reads the system lines per notch, 100 px at the default 3; macOS 40 px per line). PinchGesture zooms
  • Cursor flips to EwResize when 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:

  1. press_topmost_overlay_tiers — modals, floating panels, context menus
  2. 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)
  3. press_menu_modal_tiers — shape picker; file / export / figma modals; import + locale dropdowns
  4. press_rail_overlay_tiers — image-fill popover, StatusBar, resize gutter, the model-picker slice over the floating chrome
  5. press_chrome_tier — the floating chrome (file pill + canvas action group) and its blank-press padding
  6. press_preview_tier — Preview (Play) mode swallows everything below
  7. press_property_overlay_tiers → press_panel_dispatch_tiers → press_property_panel_tier
  8. press_git_and_chat_tiers
  9. press_toolbar_tiers
  10. press_layer_and_click_tiers — LayerPanel rows / Page rows + chat-defocus
  11. press_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.rs spine; _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 is AgentSettings::agents_selected (by id; read it through resolved_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 as cli_hidden_models and leave the chat picker, Connect / Disconnect. ACP detail: preset + connection segments, command/args or URL, install hint, environment. Host tests press controls through AgentSettingsPanel::point_for_hit rather 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 + Add empty 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, state editor_ui_state/update_state.rs), which the desktop host drives through update_install.rs (download with progress, SHA-256 check against SHA256SUMS.txt, stage) and update_install_platform.rs (macOS bundle swap / Windows silent NSIS / Linux binary rename from design-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 BEFORE start_pen_path mutates 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::*_selected ops; Group/Ungroup live in document/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::Text go through its image-cached path. stroke_line / fill_round_rect / stroke_round_rect / stroke_svg_path / fill_svg_path bypass 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_back capped at 100 entries; the old Vec::remove(0) was O(n) on every commit past the cap.
  • Document::t returns &'static str — every locale value is a string literal, so chrome paint stores &'static str instead of cloning a String per frame. PropertyLabels is a Copy struct of static slices; widget builders propagate the 'static lifetime so no per-paint allocations happen for labels.
  • Viewport culling (widgets/canvas_viewport.rs) — paint_node takes a cull: 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) + a prepare_redraw step 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 hide canvas.clear(BLACK) between same-output frames).
  • Cursor-move coalescing — apply_cursor_move cached as pending_cursor_move, drained on RedrawRequested AND right before apply_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::new walks PREWARM_CJK_CODEPOINTS (~50 chars covering every CJK glyph used in the chrome + settings modal) through FontMgr::match_family_style_character at 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/:

ModuleOwns
host_ui_transitions.rsChrome-state transitions (the byte-identical twin blocks)
host_press_transitions.rsPress-path chrome transitions
host_keyboard_transitions.rsKeyboard-driven editor-state transitions
host_escape_transitions.rsThe Escape ladder — exactly one layer dismissed per press
host_drag_state.rsThe transient pointer-drag structs both spines used to declare separately
host_drag_transitions.rsCanvas press/drag state transitions
host_variables_transitions.rsVariablesPanel press arms
host_variables_commit.rsVariablesPanel draft commits (header renames + per-row Name/Number/String/Color drafts)
host_settings_commit.rsSettings-modal draft commit
host_image_panel_transitions.rsImage-node panel transitions (Search / Generate popovers)
host_preset_name_draft.rsThe variables preset "save as name" input
host_wheel_routing.rsWheel / trackpad routing (pan vs zoom, Shift axis) + line → px per notch (#303)
request_snapshot.rsnarrowed_snapshot — see below
agent_reveals.rsBefore/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.rsreveal_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/:

ModuleOwns
press_flow.rsPress dispatch — hosts map a hit-test result through it and run only the tail
chat_click_flow.rsChat-panel click dispatch (apply_chat_hit)
property_panel_dispatch.rs + _support.rsPropertyPanel action dispatch (was two ~500-line near-verbatim copies)
property_panel_commit.rsBoth ends of the PropertyPanel draft lifecycle (property_focus_initial + commit)
property_panel_layout_ops.rsLayout / sizing / typography writers behind the button groups
drag_flow.rsCanvas node-drag flow
marquee_flow.rsMarquee-release commit (screen→doc rect walk + additive/replace selection)
image_crop_flow.rsFigma-style image-fill crop gesture
image_popover_input_flow.rsMouse selection in the image Search / Generate text inputs
scroll_flow.rsPanel wheel / trackpad-pan scrolling
cursor_hover_flow.rsCursor-move hover resolution
missing_fonts_flow.rsMissing-font prompt: scroll, press dispatch, detection/refresh bookkeeping
variables_panel_geometry_flow.rsFloating VariablesPanel placement + resize clamping
agent_settings_press_flow.rs + _entries.rs + _focus.rsAgent-settings modal press dispatch, list-entry arms, and input focus seeding
host_canvas_geometry.rsThe coordinate invariant (see "Hit-test order")
host_overlay_geometry.rsOn-screen rects for dropdowns, the three draggable floating panels, StatusBar actions
host_frame_bookkeeping.rsPer-frame work both spines do around paint (cache owner rotation, layout transitions, animation deadlines)
menu_paint.rsShared dropdown row chrome (hover tint, hit rect, divider) for the file menu
settings_form.rsShared card-form chrome for the Agent settings sections
canvas_generation_visibility.rsWhat the last canvas frame showed of the generation overlay; generation_deadline_ms keeps 60 fps only for that (#17), both hosts
test_capture_backend.rsTest-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:

  1. Variant routing — all 12 PenNode variants (frame / group / rectangle / ellipse / line / polygon / path / text / text_input / image / icon_font / ref) become NodePayload. 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") with iconFontName stashed in text).
  2. Layout via jian_core::layout::LayoutEngine — taffy-backed flex solver, with the canonical clipContent / justifyContent / alignItems semantics. 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.
  3. Text measurement via jian_skia::SkiaMeasure — real skia paragraph shaper plugged in with LayoutEngine::with_backend(Rc::new(SkiaMeasure::new())). Replaces the default EstimateBackend (~10% character-count heuristic) so fit_content text frames size against the same glyph advances draw_text paints with.
  4. Version tolerance — persistence::load_canonical retries with version rewritten to "1.0" when the canonical schema rejects on a legacy major (e.g. pencil-demo.op's version: "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 Components page with ids verbatim, so ref instances resolve through the normal cross-page resolver and keep rendering when a library goes missing. masters records ownership: a re-sync replaces exactly those nodes; a master whose ids a local node already uses is skipped (status conflicts). Owned variables follow the library, local names win; theme axes are add-only.
  • doc_io::load_editor_state_with_report re-reads every link on open (pen.dev imports become links, alias: prefixes are dropped); set_file_name_display rebases links on Save As. Desktop library_io.rs polls link stamps once a second on a thread and re-syncs on DesktopEvent::LibraryChanged.
  • Sync is not an undo step; undo / redo call reconcile_library_masters so 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 queue LibraryRequest, the web host answers with a toast), MCP list_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 — .de files emit weights as JSON strings ("700", "600", "normal"). Both vendor/jian/.../layout/mod.rs::resolve_weight and pen_doc_adapter::resolve_font_weight parse 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 authored textGrowth: fixed-width (or fixed-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. \n characters split into multiple lines either way.
  • wrap_text (canvas_text_wrap.rs) — greedy CJK-aware line breaker mirroring pen-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 \n segments. Takes a TextFace (family, weight, italic) and measures through measure_text_family_styled, so lines break where the painted face does (#178); the caret, alignment and auto-width shrink in canvas_text_edit use the same face. Lines break at the node's exact width (canvas_text_wrap::wrap_width, #186; the retired TS min(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 in de-pen-loader/src/adapter/pages.rs), so a fill_container text box can be fractional and the painter breaks where layout did (#202). The greedy algorithm itself is de_editor_core::text_wrap::wrap_text_measured, and layout runs it too: de-pen-loader/src/painter_wrap_measure.rs wraps jian's SkiaMeasure and, for wrapped text in one style and a simple script, counts lines with that function over jian-skia's FontResolver advances (the painter's measure, through the resolver SkiaMeasure itself uses), so fit_content heights 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's EstimateBackend. Unset text styles come from de_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_text and FontResolver::shape_run (jian-skia shaped_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 on font_generation). Native draw_text paints the cached per-segment blobs shape_run builds, so paint and measure use one set of advances. CanvasKit mirrors it in op_ck_bridge.js (shapeWord / kernedWidth / drawKerned, paragraph shaper over a TypefaceFontProvider holding 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 through measure_text_styled with the weight. The trait default forwards to measure_text for 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-skia font_match::match_family_style_css, used by FontResolver instead of FontMgr::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 from font_meta::parse_style), and opCkMatchFontFace picks one; imported and bundled web families still hold one face.
  • Synthetic bold — both native and web draw_text set PaintStyle::StrokeAndFill + stroke_width = font_size * 0.06 for weights ≥ 600 when the picked face is lighter than 500 (opCkSyntheticBold on 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 its wght axis instead (jian-skia variable_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:

SurfaceStateTint
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 rowsDocument.ui.hovered_layer_id / hovered_page_indextheme.muted row wash
AgentSettings nav (sidebar tabs)agent_settings.hover_nav: Option<AgentSettingsTab>theme.accent
AgentSettings Agents listagent_settings.hover_agents_row: Option<usize>theme.muted row wash
Layer context menulayer_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_width helper 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 snapshots Document state 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 headless PreviewSession from the registration snapshot, runs screen + actions (tap / hover / navigate / back / wait, each settling 400 ms; de_preview_core::capture drives the clock frame by frame like a host), waits timeMs, and returns a PNG of the shown screen root (or nodeId). The editor's own preview and the document are untouched. entryNodeId opens on the board holding that node, like the editor's selection (#223).
  • Preview screens — set_screen (#223, de-mcp/src/screen_tools.rs): nodeId + mode mark / start / remove, the property panel's screen-marker writes (de_editor_core::screen_marker_edit), one Batch (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 own de_host_native::boolean_ops::compute_boolean_op on the snapshot (on every host; the web canvas keeps its axis-aligned fallback) and commits through EditorCommand::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 via EditorState::commit_canvas_boolean, minting the id from the host's next_node_id counter. 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.dev Generate: type ai | stock, nodeId, prompt | query) and get_generation_status (de-host-services/src/mcp_serve/generate_tool.rs). Async: the call writes a de:pending-image-<id> image fill and returns; a worker in the process-global de_host_services::generate_jobs::GenerateJobs runs 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 ordinary PatchNodeData writes computed against the current document: the live editor in McpLiveServer::pump (the jobs' listener wakes the UI thread), the file-backed --mcp / --mcp-http servers per request and after a bounded wait at session end (they load the user's saved provider settings), and the --serve-web daemon per request and from the listener (custom endpoints SSRF-screened there). Failure removes the pending fill. enrich_images sends explicit Generate slots 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) and vectorize-image (local vtracer, generate_jobs/vectorize.rs): the call marks the frame placeholder: true, the landing imports the SVG through de_editor_core::svg_import::svg_nodes_fitted (fitted to the frame, no 400 px cap) as one InsertSubtree + flag clear — and the background transforms (remove-background / replace-background, generate_jobs/image_edit.rs): provider image edits (OpenAI images/edits with background: 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 (imageUrl already in the document, or sourceNodeId) 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_design accepts exactly one of nodes_json (a flat descriptor array), operations (the insert-only I(parent, node) program DSL), or script — a JavaScript program sandboxed through de_mcp::script_runner (feature script, native-only; 64 MiB memory / 2 s wall-clock / 4096 recorded-line / 256 KiB source-size limits) whose only effect is calling I(parent, node) to emit the same program. The orchestrator's subagents share this exact runner: script-gen (a real JS program driving I(...)) 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_nodes remains 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_body returns None on { or [ for any value; parse_tool_call propagates 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.
  • arguments field is a top-level walker. arguments_field iterates top-level key/value pairs in the params body so a nested meta.arguments can't shadow the real top-level field, and "name":"arguments" doesn't false-positive.
  • No client hangs on parse failure. run_stdio_with_applier recovers the JSON-RPC id via parser::extract_request_id and writes a typed ToolErrorCode::InvalidArgument response 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 any OkWithCommand response to ToolErrorCode::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 invariants

Host 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: initialize returns protocol version + capabilities + serverInfo; tools/list enumerates the full catalog with JSON inputSchemas; notifications/initialized + ping handled inline.
  • Per-call lifecycle: re-build the ToolRegistry against the live document (so read-tool snapshots reflect prior writes) → dispatch through run_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-core document/chat.rs) — the native send path: pushes the user message + an empty assistant bubble, raises chat.pending_send. The web shell (with the codegen feature — the production bundle) drains it into web_chat.rs and streams the turn through the daemon's /api/ai/stream; a transport-less build reports an honest per-send error (the old send() echo stub is retired from the web send path).
  • ChatProvider (shell-core chat_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 (SubprocessProvider for Codex/Antigravity/Grok Build), chat_copilot.rs, chat_http_server.rs (OpenCode).
  • chat_session.rs — ChatSession runs a turn on a worker thread (ChatProvider::send is a blocking iterator). launch_if_pending drains pending_send → provider_for_agent(chat_selected_agent); pump streams 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 cycles ui.chat_selected_agent through agent_settings.connected via Document::cycle_chat_agent (AIChatHit::CycleModel).
  • Codex / OpenCode have no ChatProvider bridge yet — selecting them writes an explicit error: … not wired yet into the transcript rather than silently rerouting to another agent.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.