@grida/svg-editor 1.0.0-alpha.1 → 1.0.0-alpha.11

package/README.md

@@ -45,6 +45,14 @@ The defaults are inverted from how most editor SDKs grow. Default is **core, not
 
 The consumer is expected to bring their own UI for everything outside the canvas: toolbar, property panel, layer list, inspector, contextual menus, modals. The editor's job is to be a legible source of state and a legible sink for commands — not to render those surfaces.
 
+### Element IR (internal)
+
+Internally, the editor wraps the parsed SVG in a **typed element IR**: a per-node typed view with element-typed capabilities (`is_resizable`, `is_rotatable`, `accepts_paint`, …), typed geometry mutators, and an explicit `RefusalReason` enum for unsupported operations. Commands dispatch on capability, not on element tag. Round-trip invariants the bytes alone cannot enforce — for example, "an editor-authored `rotate(θ cx cy)` recomposes its pivot when the local box changes" — are IR invariants enforced inside the mutator methods.
+
+The IR is a **typed view, not alternative storage**. The parsed AST remains the in-memory store; file bytes remain the source of truth; the parse-side source-position trivia store carries whitespace, attribute order, and unknown-namespace content. The IR is rebuilt from the AST on every load and discarded on `dispose`. P1 round-trip stands.
+
+This is consistent with the "Not a private IR" anti-goal below — that anti-goal rejects alternative on-disk format and bytes-projected-from-IR storage, neither of which this is. Design: `docs/wg/feat-svg-editor/element-ir.md`. Migration sketch: `docs/wg/feat-svg-editor/element-ir-migration.md`.
+
 ## Principles
 
 These are decision rules, not aspirations. Each one points to a verdict when "is this core, customizable, or its own layer?" comes up in review.
@@ -63,11 +71,11 @@ A small, named set of concerns belongs to the embedding product: clipboard, file
 
 ### P4. Subscribe to outcomes, not events.
 
-The public observation surface is **designed**, not raw. It exposes purpose-built views — `selection`, `node_properties`, `node_paint`, `tree`, `surface_hover`, `dirty`, `version`, `structure_version` — each of which handles multi-selection, capability variance, and history bookkeeping internally. Consumers never receive raw pointer events, reducer actions, or gesture frames. If a needed view doesn't exist, that's an API gap to close, not an internals hatch to open.
+The public observation surface is **designed**, not raw. It exposes purpose-built views — `selection`, `properties(names)`, `mode`, `tree`, `dirty`, `version` — each of which handles multi-selection, capability variance, and history bookkeeping internally. Consumers never receive raw pointer events, reducer actions, or gesture frames. If a needed view doesn't exist, that's an API gap to close, not an internals hatch to open.
 
 ### P5. A separate layer earns its separateness by reuse or isolated testability.
 
-Code becomes its own package or layer when it has ≥2 callers, or can be meaningfully tested without mounting the editor. `@grida/history`, `@grida/cmath`, `@grida/text-editor`, `@grida/keybinding`, `@grida/hud` pass. A hypothetical `@grida/svg-selection-model` (one caller, untestable without an editor) doesn't.
+Code becomes its own package or layer when it has ≥2 callers, or can be meaningfully tested without mounting the editor. `@grida/history`, `@grida/cmath`, `@grida/text-editor`, `@grida/mixed-properties` pass. A hypothetical `@grida/svg-selection-model` (one caller, untestable without an editor) doesn't.
 
 ### P6. Public only after dogfooding.
 
@@ -89,11 +97,13 @@ When a new design decision lands, walk these in order. The first match wins.
 
 These are the design principles guiding the implementation.
 
-- Built as an SDK, not an app. Headless, backend-agnostic — no DOM or window assumptions in the core. v1 ships a DOM surface; non-DOM surfaces are out of scope.
+- Built as an SDK, not an app. Headless, backend-agnostic — no DOM or window assumptions in the core. Plug into any rendering surface.
 - The IR carries source-position trivia, so the serializer can rewrite only the bytes that actually changed.
 - Per-element-type capability modules (rect, circle, path, text, group, use, ...) contribute intent handlers, inspector controls, and direct-manipulation overlays into a shared editor shell — internally. The shared shell is what's public.
 - Edit intents are dispatched per `(element type, gesture, mode)`, so each mutation chooses the cleanest in-place representation: rewrite native attributes when the gesture allows it, fall back to `transform=` otherwise.
-- A separate, explicit **Tidy** command is planned for structural cleanup (deduplicate defs, strip dead resources, normalize generated class and id names, recognize geometric patterns). Never silent, never automatic. **Deferred for v1.**
+- A separate, explicit **Tidy** command performs structural cleanup — deduplicate defs, strip dead resources, normalize generated class and id names, recognize geometric patterns. Never silent, never automatic.
+
+The per-element-module and `(element type, gesture, mode)` bullets above describe today's code. The proposed model groups by edit-shape and dispatches on capability — see [Paradigm § Element IR (internal)](#element-ir-internal) and `docs/wg/feat-svg-editor/element-ir.md`. These bullets will be revised when that model lands.
 
 ## Examples
 
@@ -107,13 +117,13 @@ A few scenarios this is designed to handle well.
 >
 > The AI's structural changes round-trip cleanly through the editor. The two color tweaks are the only added lines in the diff. The next AI pass reads a file that still looks like its own work.
 
-> _"I translated a rect 10px to the right."_
+> _"I rotated a rect by 12 degrees."_
 >
-> The editor rewrites the rect's `x` in place. It does not wrap it in a `<g>`, does not collapse to a matrix, and does not touch the rect's `y` / `width` / `height`.
+> The editor writes `transform="rotate(12 cx cy)"` on the rect itself. It does not wrap it in a `<g>`, does not collapse to a matrix, and does not touch the rect's `x` / `y` / `width` / `height`.
 
 > _"This SVG has a `<style>` block with `.brand { fill: var(--brand) }`. I want to change the fill of one element to red."_
 >
-> The editor adds `style="fill: red"` inline on that element, which wins the cascade against the class rule. The stylesheet is untouched. Other `.brand` elements are untouched. **Note for v1:** the headless cascade engine does **not** match `<style>` rules — it covers presentation attribute + inline style + inheritance + initial only. To see what the `.brand` rule actually resolves to for the inspector, attach the DOM surface and use `editor.dom_computed_property(id, "fill")`, which delegates to `getComputedStyle()` (see [Low-level API](#low-level-api)).
+> The editor adds `style="fill: red"` inline on that element, which wins the cascade against the class rule. The stylesheet is untouched. Other `.brand` elements are untouched.
 
 > _"This file has an Inkscape `<sodipodi:namedview>` block and `inkscape:label` attributes."_
 >
@@ -131,7 +141,7 @@ npm install @grida/svg-editor
 
 ## API
 
-> **v1 status.** Names and shapes are stabilizing toward `1.0.0`. The high-level API documented here is the durable contract; the [Low-level API](#low-level-api) section is where escape hatches live for things v1 doesn't yet cover. The list of pieces not in v1 is documented honestly under [Deferred for v1](#deferred-for-v1) — every promise we're not yet keeping. Signatures shown as TypeScript-ish pseudo-code; some types are simplified for readability.
+> **Status of this section.** Names and shapes are a v0 proposal — subject to P6 dogfooding before semver stability. The headings (`commands`, `state`, `properties`, `paint`, `defs`, `tree`, `modes`, `subscribe`, providers, style, surface) are committed; their member names are not. The **multi-selection ("mixed values")** section is explicitly deferred — its shape is sketched as a placeholder, not designed. Signatures shown as TypeScript-ish pseudo-code; some types are simplified for readability.
 
 ### Construction
 
@@ -155,11 +165,11 @@ const editor = createSvgEditor({
 
 `createSvgEditor` is the only constructor. The returned `SvgEditor` is the only object consumers ever hold.
 
-The editor core is **headless**. It parses the SVG, owns the document IR, accepts commands, and emits state — but it does not import, reference, or call into `window`, `document`, `HTMLElement`, or any DOM type. To render or take input, the host attaches a surface (next section).
+The editor core is **headless**. It parses the SVG, owns the document IR, accepts commands, and emits state — but it does not import, reference, or call into `window`, `document`, `HTMLElement`, or any DOM type. To render or take input, the host attaches a `Surface` (next section).
 
 ### Surface
 
-A surface is the editor's attachment seam — it mounts the SVG into a host environment, listens for input, and renders HUD overlays. **v1 ships one surface, for the browser DOM.** Non-DOM surfaces (worker-side renderer, React Native, headless test harness) are out of scope.
+A `Surface` is the host-provided rendering and input boundary. The editor pushes paint instructions and HUD descriptors to the surface; the surface pushes normalized input events back. Non-DOM hosts (React Native, worker-side renderer, headless test harness) implement the `Surface` interface themselves. The shipped `domSurface` is the reference implementation used by the React layer.
 
 ```ts
 import { attach_dom_surface } from "@grida/svg-editor/dom";
@@ -169,7 +179,28 @@ const handle = attach_dom_surface(editor, { container });
 handle.detach();
 ```
 
-`@grida/svg-editor/dom` is the only place in this package that imports DOM types. The internal `Surface` type exists for tests and future work; it is not a documented extension point at v1.
+The contract (full surface contract documented separately — out of scope for this README):
+
+```ts
+interface Surface {
+  // editor → surface: paint the document + HUD overlay
+  paint(snapshot: SurfacePaintSnapshot): void;
+
+  // surface → editor: hit-test on screen pixel
+  hit_test(x: number, y: number): NodeId | null;
+
+  // surface → editor: subscribe to normalized input
+  on_input(listener: (event: SurfaceInputEvent) => void): Unsubscribe;
+
+  dispose(): void;
+}
+```
+
+Geometry (world-space bboxes, screen ↔ local projection) is exposed via `editor.geometry`, not the `Surface` itself — the DOM surface registers a `MemoizedGeometryProvider` with the editor on attach so headless callers can query bounds without going through the surface.
+
+`@grida/svg-editor/dom` exports `attach_dom_surface(editor, { container, ... })` as the default DOM implementation, plus the surface-scoped types (`Camera`, `Gestures`, `SnapOptions`, `MemoizedGeometryProvider`, `DomComputedResolver`) that callers writing alternative surfaces or advanced integrations may need. It mounts the SVG into the container, wires pointer / keyboard listeners scoped to that container, and uses native `getBBox` / `getScreenCTM` for geometry. It is the only place in this package that imports DOM types.
+
+The container is **exclusively owned** by the surface. Render toolbars, layer lists, inspectors, and any other interactive chrome as **siblings** of the container, not children. Children of the container interfere with pointer routing (capture redirects, hit-test ordering) and produce silent click breakage. The shipped `SvgEditorCanvas` React component enforces this by creating its own internal div; hosts using `domSurface` / `keynote.attach` directly are responsible for the same discipline. In development, the surface emits a `console.warn` at attach time when the container is non-empty.
 
 ### Lifecycle
 
@@ -179,7 +210,7 @@ editor.detach(): void; // detach current surface, keep editor state
 editor.dispose(): void; // permanent teardown
 ```
 
-`load()`, `serialize()`, `reset()`, commands, and subscriptions all work on the headless editor regardless of whether a surface is attached. The lone DOM-dependent reads — `dom_computed_property` / `dom_computed_paint` — return `null` when no DOM surface is attached.
+`load()`, `serialize()`, `reset()`, commands, and subscriptions all work on the headless editor regardless of whether a surface is attached.
 
 ### External control
 
@@ -196,12 +227,14 @@ editor.state: {
   readonly selection: ReadonlyArray<NodeId>;
   readonly scope: NodeId | null;             // active isolation (group entered via dblclick)
   readonly mode: Mode;                       // "select" | "edit-content"
+  readonly tool: Tool;                       // { type: "cursor" } | { type: "insert", tag } — orthogonal to mode
   readonly dirty: boolean;                   // unsaved changes since load() / serialize()
   readonly can_undo: boolean;
   readonly can_redo: boolean;
-  readonly version: number;                  // bumps on every emit (selection, mutation, history)
-  readonly structure_version: number;        // bumps only on tree-shape / display-label changes;
-                                             // stable across pure attribute writes
+  readonly version: number;                  // bumps on any emission — drag, history, mutation
+  readonly structure_version: number;        // bumps only when tree shape or display-label inputs change
+  readonly geometry_version: number;         // bumps only when something that could shift world bounds changes
+  readonly load_version: number;             // bumps once per `editor.load()` call (constructor doesn't count)
 };
 
 editor.subscribe(fn: (state: EditorState) => void): Unsubscribe;
@@ -212,13 +245,13 @@ editor.subscribe_with_selector<T>(
 ): Unsubscribe;
 ```
 
-`state` is a frozen snapshot. Consumers never destructure into internals; if a view they need isn't here or in the purpose-built views below, that's an API gap.
+`version` fires on every emission and is the right key for "anything could have changed" reads. Use the narrower companions (`structure_version`, `geometry_version`, `load_version`) as cache keys when the data only depends on the corresponding slice — e.g. a hierarchy panel snapshots once per `structure_version` so a drag doesn't invalidate the tree view.
 
-**`version` vs `structure_version`.** `version` ticks on every emission — selection, mutation, history. `structure_version` ticks only when something a hierarchy / layers view cares about changes (a node is added / removed / reordered, text-node content changes, an `id` attribute changes). During a drag, `version` ticks repeatedly while `structure_version` stays put, so a layers panel keyed on `structure_version` doesn't re-render at gesture rate.
+`state` is a frozen snapshot. Consumers never destructure into internals; if a view they need isn't here or in the purpose-built views below, that's an API gap.
 
 ### Observation — properties
 
-This section is about **property semantics on a single node**, following the CSS / SVG spec. Multi-selection aggregation ("mixed values") is deferred for v1 — see [Deferred for v1](#deferred-for-v1).
+This section is about **property semantics on a single node**, following the CSS / SVG spec. Multi-selection ("mixed values") is a separate concern; see the [Multi-selection](#multi-selection-mixed-values) section below. The two are kept apart on purpose: property semantics is defined by the spec; mixed semantics is an aggregation layer the editor adds because it supports multi-select.
 
 The CSS Cascading and Inheritance spec defines a value pipeline of six stages: **declared → cascaded → specified → computed → used → actual** ([css-cascade-5 §4](https://www.w3.org/TR/css-cascade-5/#value-stages)). For an SVG property panel, two stages are useful:
 
@@ -227,9 +260,9 @@ The CSS Cascading and Inheritance spec defines a value pipeline of six stages: *
 
 Plus the editor's own metadata, marked as such:
 
-- **`provenance`** — _editor metadata, not a CSS spec term_. Reports which document carrier won the cascade for this node (presentation attribute, inline style, inherited from parent, defaulted). The cascade itself collapses these into the "author" origin; we surface them because we parsed them.
+- **`provenance`** — _editor metadata, not a CSS spec term_. Reports which document carrier won the cascade for this node (presentation attribute, inline style, stylesheet rule, inherited from parent, defaulted). The cascade itself collapses these into the "author" origin; we surface them because we parsed them.
 
-Intermediate stages (`specified`) and downstream stages (`used`, `actual`) are not exposed.
+Intermediate stages (`specified`) and downstream stages (`used`, `actual`) are not exposed. `specified` differs from `declared` only when CSS-wide keywords are present and is rarely useful to a panel UI. `used` and `actual` are surface-bound and out of scope for the headless editor.
 
 ```ts
 type Provenance = {
@@ -247,30 +280,13 @@ type InvalidComputedValue = {
   reason: string; // e.g. "var(--brand) is not defined and has no fallback"
 };
 
-type PropertyValue<T = string | number> = {
+type PropertyValue<T = string> = {
   declared: string | null;
   computed: T | InvalidComputedValue | null;
   provenance: Provenance;
 };
 ```
 
-#### What v1's cascade engine covers
-
-The headless cascade engine resolves values synchronously without a surface, covering:
-
-- Presentation attributes (`<rect fill="red">`)
-- Inline `style="..."`
-- Inheritance from parent elements
-- The property's initial value
-
-#### What v1's cascade engine does **not** cover
-
-- `<style>` block matching
-- `var()` (custom-property) substitution
-- `currentColor` resolution
-
-For these three, attach a DOM surface and use `editor.dom_computed_property(id, name)` or `editor.dom_computed_paint(id, channel)` (see [Low-level API](#low-level-api)). Those methods delegate to `getComputedStyle()` against the mounted SVG, which the browser implements end-to-end — `<style>` block matching, `var()`, inheritance, the full pipeline. Treat them as the v1 path for "what does the browser actually paint?".
-
 Read — per node:
 
 ```ts
@@ -282,7 +298,9 @@ editor.node_properties(
 
 Property names mirror SVG attribute / CSS property names exactly. No invented schema. Names the editor knows return type-parsed `computed` values (e.g. `opacity` → `number`); unknown names return generic `string`.
 
-Write — selection-scoped. Writing the same value to every selected node has no mixed-value ambiguity, so the write API is selection-scoped without engaging any multi-selection layer:
+Resolving `computed` requires a cascade engine. The editor implements only the subset needed for clean editor DX: [presentation attributes](https://www.w3.org/TR/SVG2/styling.html#PresentationAttributes), inline `style=""`, and rules from `<style>` blocks within the document. External stylesheets are out of scope; declarations from them would fall through to `defaulted` / `inherited` with the inspector surfacing that honestly.
+
+Write — selection-scoped. Writing the same value to every selected node has no mixed-value ambiguity, so the write API is selection-scoped without engaging the multi-selection layer:
 
 ```ts
 editor.commands.set_property(name: string, value: string | null): void;
@@ -300,12 +318,16 @@ The editor decides whether to write a presentation attribute vs. inline style fo
 
 `fill` and `stroke` are common enough — and shape-different enough from a plain string — that they get a dedicated typed API. A solid color, a paint-server reference, and `currentColor` are not interchangeable strings; pretending they are is what produces editors that round-trip badly.
 
+This section, like Properties above, is **per-node and spec-aligned**. Multi-selection aggregation is in the [Multi-selection](#multi-selection-mixed-values) section.
+
 The `Paint` type follows the [SVG 2 `<paint>` production](https://www.w3.org/TR/SVG2/painting.html#SpecifyingPaint) literally:
 
 ```
 <paint> = none | <color> | <url> [none | <color>]? | context-fill | context-stroke
 ```
 
+`<color>` includes `currentColor` per [CSS Color 4 §4](https://www.w3.org/TR/css-color-4/#typedef-color). `inherit` and `var()` are _not_ paint values — they are defaulting / substitution mechanisms that are resolved before the computed value exists (see the property stages above). They appear in `declared` strings but never in a parsed `Paint`.
+
 ```ts
 type Paint =
   | { kind: "none" } // fill="none"
@@ -316,13 +338,15 @@ type Paint =
 
 type PaintFallback = { kind: "none" } | { kind: "color"; value: Color };
 
+// Color preserves currentColor as a keyword at computed time (CSS Color 4 §4.4); the
+// rgb resolution happens at *used* value, which requires the surface's painting context.
 type Color =
   | { kind: "rgb"; value: string } // any resolvable CSS color, normalized to rgb-ish
-  | { kind: "current_color" }; // unresolved keyword; resolve via dom_computed_paint when DOM-attached
+  | { kind: "current_color" }; // unresolved keyword; surface dereferences at paint time
 
 type PaintValue = {
   declared: string | null; // raw, e.g. "var(--brand, currentColor)" or "url(#g1) red"
-  computed: Paint | InvalidComputedValue | null; // post-defaulting; var() reported as invalid in v1
+  computed: Paint | InvalidComputedValue | null; // post-defaulting, post-var
   provenance: Provenance;
 };
 ```
@@ -333,11 +357,11 @@ Read — per node:
 editor.node_paint(id: NodeId, channel: "fill" | "stroke"): PaintValue;
 ```
 
-Notes per spec:
+Notes on the `<url>` reference, per spec:
 
-- A reference to a non-existent id with no fallback paints nothing for that layer. Surfacing this as a warning is **deferred for v1**.
-- `context-fill` / `context-stroke` are only meaningful inside `<marker>` content or a `<use>` shadow tree.
-- Same v1 cascade caveat as for `node_properties`: a `fill` declared in a `<style>` block is **not** resolved by `node_paint`. Use `dom_computed_paint(id, "fill")` when DOM-attached.
+- The fallback (`<url> <color>` or `<url> none`) kicks in only when the URL resolves to a missing or invalid paint server. A valid-but-empty gradient is still valid; the fallback does not apply ([SVG 2 §13.2.1](https://www.w3.org/TR/SVG2/painting.html#FillStrokePaintServer)).
+- A reference to a non-existent id with no fallback paints nothing for that layer (silently skipped, not an error). The editor surfaces this via a warning in the `defs` registry's `subscribe()`.
+- `context-fill` / `context-stroke` are only meaningful inside `<marker>` content or a `<use>` shadow tree ([SVG 2 §13.2.2](https://www.w3.org/TR/SVG2/painting.html#TermContextElement)). Outside those contexts, the editor treats them as no-paint and surfaces a warning.
 
 Write — selection-scoped (same reasoning as for generic properties):
 
@@ -351,15 +375,43 @@ editor.commands.preview_paint(channel: "fill" | "stroke"): {
 };
 ```
 
-Assigning a gradient as fill is a two-step operation by design — the gradient lives in `<defs>` (per SVG), the paint references it. The editor does not auto-inline. Sugar for the common "create new gradient and set as fill in one undo step" case is provided below.
+Assigning a gradient as fill is a two-step operation by design — the gradient lives in `<defs>` (per SVG), the paint references it. The editor does not auto-inline. Sugar for the common "create new gradient and set as fill in one undo step" case is provided by the resource API below.
+
+### Multi-selection (mixed values)
+
+When more than one node is selected, **reading** a property no longer has a single answer — values may agree across the selection, or they may differ ("mixed"). This is its own concept, layered on top of the per-node property and paint APIs above. It is the typical reading mode for a property panel.
+
+This layer is **not deeply designed yet**. The shape will likely look something like:
+
+```ts
+// Provisional — names, contract, and ergonomics subject to design before v0.
+type MixedView<V> =
+  | { status: "single"; value: V } // every selected node agrees
+  | { status: "mixed"; per_node: ReadonlyMap<NodeId, V> } // values differ
+  | { status: "unsupported" } // no selected node has this property
+  | { status: "empty" }; // no selection
+
+editor.selection_properties(names): { readonly [name: string]: MixedView<PropertyValue> };
+editor.selection_paint(channel): MixedView<PaintValue>;
+```
+
+`@grida/mixed-properties` already exists in the monorepo and is the likely starting point, but whether it covers SVG paint and the spec-aligned `PropertyValue` shape cleanly is an open question. Writes do not engage this layer — `set_property` and `set_paint` apply the same value to every selected node and are well-defined as-is.
+
+For v0, the per-node APIs (`node_properties`, `node_paint`) are the stable primitives. Consumers who need to render a property panel today can iterate over `state.selection` and aggregate themselves; the goal of the mixed layer is to give them an ergonomic alternative once its shape is settled.
 
 ### Observation — defs (resources)
 
-SVG forces gradients, patterns, symbols, markers, clip-paths, masks, and filters to live as named entries in `<defs>` and be referenced by `url(#id)`. **v1 ships only the `gradients` registry as a typed view.** The other resource kinds (patterns, symbols, markers, clip-paths, masks, filters) are deferred — to read or walk them at v1, use `editor.document` (see [Low-level API](#low-level-api)).
+SVG forces gradients, patterns, symbols, markers, clip-paths, masks, and filters to live as named entries in `<defs>` and be referenced by `url(#id)`. The editor exposes a typed registry per resource kind. Consumers reading `editor.paint("fill").computed` may encounter a `{ kind: "ref", id }`; they look up the actual gradient via `editor.defs.gradients.get(id)`.
 
 ```ts
 editor.defs: {
   gradients: GradientsApi;
+  patterns: PatternsApi;
+  symbols: SymbolsApi;
+  markers: MarkersApi;
+  clip_paths: ClipPathsApi;
+  masks: MasksApi;
+  filters: FiltersApi;
 };
 
 interface GradientsApi {
@@ -422,6 +474,10 @@ editor.commands.set_paint_from_gradient(
 
 This is one undo step.
 
+The same shape (`list / get / upsert / remove / subscribe`) repeats for `patterns`, `symbols`, `markers`, `clip_paths`, `masks`, `filters`. Each carries its own `*Definition` type that mirrors the SVG spec. None of them are renamed or renormalized — `<linearGradient>` stays `<linearGradient>`, `<marker>` stays `<marker>`.
+
+Markers are referenced via `marker-start` / `marker-mid` / `marker-end` (and the shorthand `marker`), not via `fill`/`stroke`. They appear in the property API the same way any presentation attribute does — read `editor.node_properties(id, ["marker-end"])`, dereference any `{ kind: "ref", id }` via `editor.defs.markers.get(id)`.
+
 ### Observation — tree
 
 ```ts
@@ -440,45 +496,24 @@ editor.tree(): {
 };
 ```
 
-Returns a shallow snapshot. Cheap to call after a `structure_version` bump (and stable across pure attribute writes, so layer-list panels keyed on it don't re-render at gesture rate).
-
-```ts
-editor.display_label(
-  id: NodeId,
-  opts?: { tagLabel?: (tag: string) => string }
-): string;
-```
-
-Single source of truth for "what to call this node in a panel." For `<text>` nodes the label is the (collapsed, truncated) text content; for everything else it's `"tag #id"` when the `id` attribute is present and just `"tag"` otherwise. The optional `tagLabel` resolver lets you substitute friendlier or localized terms ("rect" → "Rectangle") without losing the structural rule. Consumers should call this rather than synthesize their own.
-
-### Observation — surface hover
-
-Out-of-canvas UI (layers panel, breadcrumbs) often wants to mirror the canvas's pointer hover. This is a transient channel — it does **not** bump `state.version`, so listeners don't get full snapshot re-renders.
-
-```ts
-editor.surface_hover(): NodeId | null; // current effective hover (pointer or override)
-editor.set_surface_hover_override(id: NodeId | null): void; // push hover from out-of-canvas UI
-editor.subscribe_surface_hover(cb: () => void): Unsubscribe;
-```
-
-When a layers-panel row is hovered, call `set_surface_hover_override(id)` to push the highlight into the HUD (drives measurement guides, outline, etc.). Pass `null` to release and let the pointer pick take over again. The subscribe channel fires for both pointer-driven and override-driven changes.
+Returns a shallow snapshot. Cheap to call after a `version` bump.
 
 ### Modes
 
 Modes are the editor's internal state machine for "what does a click do." Consumers observe `state.mode`, flip it via commands, but cannot define new modes.
 
 ```ts
-editor.modes: ReadonlyArray<Mode>; // frozen after construction
-// v1: ["select", "edit-content"]
+editor.modes: ReadonlyArray<Mode>; // discoverable, frozen after construction
+// e.g. ["select", "insert-rect", "insert-ellipse", "insert-line", "insert-text", "edit-content"]
 
 editor.commands.set_mode(mode: Mode): void;
 ```
 
-Adding new modes (insertion tools, etc.) requires a PR to this package; per the anti-goals, this is not a vector authoring tool.
+When a mode-driven gesture completes (rect drawn, text inserted), the editor returns to `select` automatically. Modifier keys can override this (Shift to stay in insert mode); that behavior is bundled, not customizable.
 
 ### Commands
 
-The full closed set for v1. Adding a command requires a PR.
+The full closed set. Adding a command requires a PR to this package.
 
 ```ts
 editor.commands.{
@@ -488,8 +523,10 @@ editor.commands.{
   enter_scope(group: NodeId): void;
   exit_scope(): void;
 
-  // mode
+  // mode + tool
   set_mode(mode: Mode): void;
+  // `set_tool` is also accessible as `editor.set_tool(...)`; the command form
+  // is provided so keymap bindings (V/R/O/L) can dispatch via the registry.
 
   // generic property (any SVG/CSS attribute)
   set_property(name: string, value: string | null): void;
@@ -504,20 +541,38 @@ editor.commands.{
     opts?: { reuse_existing?: boolean },
   ): { gradient_id: string };
 
-  // transforms
+  // transforms (atomic — the bundled HUD drives drag-resize-rotate internally)
   translate(delta: { dx: number; dy: number }): void;
+  nudge(direction: "left" | "right" | "up" | "down", step?: number): void;
+  resize(target: { width?: number; height?: number; anchor?: ResizeAnchor }): void;
+  resize_to(target: { width: number; height: number; anchor?: ResizeAnchor }): void;
+  rotate(args: { angle: number; pivot?: { x: number; y: number } }): void;
+  rotate_to(args: { angle: number; pivot?: { x: number; y: number } }): void;
+  flatten_transform(): void;          // bake `transform=` into native attrs where possible
+
+  // alignment (operates on selection of ≥2 nodes against their union bbox)
+  align(direction: AlignDirection): void;
 
   // structure
   reorder(direction: "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back"): void;
+  group(): void;                      // wrap selection in a new <g>
   remove(): void;
 
+  // insertion
+  insert(tag: InsertableTag, attrs?: Readonly<Record<string, string>>): NodeId;
+  insert_preview(tag: InsertableTag, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
+
   // content
   set_text(value: string): void;
+  enter_content_edit(target?: NodeId): boolean;
 
   // file
   load_svg(svg: string): void;
   serialize_svg(): string;
 
+  // cleanup — never silent, never automatic
+  tidy(opts?: TidyOptions): void;
+
   // history
   undo(): void;
   redo(): void;
@@ -526,19 +581,7 @@ editor.commands.{
 
 All commands operate on `state.selection` unless they take an explicit target. Commands that can't apply (e.g. `set_text` with no text node selected) are no-ops, not errors.
 
-**`translate` is a single-step displacement command.** Resize gestures are HUD-driven via a preview session (not via a top-level command — there is no `commands.resize` at v1). Rotate, tidy, and multi-selection aggregation are [Deferred for v1](#deferred-for-v1).
-
-#### Content edit
-
-```ts
-editor.enter_content_edit(target?: NodeId): boolean;
-```
-
-Surface-dependent. With no DOM surface attached, returns `false` and does nothing — the headless editor cannot mount a `<textarea>` / DOM input. With a DOM surface attached, mounts an in-place text editor on the target `<text>` node.
-
-#### Naming convention
-
-Public API uses `snake_case` throughout (`set_property`, `node_paint`, `subscribe_with_selector`). User-facing strings that mirror SVG attribute names stay `kebab-case` exactly as the spec writes them (`set_property("stroke-width", …)`). The exceptions are `FileIOProvider.openSvg` / `saveSvg` and `FontResolver.resolve(...).metrics.unitsPerEm` — these match CSS Font-Metrics / file-API ergonomic naming and stay camelCase.
+(Naming convention for the API surface is `snake_case` to match the SVG / CSS property naming the editor already echoes — `set_property("stroke-width", …)` reads cleanly next to `set_paint("fill", …)`. JavaScript identifiers use `snake_case`; user-facing strings that mirror SVG attribute names stay `kebab-case` exactly as the spec writes them.)
 
 ### Providers
 
@@ -563,8 +606,6 @@ type FileIOProvider = {
 };
 ```
 
-Once constructed, the provider bag is readable as `editor.providers` for code that wants to share the same clipboard / font / file-io plumbing (a Save toolbar, an Open menu item, etc.).
-
 ### Style
 
 `style` is the HUD chrome's appearance spec. It is **values, not slots** — consumers cannot replace the chrome, they restyle it. Field names are `snake_case`. The spec is small and additive.
@@ -577,18 +618,18 @@ type EditorStyle = {
   handle_stroke: string;
   endpoint_dot_radius: number;
   selection_outline_width: number;
-  measurement_color: string; // measurement guide lines + numeric pills
+  // ...
 };
 
 editor.style: Readonly<EditorStyle>;
 editor.set_style(partial: Partial<EditorStyle>): void;
 ```
 
-`set_style` is the legitimate runtime path — wire it up for theme switching.
-
 ### React API (thin wrapper)
 
-The React layer is intentionally thin. We ship a provider, a canvas component, and the **minimum set of hooks needed to bridge React's subscription model to the editor's API**. Hooks for specific observation patterns (per-node properties, gradients list, document tree, etc.) are not exported — they're 5-line recipes consumers write against the editor's own API, tailored to their re-render needs.
+The React layer is intentionally thin. We ship a provider, a canvas component, two core subscription primitives (`useEditorState` + `useCommands`), and a small set of bundled hooks for the patterns that turned out the same across every consumer. Hooks for **per-node** observation patterns (paint, properties, gradients list, document tree) are not exported — those are 5-line recipes consumers write against the editor's own API, tailored to their re-render needs.
+
+#### Core (the primitives)
 
 ```tsx
 import {
@@ -600,14 +641,43 @@ import {
 } from "@grida/svg-editor/react";
 ```
 
-That's the whole public surface.
-
 - `SvgEditorProvider` — owns the headless editor, puts it in context.
-- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container: div })` on mount and `detach()` on unmount.
+- `SvgEditorCanvas` — the only UI component we ship; internally calls `attach_dom_surface(editor, { container })` on mount and `handle.detach()` on unmount. Receives the `DomSurfaceHandle` via an `onAttach` callback so consumers can thread `handle.camera` / `handle.gestures` into surrounding chrome.
 - `useSvgEditor()` — returns the editor instance from context.
 - `useEditorState(selector, equals?)` — subscribes to a slice of `editor.state` and re-renders on change. The subscription primitive.
 - `useCommands()` — sugar for `useSvgEditor().commands`.
 
+#### Bundled hooks (state-slice convenience + lifecycle-aware sessions)
+
+These are not internals to be replaced — they're documented sugar over `useEditorState` and the imperative APIs, with stable contracts. They exist because every consumer wrote the same recipe; per P6, they earned promotion.
+
+```tsx
+import {
+  // state slices (one-line wrappers over useEditorState)
+  useSelection,        // → readonly NodeId[]
+  useTool,             // → Tool
+  useMode,             // → Mode
+  useCanUndo,          // → boolean
+  useCanRedo,          // → boolean
+
+  // lifecycle-aware preview sessions — unmount = discard (never commit)
+  usePaintPreview,     // (channel) → PaintPreviewSession
+  usePropertyPreview,  // (name) → PreviewSession
+
+  // bound imperative actions, stable identity across renders
+  useEditorLoad,       // → (svg: string) => void
+  useEditorSerialize,  // → () => string
+
+  // RAII hover override (clears on unmount if this hook set the override)
+  useHoverOverride,    // → (id: NodeId | null) => void
+
+  // camera bridge (subscribe to a slice of handle.camera without bumping state.version)
+  useCameraSnapshot,   // (handle, selector, fallback) → T
+} from "@grida/svg-editor/react";
+```
+
+The preview hooks (`usePaintPreview` / `usePropertyPreview`) wrap `commands.preview_*` with a React-lifecycle-aware shell whose contract is: **unmount discards, the host commits**. The session returned is reference-stable across renders within one key — `picker open → commit → reopen` works without remounting.
+
 Top-level wiring:
 
 ```tsx
@@ -642,8 +712,14 @@ function Toolbar() {
         ↖
       </ToolButton>
       <ToolButton
-        active={mode === "edit-content"}
-        onClick={() => cmd.set_mode("edit-content")}
+        active={mode === "insert-rect"}
+        onClick={() => cmd.set_mode("insert-rect")}
+      >
+        ▭
+      </ToolButton>
+      <ToolButton
+        active={mode === "insert-text"}
+        onClick={() => cmd.set_mode("insert-text")}
       >
         T
       </ToolButton>
@@ -684,7 +760,7 @@ function PropertyPanel() {
   const selection = useEditorState((s) => s.selection);
   const cmd = useCommands();
 
-  // v1: single-selection path. Multi-selection aggregation is deferred.
+  // v0: single-selection path. Multi-selection arrives with the mixed-values layer.
   if (selection.length !== 1)
     return <MultiSelectionPlaceholder count={selection.length} />;
   const id = selection[0];
@@ -696,7 +772,8 @@ function PropertyPanel() {
   return (
     <>
       {/* PaintInput is consumer-built. `provenance` tells the user whether this
-          value came from an attribute, inline style, was inherited, or defaulted. */}
+          value came from an attribute, inline style, a stylesheet rule, or was
+          inherited / defaulted. */}
       <PaintInput
         label="Fill"
         declared={fill.declared}
@@ -720,111 +797,33 @@ function PropertyPanel() {
 }
 ```
 
-The pattern is the same for `useDocumentTree`, `useNodeProperties`, etc. — consumers compose against the editor's existing `subscribe()` / `.list()` / `.get()` methods. The package does not ship those hooks because every consumer's re-render needs are slightly different (which IDs to watch, which equality function to use, how to memoize the snapshot), and a one-size-fits-all hook is the wrong layer.
+The pattern is the same for `useDocumentTree`, `useNodeProperties`, `useMarkers`, `useSymbols`, etc. — consumers compose against the editor's existing `subscribe()` / `.list()` / `.get()` methods. The package does not ship those hooks because every consumer's re-render needs are slightly different (which IDs to watch, which equality function to use, how to memoize the snapshot), and a one-size-fits-all hook is the wrong layer.
 
 What this means in practice:
 
-- The editor's API (`editor.subscribe`, `editor.node_*`, `editor.defs.gradients.subscribe`, etc.) is the contract. The React wrapper is just plumbing.
+- The editor's API (`editor.subscribe`, `editor.node_*`, `editor.defs.*.subscribe`, etc.) is the contract. The React wrapper is just plumbing.
 - A consumer who decides to use TanStack Query, Jotai, or Zustand instead of `useSyncExternalStore` reaches the same primitives the same way.
 - Adding a built-in hook later (e.g. `useNodePaint`) requires a P6 justification: ≥2 internal consumers and a stable contract.
 
-## Low-level API
-
-Semver-stable from v1, deliberately minimal. These are the escape hatches consumers use when the high-level API doesn't yet cover what they need — typically because v1's scope is intentionally narrow.
-
-```ts
-editor.document; // raw IR handle
-editor.dom_computed_property(id, name); // getComputedStyle when DOM-attached
-editor.dom_computed_paint(id, channel);
-editor.commands.register(id, handler);
-editor.commands.invoke(id, args);
-editor.commands.has(id);
-editor.keymap; // host-controlled bindings
-```
-
-### `editor.document`
-
-The raw in-memory IR handle. Use this for things the high-level API doesn't cover — walking `<defs>` for non-gradient resources, reading attributes the property cascade doesn't surface, inspecting comment / CDATA nodes. **Mutating the IR directly bypasses history.** For app code, prefer the high-level `editor.commands.*`; reach for `editor.document` for tooling, instrumentation, and one-off inspections.
-
-### `editor.dom_computed_property` / `editor.dom_computed_paint`
-
-```ts
-editor.dom_computed_property(id: NodeId, name: string): string | null;
-editor.dom_computed_paint(
-  id: NodeId,
-  channel: "fill" | "stroke"
-): { computed: string; resolved_paint: Paint | null } | null;
-```
-
-DOM-only computed reads. Returns `null` when no DOM surface is attached. When a DOM surface is attached, delegates to `getComputedStyle()` against the mounted SVG element — which honors `<style>` block matching, `var()` substitution, `currentColor`, and the rest of the CSS cascade the headless engine doesn't implement.
-
-These exist because v1 doesn't ship a full headless cascade engine, and we'd rather expose an honest escape hatch than silently lie about `computed` values. As the headless cascade engine grows (post-v1), these methods stay — they remain the only way to ask "what does the browser actually paint?" for cases that depend on user-agent stylesheet, font fallbacks, or rendering-context decisions.
-
-### `editor.commands.register / invoke / has`
-
-```ts
-editor.commands.register(id: CommandId, handler: CommandHandler): () => void;
-editor.commands.invoke(id: CommandId, args?: unknown): boolean;
-editor.commands.has(id: CommandId): boolean;
-
-type CommandId = string; // dotted: "history.undo", "selection.remove", "host.copy"
-type CommandHandler = (args?: unknown) => boolean | void;
-```
-
-Id-keyed command surface for host-registered commands. The package's built-in commands are pre-registered under stable ids (`history.undo`, `selection.deselect`, `transform.nudge`, …); hosts can register their own and address them from the keymap. Handlers return `true` if they consumed the invocation, `false` / `undefined` if they didn't (the keymap will then try the next candidate registered for the same key — ProseMirror-style chain semantics).
-
-### `editor.keymap`
-
-```ts
-editor.keymap.bind(binding: KeymapBinding): () => void;
-editor.keymap.unbind(spec: { keybinding?: Keybinding; command?: CommandId }): void;
-editor.keymap.bindings(): readonly KeymapBinding[];
-editor.keymap.dispatch(event: KeyboardEvent): boolean;
-```
-
-Declarative bindings of `Keybinding` → command id with chain-style dispatch. The package's own keybindings are registered at construction (Undo/Redo, arrow-nudge, bracket-reorder, etc.); host bindings layer on top and chain ahead of defaults when their priority is higher. The DOM surface calls `dispatch(event)` automatically; for non-DOM hosts or custom input loops, call it yourself.
-
-The `@grida/keybinding` package provides the `Keybinding` type, `kb()` / `seq()` / `platformKb()` builders, and the `KeyCode` enum.
-
----
-
-Anything that earns enough use to be a stable primitive graduates out of this section into the high-level API. Anything we add but later regret stays here under a deprecation marker until it can be removed.
-
-## Deferred for v1
-
-What v1 explicitly doesn't ship. Each is documented elsewhere with the v1 workaround.
-
-- **`<style>` block matching, `var()` substitution, `currentColor` resolution** in the headless cascade. Use `dom_computed_property` / `dom_computed_paint` when DOM-attached (see [Low-level API](#low-level-api)).
-- **Defs registries other than gradients** (patterns, symbols, markers, clip-paths, masks, filters). Walk `editor.document` directly.
-- **`commands.resize` (top-level), `commands.rotate`, `commands.tidy`**. Resize gestures are HUD-driven via a preview session; rotate and tidy are unimplemented.
-- **Multi-selection aggregation** (mixed-value property/paint views).
-- **Insertion modes / shape tools.** Anti-goal — "Not a vector authoring tool."
-- **Copy/paste, alt-drag, snap-to-geometry, snap-to-pixel-grid, alignment hotkeys, duplicate (Cmd+D), select-all.**
-- **Non-DOM surfaces** (worker, React Native, headless test harness).
-- **Paint-server validity warnings** (dangling `url(#id)` references).
-- **Rotation gesture in the HUD.**
-
 ## Anti-goals
 
 What this editor will never be. Each one is a defensive perimeter for the principles above.
 
 - **Not a vector authoring tool.** No pen tool, no boolean ops, no path-node sculpting beyond what an SVG-natural edit supports.
 - **Not an animation editor.** SMIL is preserved verbatim, never authored or mutated.
-- **Not a plugin host.** No public registry for tools, capabilities, gestures, HUD overlays, or serializers. The keymap and the command-id registry are host-controlled seams (P2: bindings are a host concern) — see [Low-level API](#low-level-api). (P1, P6.)
+- **Not a plugin host.** No public registry for tools, capabilities, gestures, HUD overlays, or serializers. (P1, P6.)
 - **Not a Figma-style multiplayer canvas.** State is local. Sync is the consumer's problem.
 - **Not customizable in HUD layout.** Style spec only — no overlay slots, no handle replacement, no custom chrome components.
-- **Not a private IR.** SVG is the source of truth; there is no canonical Grida representation behind it.
+- **Not a private IR.** SVG is the source of truth. The editor does not maintain an alternative on-disk format, and the bytes are not projected from any in-memory canonical store. (The internal typed element IR described under [Paradigm § Element IR (internal)](#element-ir-internal) is a typed view over the parsed AST, not a store the file is derived from — the AST and the file are the source of truth, and the IR is rebuilt from them on each load.)
 - **Not a serializer playground.** Round-trip rules are fixed (P1). No "compact mode," no "Prettier mode," no consumer-supplied formatter.
 
 If a consumer needs any of the above, the right answer is "this is the wrong tool." Saying yes to any one is the path that turned the Grida main editor into a 6,800-line god-class.
 
 ## Status
 
-`v1.0.0-alpha.1` — selection, translate, paint editing (solid + gradient), gradient defs, history, reorder, remove, set_text, keyboard shortcuts.
-
-Round-trip fidelity (P1) is the design invariant; the v1 surface is deliberately minimal and the [Low-level API](#low-level-api) is the escape hatch when the high-level API doesn't yet cover what you need.
+- `v0.0.0` — selection only, no mutation.
 
-The shape may still change between alpha and `1.0.0` based on dogfooding feedback. Don't depend on it from production code yet.
+The shape of the API, the mental model, the file-format guarantees, and the scope are all unsettled. Nothing here is stable. Do not depend on it from production code.
 
 ## License