@grida/svg-editor 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,831 @@
+# @grida/svg-editor
+
+Grida SVG Editor is a **clean** SVG editor. Experimental.
+
+## What "clean" means
+
+Open an SVG file, edit it, save it. The diff should be exactly the change you made — nothing more.
+
+Most editors don't do this:
+
+- **Adobe Illustrator** saves files wrapped in its own `<switch>` / `<foreignObject>` / `<i:pgfRef>` scaffolding, converts circles to four-cubic-Bézier paths, stamps elements with generated classes (`.st0`, `.st1`) and ids (`SVGID_1_`), and emits coordinates at eight decimals of precision.
+- **Inkscape** injects its own namespace metadata (`sodipodi:namedview`, `inkscape:version`, `inkscape:groupmode`, ...) on every save, and reformats whitespace, attribute order, and `<defs>` ordering even when nothing was changed.
+- **AI agents** that read and rewrite SVG produce wildly variable output and have no shared discipline for what to preserve.
+
+These tools all _render_ the file correctly. They just leave the markup in a state where the next editor — or the next AI pass, or `git diff` — can't tell what actually changed.
+
+A clean editor:
+
+1. **Round-trips by default.** Open + save without edits → byte-equal output. Comments, whitespace, attribute order, and even legacy or unknown-namespace attributes survive verbatim.
+2. **Mutates minimally.** Change one attribute on one element → one attribute's worth of diff. Nothing else moves.
+3. **Adds no proprietary noise.** No editor-specific namespaces. No invented ids or classes. No reflow of unrelated nodes.
+4. **Is honest about its scope.** SVG is full of constructs that can't be edited cleanly in a graphical UI (cascading CSS, SMIL animation, `<switch>` language branches, foreign-namespace content). The editor preserves them, surfaces them, and refuses to mutate them rather than silently mishandling them.
+
+## Why this matters
+
+The world is moving toward AI-native authoring formats — HTML, CSS, SVG — because they're what large language models read and write fluently. As that shift accelerates, the bottleneck isn't generation. It's _collaboration_: humans and AI editing the same files, in the same repos, taking turns.
+
+Real collaboration requires editors that don't fight the file. Today, none of the obvious options do:
+
+- Illustrator and Inkscape were built as authoring tools, not collaboration tools. They round-trip badly because nothing in their design rewards round-trip fidelity.
+- AI agents produce text but have no stable, shared notion of "minimal change."
+- Figma, Sketch, and Grida-native treat SVG as import/export. The native IR is private; SVG is a foreign format on both ends.
+
+The result is that every round trip damages the file, every commit produces a noisy diff, and AI's next pass conflicts with the editor's last save. Trust erodes. Co-editing becomes unworkable.
+
+This problem is hard for a real reason. SVG was designed to be hand-authored. It supports CSS cascades, scripted animation, foreign-namespace metadata, embedded fonts, and dozens of features that are coherent for a human writer but actively hostile to a canonical editor IR. Most editors solve this by ignoring or normalizing those features — at which point they're no longer editing SVG, they're editing their interpretation of it.
+
+Grida SVG Editor takes the opposite stance: **the file is the source of truth, and the editor's job is to honor it.**
+
+## Paradigm
+
+The public surface is **narrow and stable**: one editor object, a finite command vocabulary, a designed observation API, and a small set of provider hooks. The internal architecture is **composite by necessity** — SVG has ~20 element types with genuinely distinct edit semantics, so per-element capability modules exist, but they are not exported.
+
+The defaults are inverted from how most editor SDKs grow. Default is **core, not customizable**. A new capability is core unless three things are true: customizing it doesn't violate the round-trip invariant, it is genuinely a host concern, and there is no view of the editor's state that would let a consumer build it themselves.
+
+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.
+
+## 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.
+
+### P1. The file format is sovereign.
+
+Any decision that, if customized, would let a consumer corrupt round-trip fidelity, emit proprietary noise, or silently lose preserved metadata is core. Customization is not an option.
+
+### P2. Customize only what the host genuinely owns.
+
+A small, named set of concerns belongs to the embedding product: clipboard, file IO, font resolution, the rendering surface, the HUD chrome style, locale. These are provider hooks at construction (or attached afterwards, in the surface's case). Everything else is editor-decided.
+
+### P3. Per-element semantics are internal architecture, not extension points.
+
+`<rect>`, `<path>`, `<text>`, `<use>`, etc. require modular code organization because they share no edit semantics. They do not require a public registry. The SVG spec is the registry; we implement against it.
+
+### 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.
+
+### 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.
+
+### P6. Public only after dogfooding.
+
+Internal seams stay internal until ≥2 internal consumers have shaped the contract. The default direction of pressure is inward, not outward.
+
+### The deciding table
+
+When a new design decision lands, walk these in order. The first match wins.
+
+| Question                                           | If yes →                                | Why                         |
+| -------------------------------------------------- | --------------------------------------- | --------------------------- |
+| Would customization violate P1 (file sovereignty)? | **Core**, non-customizable              | Editor owns the invariant   |
+| Is this a host-owned concern per P2?               | **Customizable** via provider           | Host knows what we can't    |
+| Is this per-element edit semantics?                | **Internal seam** (P3)                  | Code organization, not API  |
+| Does it pass P5 (reuse or isolated tests)?         | **Separate layer**                      | Earned its separation       |
+| Otherwise                                          | **Core**, internally modular if complex | Default-in, not default-out |
+
+## Approach
+
+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.
+- 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.**
+
+## Examples
+
+A few scenarios this is designed to handle well.
+
+> _"I opened an SVG exported from Illustrator five years ago and nudged a circle 10px to the right."_
+>
+> Diff: one attribute. The Adobe wrapper, the `.st0` classes, the dead gradients, and the wrapping identity-matrix `<g>` layers are all untouched.
+
+> _"My AI agent rewrote a logo file. I want to tweak two colors and commit."_
+>
+> 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."_
+>
+> 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`.
+
+> _"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)).
+
+> _"This file has an Inkscape `<sodipodi:namedview>` block and `inkscape:label` attributes."_
+>
+> Preserved verbatim. Surfaced in a "preserved metadata" panel so the user knows they exist. Never edited; never silently dropped.
+
+> _"This file has a SMIL `<animate>` on a circle's `cx`. I want to move the circle."_
+>
+> The editor freezes the animation at `t=0` for editing, applies the position change to the static `cx` attribute, and preserves the `<animate>` block verbatim. The inspector shows a clear "animated property" badge so the user understands what they're editing.
+
+## Install
+
+```sh
+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.
+
+### Construction
+
+```ts
+import { createSvgEditor } from "@grida/svg-editor";
+
+const editor = createSvgEditor({
+  svg: "<svg ...>...</svg>",
+  providers: {
+    clipboard, // optional
+    fonts, // optional — font availability + metrics resolver
+    file_io, // optional — for "open" / "save as" commands
+  },
+  style: {
+    chrome_color: "#2563eb",
+    handle_size: 8,
+    // ...style spec, snake_case (see "Style" below)
+  },
+});
+```
+
+`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).
+
+### 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.
+
+```ts
+import { attach_dom_surface } from "@grida/svg-editor/dom";
+
+const handle = attach_dom_surface(editor, { container });
+// later:
+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.
+
+### Lifecycle
+
+```ts
+editor.attach(surface: Surface): SurfaceHandle; // returns { detach() }
+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.
+
+### 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.reset(): void; // back to last load() input, clears history
+```
+
+### Observation — state
+
+```ts
+editor.state: {
+  readonly selection: ReadonlyArray<NodeId>;
+  readonly scope: NodeId | null;             // active isolation (group entered via dblclick)
+  readonly mode: Mode;                       // "select" | "edit-content"
+  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
+};
+
+editor.subscribe(fn: (state: EditorState) => void): Unsubscribe;
+editor.subscribe_with_selector<T>(
+  selector: (state: EditorState) => T,
+  fn: (value: T, prev: T) => void,
+  equals?: (a: T, b: T) => boolean,
+): 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` 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 — 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).
+
+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:
+
+- **`declared`** — the literal source string as authored, with CSS-wide keywords (`inherit`, `initial`, `unset`) already resolved per [css-cascade-5 §7.3](https://www.w3.org/TR/css-cascade-5/#defaulting-keywords), but with `var()` and `url(#…)` references preserved verbatim. This is what the file says; this is what round-trips.
+- **`computed`** — the value after [`var()` substitution at computed-value time](https://www.w3.org/TR/css-variables-1/#substitute-a-var) and type-parsing per the property's definition. For paint with `url(#id)`, the reference itself is the computed value (paint servers are not dereferenced at computed time, per [SVG 2 §13.2](https://www.w3.org/TR/SVG2/painting.html#SpecifyingPaint)). If a `var()` cannot resolve, `computed` is a distinct error state ("invalid at computed-value time"), not silently absent.
+
+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.
+
+Intermediate stages (`specified`) and downstream stages (`used`, `actual`) are not exposed.
+
+```ts
+type Provenance = {
+  origin: "author" | "user_agent"; // cascade origin (css-cascade-5 §6.2)
+  carrier: // editor metadata — where in the file the winning declaration lives
+    | "presentation_attribute" // <rect fill="red">
+    | "inline_style" // <rect style="fill: red">
+    | "stylesheet" // matched a <style> block rule
+    | "inherited" // no winning declaration; took parent's computed value
+    | "defaulted"; // no winning declaration; took the property's initial value
+};
+
+type InvalidComputedValue = {
+  error: "invalid_at_computed_value_time";
+  reason: string; // e.g. "var(--brand) is not defined and has no fallback"
+};
+
+type PropertyValue<T = string | number> = {
+  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
+editor.node_properties(
+  id: NodeId,
+  names: ReadonlyArray<string>,
+): { readonly [name: string]: PropertyValue };
+```
+
+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:
+
+```ts
+editor.commands.set_property(name: string, value: string | null): void;
+
+editor.commands.preview_property(name: string): {
+  update(value: string): void;
+  commit(): void;
+  discard(): void;
+};
+```
+
+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.
+
+### 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.
+
+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
+```
+
+```ts
+type Paint =
+  | { kind: "none" } // fill="none"
+  | { kind: "color"; value: Color } // fill="#f00" | fill="red" | fill="currentColor"
+  | { kind: "ref"; id: string; fallback?: PaintFallback } // fill="url(#g1) red"
+  | { kind: "context_fill" } // fill="context-fill" — meaningful in <marker> / <use>
+  | { kind: "context_stroke" };
+
+type PaintFallback = { kind: "none" } | { kind: "color"; value: Color };
+
+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
+
+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
+  provenance: Provenance;
+};
+```
+
+Read — per node:
+
+```ts
+editor.node_paint(id: NodeId, channel: "fill" | "stroke"): PaintValue;
+```
+
+Notes 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.
+
+Write — selection-scoped (same reasoning as for generic properties):
+
+```ts
+editor.commands.set_paint(channel: "fill" | "stroke", paint: Paint): void;
+
+editor.commands.preview_paint(channel: "fill" | "stroke"): {
+  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.
+
+### 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)).
+
+```ts
+editor.defs: {
+  gradients: GradientsApi;
+};
+
+interface GradientsApi {
+  list(): ReadonlyArray<GradientEntry>;
+  get(id: string): GradientEntry | null;
+  upsert(definition: GradientDefinition, opts?: { id?: string }): string; // returns assigned id
+  remove(id: string): void;
+  subscribe(fn: (entries: ReadonlyArray<GradientEntry>) => void): Unsubscribe;
+}
+
+type GradientDefinition =
+  | {
+      kind: "linear";
+      stops: GradientStop[];
+      x1?: number; y1?: number; x2?: number; y2?: number;
+      gradient_units?: "user_space_on_use" | "object_bounding_box";
+      spread_method?: "pad" | "reflect" | "repeat";
+    }
+  | {
+      kind: "radial";
+      stops: GradientStop[];
+      cx?: number; cy?: number; r?: number; fx?: number; fy?: number;
+      gradient_units?: "user_space_on_use" | "object_bounding_box";
+      spread_method?: "pad" | "reflect" | "repeat";
+    };
+
+type GradientStop = { offset: number; color: string; opacity?: number };
+
+type GradientEntry = {
+  id: string;
+  definition: GradientDefinition;
+  ref_count: number; // how many nodes currently reference this gradient
+};
+```
+
+`upsert(definition)` creates a new `<linearGradient>` / `<radialGradient>` (and `<defs>` if absent) and returns its id. If `opts.id` matches an existing entry, the definition is replaced in place. `remove(id)` is rejected if `ref_count > 0` (the editor refuses to leave dangling `url(#id)` references — surface a confirmation in your UI and clear references first).
+
+Assigning a freshly-authored gradient as fill, end-to-end:
+
+```ts
+const id = editor.defs.gradients.upsert({
+  kind: "linear",
+  stops: [
+    { offset: 0, color: "#ff6b35" },
+    { offset: 1, color: "#7fb8e0" },
+  ],
+});
+editor.commands.set_paint("fill", { kind: "ref", id });
+```
+
+For the very common "set fill from picker that just produced a gradient" path, a sugar command exists:
+
+```ts
+editor.commands.set_paint_from_gradient(
+  channel: "fill" | "stroke",
+  definition: GradientDefinition,
+  opts?: { reuse_existing?: boolean }, // dedupe by definition equality
+): { gradient_id: string };
+```
+
+This is one undo step.
+
+### Observation — tree
+
+```ts
+editor.tree(): {
+  readonly root: NodeId;
+  readonly nodes: ReadonlyMap<
+    NodeId,
+    {
+      id: NodeId;
+      tag: string; // "rect" | "g" | "path" | ...
+      name?: string; // from id= or inkscape:label, if present (preserved)
+      parent: NodeId | null;
+      children: ReadonlyArray<NodeId>;
+    }
+  >;
+};
+```
+
+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.
+
+### 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.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.
+
+### Commands
+
+The full closed set for v1. Adding a command requires a PR.
+
+```ts
+editor.commands.{
+  // selection
+  select(target: NodeId | ReadonlyArray<NodeId>, opts?: { additive?: boolean }): void;
+  deselect(): void;
+  enter_scope(group: NodeId): void;
+  exit_scope(): void;
+
+  // mode
+  set_mode(mode: Mode): void;
+
+  // generic property (any SVG/CSS attribute)
+  set_property(name: string, value: string | null): void;
+  preview_property(name: string): PreviewSession;
+
+  // paint — typed sugar for fill / stroke
+  set_paint(channel: "fill" | "stroke", paint: Paint): void;
+  preview_paint(channel: "fill" | "stroke"): PaintPreviewSession;
+  set_paint_from_gradient(
+    channel: "fill" | "stroke",
+    definition: GradientDefinition,
+    opts?: { reuse_existing?: boolean },
+  ): { gradient_id: string };
+
+  // transforms
+  translate(delta: { dx: number; dy: number }): void;
+
+  // structure
+  reorder(direction: "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back"): void;
+  remove(): void;
+
+  // content
+  set_text(value: string): void;
+
+  // file
+  load_svg(svg: string): void;
+  serialize_svg(): string;
+
+  // history
+  undo(): void;
+  redo(): void;
+}
+```
+
+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.
+
+### Providers
+
+Three host-owned seams, all optional.
+
+```ts
+type ClipboardProvider = {
+  read(): Promise<string | null>;
+  write(text: string): Promise<void>;
+};
+
+type FontResolver = {
+  resolve(family: string): Promise<{
+    available: boolean;
+    metrics?: { ascent: number; descent: number; unitsPerEm: number };
+  }>;
+};
+
+type FileIOProvider = {
+  openSvg(): Promise<string | null>; // "open" dialog
+  saveSvg(svg: string, suggestedName?: string): Promise<void>;
+};
+```
+
+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.
+
+```ts
+type EditorStyle = {
+  chrome_color: string; // selection border + handle stroke
+  handle_size: number; // pixels
+  handle_fill: string;
+  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.
+
+```tsx
+import {
+  SvgEditorProvider,
+  SvgEditorCanvas,
+  useSvgEditor,
+  useEditorState,
+  useCommands,
+} 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.
+- `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`.
+
+Top-level wiring:
+
+```tsx
+<SvgEditorProvider
+  svg={initial_svg}
+  providers={{ clipboard, fonts, file_io }}
+  style={{ chrome_color: "#2563eb" }}
+>
+  <Layout>
+    <Toolbar />
+    <SvgEditorCanvas className="flex-1" />
+    <PropertyPanel />
+    <LayerList />
+  </Layout>
+</SvgEditorProvider>
+```
+
+Everything else is consumer-built against the editor's API. The two patterns:
+
+**Pattern A — state slice via the built-in hook.**
+
+```tsx
+function Toolbar() {
+  const mode = useEditorState((s) => s.mode);
+  const cmd = useCommands();
+  return (
+    <>
+      <ToolButton
+        active={mode === "select"}
+        onClick={() => cmd.set_mode("select")}
+      >
+        ↖
+      </ToolButton>
+      <ToolButton
+        active={mode === "edit-content"}
+        onClick={() => cmd.set_mode("edit-content")}
+      >
+        T
+      </ToolButton>
+    </>
+  );
+}
+```
+
+**Pattern B — anything else (per-node reads, resource lists, tree, paint) via a custom hook over `useSyncExternalStore`.** The recipe is the same shape every time:
+
+```tsx
+import { useSyncExternalStore } from "react";
+
+// For per-node property reads, subscribe to the whole editor and re-snapshot.
+// useSyncExternalStore handles reference-equality bailouts.
+function useNodePaint(id: NodeId, channel: "fill" | "stroke") {
+  const editor = useSvgEditor();
+  return useSyncExternalStore(
+    (cb) => editor.subscribe(cb),
+    () => editor.node_paint(id, channel)
+  );
+}
+
+// For defs registries, subscribe to the registry directly — more granular.
+function useGradients() {
+  const editor = useSvgEditor();
+  return useSyncExternalStore(
+    (cb) => editor.defs.gradients.subscribe(cb),
+    () => editor.defs.gradients.list()
+  );
+}
+```
+
+The property panel composes those custom hooks with the built-in ones:
+
+```tsx
+function PropertyPanel() {
+  const selection = useEditorState((s) => s.selection);
+  const cmd = useCommands();
+
+  // v1: single-selection path. Multi-selection aggregation is deferred.
+  if (selection.length !== 1)
+    return <MultiSelectionPlaceholder count={selection.length} />;
+  const id = selection[0];
+
+  const fill = useNodePaint(id, "fill");
+  const stroke = useNodePaint(id, "stroke");
+  const gradients = useGradients();
+
+  return (
+    <>
+      {/* PaintInput is consumer-built. `provenance` tells the user whether this
+          value came from an attribute, inline style, was inherited, or defaulted. */}
+      <PaintInput
+        label="Fill"
+        declared={fill.declared}
+        computed={fill.computed}
+        provenance={fill.provenance}
+        available_gradients={gradients}
+        onPreview={(p) => cmd.preview_paint("fill").update(p)}
+        onCommit={(p) => cmd.set_paint("fill", p)}
+        onCreateGradient={(def) => cmd.set_paint_from_gradient("fill", def)}
+      />
+      <PaintInput
+        label="Stroke"
+        declared={stroke.declared}
+        computed={stroke.computed}
+        provenance={stroke.provenance}
+        available_gradients={gradients}
+        onCommit={(p) => cmd.set_paint("stroke", p)}
+      />
+    </>
+  );
+}
+```
+
+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.
+
+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.
+- 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 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 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.
+
+The shape may still change between alpha and `1.0.0` based on dogfooding feedback. Don't depend on it from production code yet.
+
+## License
+
+MIT