@grida/svg-editor 1.0.0-alpha.12 → 1.0.0-alpha.14

package/README.md

@@ -51,7 +51,15 @@ Internally, the editor wraps the parsed SVG in a **typed element IR**: a per-nod
 
 The IR is a **typed view, not alternative storage**. The parsed AST remains the in-memory store; file bytes remain the source of truth; the parse-side source-position trivia store carries whitespace, attribute order, and unknown-namespace content. The IR is rebuilt from the AST on every load and discarded on `dispose`. P1 round-trip stands.
 
-This is consistent with the "Not a private IR" anti-goal below — that anti-goal rejects alternative on-disk format and bytes-projected-from-IR storage, neither of which this is. Design: `docs/wg/feat-svg-editor/element-ir.md`. Migration sketch: `docs/wg/feat-svg-editor/element-ir-migration.md`.
+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
 
@@ -163,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
+```
+
+`@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 host-provided rendering and input boundary. The editor pushes paint instructions and HUD descriptors to the surface; the surface pushes normalized input events back. Non-DOM hosts (React Native, worker-side renderer, headless test harness) implement the `Surface` interface themselves. The shipped `domSurface` is the reference implementation used by the React layer.
+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";
@@ -179,29 +208,32 @@ const handle = attach_dom_surface(editor, { container });
 handle.detach();
 ```
 
-The contract (full surface contract documented separately — out of scope for this README):
+The v0 contract is pure lifecycle:
 
 ```ts
 interface Surface {
-  // editor → surface: paint the document + HUD overlay
-  paint(snapshot: SurfacePaintSnapshot): void;
-
-  // surface → editor: hit-test on screen pixel
-  hit_test(x: number, y: number): NodeId | null;
-
-  // surface → editor: subscribe to normalized input
-  on_input(listener: (event: SurfaceInputEvent) => void): Unsubscribe;
-
+  /** 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`, `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.
 
+**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 container's subtree OR the pointer is over the container**. 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.
+
 ### Lifecycle
 
 ```ts
@@ -498,18 +530,23 @@ editor.tree(): {
 
 Returns a shallow snapshot. Cheap to call after a `version` bump.
 
-### Modes
+### Modes and tools
+
+"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>; // discoverable, frozen after construction
-// e.g. ["select", "insert-rect", "insert-ellipse", "insert-line", "insert-text", "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)
 ```
 
-When a mode-driven gesture completes (rect drawn, text inserted), the editor returns to `select` automatically. Modifier keys can override this (Shift to stay in insert mode); that behavior is bundled, not customizable.
+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
 
@@ -558,9 +595,11 @@ editor.commands.{
   group(): void;                      // wrap selection in a new <g>
   remove(): void;
 
-  // insertion
-  insert(tag: InsertableTag, attrs?: Readonly<Record<string, string>>): NodeId;
-  insert_preview(tag: InsertableTag, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
+  // 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;
+  insert_preview(tag: string, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
 
   // content
   set_text(value: string): void;
@@ -654,25 +693,25 @@ These are not internals to be replaced — they're documented sugar over `useEdi
 ```tsx
 import {
   // state slices (one-line wrappers over useEditorState)
-  useSelection,        // → readonly NodeId[]
-  useTool,             // → Tool
-  useMode,             // → Mode
-  useCanUndo,          // → boolean
-  useCanRedo,          // → boolean
+  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
+  usePaintPreview, // (channel) → PaintPreviewSession
+  usePropertyPreview, // (name) → PreviewSession
 
   // bound imperative actions, stable identity across renders
-  useEditorLoad,       // → (svg: string) => void
-  useEditorSerialize,  // → () => string
+  useEditorLoad, // → (svg: string) => void
+  useEditorSerialize, // → () => string
 
   // RAII hover override (clears on unmount if this hook set the override)
-  useHoverOverride,    // → (id: NodeId | null) => void
+  useHoverOverride, // → (id: NodeId | null) => void
 
   // camera bridge (subscribe to a slice of handle.camera without bumping state.version)
-  useCameraSnapshot,   // (handle, selector, fallback) → T
+  useCameraSnapshot, // (handle, selector, fallback) → T
 } from "@grida/svg-editor/react";
 ```
 
@@ -701,25 +740,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 === "insert-rect"}
-        onClick={() => cmd.set_mode("insert-rect")}
+        active={tool.type === "insert" && tool.tag === "rect"}
+        onClick={() => editor.set_tool({ type: "insert", tag: "rect" })}
       >
         ▭
       </ToolButton>
       <ToolButton
-        active={mode === "insert-text"}
-        onClick={() => cmd.set_mode("insert-text")}
+        active={tool.type === "insert-text"}
+        onClick={() => editor.set_tool({ type: "insert-text" })}
       >
         T
       </ToolButton>
@@ -821,9 +862,14 @@ If a consumer needs any of the above, the right answer is "this is the wrong too
 
 ## Status
 
-- `v0.0.0` — selection only, no mutation.
+- `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.
+
+## Contributing
 
-The shape of the API, the mental model, the file-format guarantees, and the scope are all unsettled. Nothing here is stable. Do not depend on it from production code.
+- [`TODO.md`](./TODO.md) — open questions and deferred work, grouped by area.
 
 ## License