@grida/svg-editor 1.0.0-alpha.2 → 1.0.0-alpha.21

package/README.md

@@ -45,6 +45,22 @@ 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`](https://grida.co/docs/wg/feat-svg-editor/element-ir). The phased migration sketch lands with the implementation slice.
+
+### Defined terms
+
+The editor's design docs use capitalised terms with precise meanings. The one most often referenced in everyday review:
+
+- **[Policy Class](https://grida.co/docs/wg/feat-svg-editor/glossary/policy-class)** — the minimal partition of editable elements such that every editing intent admits the same set of legal solutions within a class. `<circle>` and `<ellipse>` are different Policy Classes because their resize solution spaces fork differently, even though both are conics. The unit at which a host's policy decision (refuse / native / promote / via-transform) maps onto. When a design discussion asks "should X and Y be treated the same?" — apply the Policy Class fork test, not authoring intuition.
+
+Full glossary: [`docs/wg/feat-svg-editor/glossary/`](https://github.com/gridaco/grida/tree/main/docs/wg/feat-svg-editor/glossary/).
+
 ## 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 +79,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 +105,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 +125,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 +149,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
 
@@ -153,13 +171,34 @@ const editor = createSvgEditor({
 });
 ```
 
-`createSvgEditor` is the only constructor. The returned `SvgEditor` is the only object consumers ever hold.
+`createSvgEditor` is the only **editor** constructor. The returned `SvgEditor` is the only editor instance consumers ever hold. A small set of Layer-A geometry primitives (see [Geometry primitives](#geometry-primitives) below) is also exported for callers that need canonical SVG geometry without mounting an editor — those are not editor instances and have no lifecycle.
+
+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).
+
+### Geometry primitives
+
+A small set of Layer-A primitives is exported for callers that want canonical SVG geometry without mounting an editor. These are not part of the editor lifecycle, do not subscribe, and do not produce diffs against an `SvgDocument` — they are pure value classes over the bytes you hand them.
+
+#### `PathModel`
+
+Models a single SVG path's vector network for callers that want path geometry without an editor. Construct from a `d` string, observe vertex/segment shape, compute a bbox, serialize back to `d`. No editor, no document, no DOM.
+
+```ts
+import { PathModel } from "@grida/svg-editor";
+
+const m = PathModel.fromSvgPathD("M 10 10 L 100 10 L 100 100 Z");
+m.vertexCount(); // 3
+m.segmentCount(); // 3
+m.snapshot(); // { vertices, segments } — POJO
+m.bbox(); // { x, y, width, height }
+m.toSvgPathD(); // canonical d
+```
 
-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).
+`@experimental` — the externally-stable contract for v0 is construction (`fromSvgPathD`) plus `snapshot()` / `bbox()` / `vertexCount()` / `segmentCount()` / `toSvgPathD()`. Mutation methods on the class exist for the editor's internal use and are not part of the documented public surface.
 
 ### 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 shipped `domSurface` is the reference implementation used by the React layer; non-DOM hosts (React Native, worker-side renderer, headless test harness) would implement the same interface — though only one implementation exists today (P6: public only after dogfooding).
 
 ```ts
 import { attach_dom_surface } from "@grida/svg-editor/dom";
@@ -169,7 +208,41 @@ 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 v0 contract is pure lifecycle:
+
+```ts
+interface Surface {
+  /** Teardown: detach listeners, drop retained refs. Called from
+   *  `editor.detach()` and `editor.dispose()`. */
+  dispose(): void;
+}
+```
+
+What's deliberately **not** part of the contract yet:
+
+- **Paint push.** There is no `paint(snapshot)` channel. The surface re-serializes the document by subscribing to the editor and writing to its own rendering target.
+- **Normalized input events.** Input routing is surface-private — the DOM surface attaches pointer/keyboard listeners on its own container and reaches the editor through the in-package `_internal` channel.
+- **Hit-testing.** Picking is surface-private: the DOM surface owns its own pointer → node-id resolver against its rendered scene. World-space geometry queries (`bounds_of`, `node_at_point` for non-pointer callers) route through `editor.geometry` instead. A cross-surface `hit_test` contract is deferred until a second surface needs one — its shape (screen vs. world units, z-order tie-breaks, hit-record vs. id) isn't pinned.
+
+Each will become a public seam when a second surface implementation arrives and pins its shape. Until then, exporting `paint(snapshot: unknown)` / `on_input(event: unknown)` / `hit_test(x, y)` would be contracts a foreign implementer cannot honestly satisfy (P6 — public only after dogfooding).
+
+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`, `AttentionScope`, `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. Sibling chrome that drives editor commands should be registered into the attention scope (`handle.attention`, below) so the keymap stays live while the user works in it.
+
+**Attention gate.** The DOM surface installs document- and window-level keydown listeners (so a user with focus on a side-panel button can still hit editor shortcuts while the pointer is on the canvas). Those listeners are gated by an internal attention predicate: a key is claimed (and `preventDefault()`-ed) only when **focus is inside the attention scope OR the pointer is over it**. Body-focus alone — the natural state when the surface is embedded as a block in a longer document — is not attended, so the editor stays out of the way of page-level shortcuts (Space / arrows to scroll, Cmd+= to zoom, etc.). Passive observation listeners (modifier mirrors, blur resets) are not gated — they don't call `preventDefault()` and need to stay live across focus boundaries.
+
+The scope starts as the container alone. Editor-adjacent host chrome — an inspector, a toolbar, a zoom menu; anything that drives `commands.*` — is a DOM sibling of the container (per the exclusive-ownership rule above), so by default the gate cannot tell it from unrelated app surface: clicking its buttons moves focus out of the container, hovering it leaves the container, and the whole keymap (undo / delete / tool keys) goes dark until the user re-attends the canvas. Register such chrome into the scope via the handle:
+
+```ts
+const handle = attach_dom_surface(editor, { container });
+handle.attention.add(inspectorEl); // counts for focus-within + pointer-over
+handle.attention.remove(inspectorEl); // e.g. on unmount
+```
+
+Registered elements get the full keymap — with text inputs inside them still excluded by the keymap's own guard. The native clipboard gate (deliberately stricter: focus-only, never pointer-over) honors the registered set's focus arm the same way. `add` is idempotent; registrations live until removed or the surface detaches.
 
 ### Lifecycle
 
@@ -179,16 +252,39 @@ 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
 
 ```ts
 editor.load(svg: string): void; // replace the document (e.g. file-on-disk changed)
 editor.serialize(): string; // emit clean SVG — guaranteed round-trip per P1
+editor.serialize_node(id: NodeId): string; // emit ONE element's subtree — a fragment, see below
 editor.reset(): void; // back to last load() input, clears history
 ```
 
+`serialize_node(id)` exports the markup of a single element — the bridge from
+"what the user selected" (a `NodeId`) to "the SVG for that element," e.g. to
+hand a downstream consumer (an AI agent) the selected subtree without
+re-serializing the whole document. It reuses `serialize()`'s trivia-preserving
+rules (attribute order, quotes, whitespace, comments — emitted as authored).
+
+It is deliberately **weaker** than `serialize()`, and the two must not be
+conflated: `serialize()` emits the whole document and carries the P1
+round-trip guarantee; `serialize_node()` emits a **fragment** and does not.
+Namespace declarations that live on an ancestor (`xmlns:xlink` and friends,
+normally on the root `<svg>`) are **not** inlined into the fragment — a node
+using `xlink:href` serializes without `xmlns:xlink`. The fragment is the
+element's markup as authored, not a standalone parseable document. Throws on
+an unknown id or a non-element node (selections are always elements).
+
+> A stable reference to a node that survives a `load()` — and survives an
+> external rewrite of the file — is a separate, unsolved problem (`NodeId`
+> regenerates on each parse). Positional child-index paths address only the
+> deterministic-re-parse case, not structural edits; durable node identity is
+> under design — see
+> [durable node identity](https://grida.co/docs/wg/feat-svg-editor/durable-node-identity).
+
 ### Observation — state
 
 ```ts
@@ -196,12 +292,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 +310,32 @@ editor.subscribe_with_selector<T>(
 ): Unsubscribe;
 ```
 
+`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.
+
 `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` 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.
+### Observation — pick (tap)
+
+A **pick** is a discrete tap on the canvas — a press and release within the drag threshold, no drag. It is observe-only and deliberately **separate from selection**: selection answers "what do commands target," a pick answers "what did the user just click, and where." A primary tap on a node both selects it _and_ emits a pick; a tap on empty canvas emits a pick with `node_id: null` (distinguishable from "nothing is selected," which selection alone cannot express); a secondary (right-button) tap emits a pick and does **not** change selection. This is the seam a click-driven host tool needs — a comment / annotation tool anchors UI at `point` and scopes its action to `node_id`, or to the whole document when `null`.
+
+```ts
+type PickEvent = {
+  point: Vec2; // document-space — the pointer-DOWN point the tap resolved against
+  node_id: NodeId | null; // topmost node under point; null = empty canvas
+  button: "primary" | "secondary"; // middle is pan, never taps
+  mods: { shift: boolean; alt: boolean; meta: boolean; ctrl: boolean };
+};
+
+editor.subscribe_pick(fn: (e: PickEvent) => void): Unsubscribe;
+```
+
+The point is document-space and always the pointer-**down** point — so it stays correct even for a tap on an already-selected node (whose selection commits on pointer-up). The channel does **not** bump `state.version`. In React, wire it with `useEditorPick(handler)`.
+
+> **Status:** `@unstable` — shipped against one consumer; the shape is open until a second click-driven tool exercises it (P6).
 
 ### 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 +344,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 +364,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,12 +382,15 @@ 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;
 
 editor.commands.preview_property(name: string): {
+  readonly live: boolean; // false once the session has ended, for any reason
   update(value: string): void;
   commit(): void;
   discard(): void;
@@ -296,16 +399,22 @@ editor.commands.preview_property(name: string): {
 
 The editor decides whether to write a presentation attribute vs. inline style for each selected node based on whichever wins the cascade for that element (P1). The preview session is what a number-input scrub or color-picker drag uses: many `update()` calls during drag, one `commit()` on pointer-up.
 
+A preview session ends as soon as its result can no longer become the document's next state — and after it ends, every method is a no-op and `session.live` is `false`. A discrete write to the same property (`set_property(name, …)`, or `set_paint` / `set_paint_from_gradient` on the same channel) **supersedes** an open session on that name, so a UI that mixes a picker drag with preset buttons cannot replay the stale dragged value when it commits on close; sessions on other property names are unaffected by discrete writes. Operations that detach the session's targets (`remove` / `cut`, `ungroup`), a document swap (`load` / `reset`), and `undo` / `redo` end open sessions on every name. Hosts that cache a session should consult `live` and lazily reopen — the bundled React hooks do.
+
 ### Observation — paint (`fill` / `stroke`)
 
 `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 +425,17 @@ 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: "rgb"; value: string } // canonical lowercase hex (#rrggbb / #rrggbbaa) for any
+  //   literal resolvable without a rendering context (named / hex / rgb() / hsl() / hwb());
+  //   unresolved spaces (lab() / oklch() / color()) pass through as authored
+  | { 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 +446,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):
 
@@ -345,21 +458,50 @@ Write — selection-scoped (same reasoning as for generic properties):
 editor.commands.set_paint(channel: "fill" | "stroke", paint: Paint): void;
 
 editor.commands.preview_paint(channel: "fill" | "stroke"): {
+  readonly live: boolean; // false once the session has ended, for any reason
   update(paint: Paint): void;
   commit(): void;
   discard(): void;
 };
 ```
 
-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 +564,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 +586,29 @@ 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).
+Returns a shallow snapshot. Cheap to call after a `version` bump.
 
-```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.
+### Modes and tools
 
-### Modes
+"What does a click do" is governed by **two orthogonal axes**, both editor-internal — consumers observe them and flip them via commands, but cannot define new values for either.
 
-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.
+- **`Mode`** — what the editor is _doing_. Two values: `select` (normal interaction — pick / marquee / drag) and `edit-content` (inline text edit, or vector content edit on a path).
+- **`Tool`** — what pointer-down _means_ within the current mode. `cursor` (the default — select / marquee / drag), `insert` (a tag — pointer-down draws a new element of that tag, drag-to-size), `insert-text` (click-only — places a single-line `<text>` and enters content-edit immediately; `<text>` has no intrinsic size so it doesn't drag-to-size), and the content-edit-only `lasso` / `bend` (valid only while `mode === "edit-content"` on a path).
 
 ```ts
-editor.modes: ReadonlyArray<Mode>; // frozen after construction
-// v1: ["select", "edit-content"]
+editor.modes: ReadonlyArray<Mode>; // discoverable, frozen after construction — ["select", "edit-content"]
+editor.state.mode: Mode;
+editor.state.tool: Tool;
 
 editor.commands.set_mode(mode: Mode): void;
+editor.set_tool(tool: Tool): void; // also dispatchable as the `tool.set` command (keymap V/R/O/L/T)
 ```
 
-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 tool-driven gesture completes (a shape is drawn, a text element placed), the tool reverts to `cursor` automatically. Modifier keys can override this (e.g. hold to stay in the insert tool); 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 +618,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 +636,87 @@ 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;
+  // `matrix` is SVG `matrix(a b c d e f)` order (the `Matrix2D` tuple).
+  transform(matrix: Matrix2D, opts?: { ids?: NodeId[]; pivot?: { x: number; y: number } }): boolean;
+  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>
+  ungroup(opts?: { id?: NodeId }): boolean; // dissolve a plain structural <g>
+                                      // (clean-structural subset only; refuses
+                                      // groups with visual state — see TODO §10)
   remove(): void;
 
+  // clipboard — the payload is a STANDALONE SVG DOCUMENT, not a private
+  // format (the file is the IR, so the clipboard is the file format).
+  // Copy carries the outbound url(#…)/href reference closure in one
+  // <defs> block and declares borrowed xmlns prefixes on the payload
+  // shell; ancestor transforms / inherited presentation / viewport are
+  // deliberately NOT carried (verbatim policy). Cut = copy + remove as
+  // ONE history step labeled "cut"; undo restores the document and the
+  // clipboard keeps the payload (cut → undo → paste = move). Paste is
+  // synchronous over delivered text (`text ?? internal buffer`) and has
+  // a gesture-grade refusal table: non-parseable environment input is a
+  // no-op `[]`, never a throw (insert_fragment keeps strict semantics).
+  // System-clipboard wiring is the DOM surface's native ClipboardEvent
+  // transport (text/plain = the markup itself) plus the optional
+  // ClipboardProvider seam. Full contract:
+  // https://grida.co/docs/wg/feat-svg-editor/clipboard
+  copy(): string | null;              // payload | null on empty selection; no history
+  cut(): string | null;               // one undoable step; buffer secured before delete
+  paste(text?: string): NodeId[];     // inserted roots (selected); [] = refusal
+
+  // duplicate — the clipboard FRD's SECOND extraction operation
+  // (subtree clone): in-document, so NO defs closure and NO xmlns
+  // shell are carried; subtrees and authored ids clone verbatim
+  // (colliding ids resolve first-in-document-order; Tidy dedups).
+  // Each clone lands as its origin's next sibling (paints above it);
+  // selection moves to the clones; ONE history step. Alt-drag
+  // translate-with-clone consumes the same operation. Repeating
+  // offset: duplicate → move the copy → duplicate repeats the
+  // translate delta (an Alt-drag clone commit arms the same memory);
+  // still one undo step, degrades to in-place when the preconditions
+  // don't hold. Contract:
+  // https://grida.co/docs/wg/feat-svg-editor/subtree-clone
+  duplicate(): NodeId[];              // clone ids (selected); [] = refusal
+
+  // insertion — `tag` is an open string (so paste / RPC can create any element,
+  // e.g. "path"); only the closed `InsertableTag` set gets a pointer-driven
+  // draw gesture and default paint.
+  insert(tag: string, attrs?: Readonly<Record<string, string>>): NodeId;
+  // markup-shaped sibling of `insert` — one or more sibling elements, or a
+  // full `<svg>` doc (the shell is discarded; its children are the content).
+  // Subtrees adopted verbatim; ONE history step; returns root ids in
+  // document order. Authored ids are NEVER rewritten (dedup is Tidy's job);
+  // undeclared `xlink:` / shell-declared prefixes are hoisted onto the root
+  // in the same step. Position is authored content: wrap the fragment in
+  // `<g transform="translate(x y)">` to land it at a point — same single
+  // undo step, no placement opt.
+  insert_fragment(svg: string, opts?: { parent?: NodeId; index?: number; select?: boolean }): NodeId[];
+  insert_preview(tag: string, 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 +725,9 @@ 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
+`transform` composes a general 2×3 affine onto the selection **relative** and **in world space about a pivot** (default: the selection union-bbox center) — `E = T(pivot) · matrix · T(-pivot)` — so a bare `[-1, 0, 0, 1, 0, 0]` is an in-place horizontal flip and `[1, 0, 0, -1, 0, 0]` a vertical one. The editor owns the round-trip: `E` is folded onto each member's transform list as a **single leading `matrix` op** (existing `rotate`/`translate` tokens are preserved after it; repeated applies collapse into one matrix; a net-identity leading matrix is dropped). It refuses (returns `false`, no history) on empty selection, no attached surface, or any member that isn't rotatable (matrix / scale / skew / `<text rotate>` / CSS-property / animated transforms — same gate as `rotate`; Flatten Transform is the recovery path). Flat-doc only: nested transformed ancestors are out of scope.
 
-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 +752,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 +764,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 +787,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
@@ -631,19 +847,27 @@ Everything else is consumer-built against the editor's API. The two patterns:
 
 ```tsx
 function Toolbar() {
-  const mode = useEditorState((s) => s.mode);
-  const cmd = useCommands();
+  // Insertion is the `Tool` axis, not `Mode` — `Mode` is only
+  // "select" / "edit-content". Flip tools via `editor.set_tool(...)`.
+  const tool = useEditorState((s) => s.tool);
+  const editor = useSvgEditor();
   return (
     <>
       <ToolButton
-        active={mode === "select"}
-        onClick={() => cmd.set_mode("select")}
+        active={tool.type === "cursor"}
+        onClick={() => editor.set_tool({ type: "cursor" })}
       >
         ↖
       </ToolButton>
       <ToolButton
-        active={mode === "edit-content"}
-        onClick={() => cmd.set_mode("edit-content")}
+        active={tool.type === "insert" && tool.tag === "rect"}
+        onClick={() => editor.set_tool({ type: "insert", tag: "rect" })}
+      >
+        ▭
+      </ToolButton>
+      <ToolButton
+        active={tool.type === "insert-text"}
+        onClick={() => editor.set_tool({ type: "insert-text" })}
       >
         T
       </ToolButton>
@@ -684,7 +908,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 +920,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 +945,40 @@ 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 customizable selection policy.** What a pick or a marquee selects (the marquee shadow rule, meta routing, additive, and the group-first targeting that lifts a click to its container) is a fixed product decision, owned by the labeled policy layer (`src/selection/`, specs [`docs/marquee-selection.md`](./docs/marquee-selection.md) and [`docs/group-first-targeting.md`](./docs/group-first-targeting.md)). No host hook, provider, or registry swaps it; the opinion lives above the engine, never inside it, and never as a public knob.
+- **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.
+- **Not an input-interception hook.** The pick/tap observation (`subscribe_pick`) reports a click that already happened; it cannot prevent, delay, or replace the editor's own selection and gesture handling. A host that needs to intercept input owns the container and splices its own layer in (the DOM escape hatch) — it does not get a veto through the observation surface.
 
 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.
+- `v0.x` — selection, transform, insert (rect / ellipse / line), inline text
+  edit, and the click-to-place text tool. Experimental.
+
+The shape of the API, the mental model, the file-format guarantees, and the scope are all unsettled. Nothing here is stable — public types still in flux include the `Tool` union (a planned axis split, see `TODO.md` F2). Do not depend on it from production code.
 
-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.
+## Contributing
 
-The shape may still change between alpha and `1.0.0` based on dogfooding feedback. Don't depend on it from production code yet.
+- [`TODO.md`](./TODO.md) — open questions and deferred work, grouped by area.
 
 ## License