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

package/dist/editor-CxqRhhzP.d.ts

@@ -0,0 +1,2359 @@
+import cmath from "@grida/cmath";
+import vn from "@grida/vn";
+import { AnyNode, AttrToken } from "@grida/svg/parser";
+import { SelectMode } from "@grida/hud";
+import { Keybinding, Platform } from "@grida/keybinding";
+
+//#region src/types.d.ts
+/**
+ * Stable identifier for a node in the editor's document model.
+ *
+ * Independent of any backing representation. Generated when the document is
+ * parsed.
+ */
+type NodeId = string;
+type Vec2 = {
+  x: number;
+  y: number;
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+/**
+ * A 2×3 affine transform in SVG `matrix(a b c d e f)` order — the same
+ * six-number tuple the SVG `transform="matrix(...)"` function takes.
+ *
+ * Applied to a point `(x, y)`:
+ *   x' = a·x + c·y + e
+ *   y' = b·x + d·y + f
+ *
+ * This is the wire shape `commands.transform` accepts. Examples:
+ *   - `[-1, 0, 0, 1, 0, 0]` — horizontal flip (mirror x about the origin)
+ *   - `[1, 0, 0, -1, 0, 0]` — vertical flip (mirror y about the origin)
+ *   - `[1, 0, 0, 1, 0, 0]`  — identity (no-op)
+ *
+ * `commands.transform` re-centers this about a pivot, so the bare flip
+ * tuples become in-place flips about the selection center.
+ */
+type Matrix2D = readonly [a: number, b: number, c: number, d: number, e: number, f: number];
+/**
+ * Observe-only outcome of a discrete pointer **tap** on the canvas: the user
+ * pressed and released within the drag threshold, without dragging. Delivered
+ * through {@link SvgEditor.subscribe_pick} — a transient event, never part of
+ * `EditorState` (it would be stale on the next snapshot).
+ *
+ * A pick is 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"); a secondary (right-button) tap emits a pick and does NOT
+ * change selection. This is what a click-driven host tool (annotation, context
+ * menu, custom selection) needs and selection alone cannot express.
+ *
+ * Observe-only: a pick reports a click that already happened. It cannot
+ * prevent or replace the editor's own selection handling.
+ *
+ * @unstable Shape is provisional until ≥2 consumers exercise it. Fields may
+ * change without a semver bump until then.
+ */
+type PickEvent = {
+  /** Document-space point the tap resolved against (the pointer-DOWN point). */point: Vec2; /** Topmost node under `point`, or `null` for empty canvas / background. */
+  node_id: NodeId | null; /** Which button produced the tap. `"middle"` is pan and never taps. */
+  button: "primary" | "secondary"; /** Modifier snapshot at press time. */
+  mods: {
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+    ctrl: boolean;
+  };
+};
+type Mode = "select" | "edit-content";
+/**
+ * SVG element tags inserted by the **drag-to-size** subsystem. Closed set;
+ * adding a new insertable tag requires a PR.
+ *
+ * `text` is intentionally NOT here. It is creatable (the `insert-text`
+ * tool — see {@link Tool}), but via a **click-only** gesture, not
+ * drag-to-size: `<text>` has no intrinsic size, so there is nothing for a
+ * drag to set. Its creation path mounts the inline content-editor
+ * immediately. Design: `docs/wg/feat-svg-editor/text-tool.md`.
+ */
+type InsertableTag = "rect" | "ellipse" | "line";
+/**
+ * Active tool — orthogonal to `Mode`. `Mode` is what the editor is doing
+ * (interacting normally vs. inline text edit); `Tool` is what pointer-down
+ * does while in `select` mode.
+ *
+ *  - `cursor` (default): pointer-down selects / starts marquee / drags
+ *    selection (existing HUD-driven behavior).
+ *  - `insert`: pointer-down opens an insertion-preview gesture for the
+ *    given tag. Click-no-drag inserts a default-sized node; drag sizes
+ *    the new node. Tool reverts to `cursor` after commit.
+ */
+type Tool = {
+  type: "cursor";
+} | {
+  type: "insert";
+  tag: InsertableTag;
+}
+/**
+ * Text creation tool. A select-mode tool like `insert`, but **click-only**
+ * rather than drag-to-size: pointer-down creates a single-line `<text>` at
+ * the click point with default appearance and immediately enters
+ * content-edit (caret active). `<text>` has no intrinsic size, so the
+ * drag-to-size model doesn't apply; a drag box would mean SVG 2 wrapped
+ * text, which is a separate (out-of-scope) model. Reverts to `cursor`
+ * after the node is placed. Design:
+ * `docs/wg/feat-svg-editor/text-tool.md`.
+ */
+| {
+  type: "insert-text";
+}
+/**
+ * Vector content-edit lasso (Q). Empty-space drag draws a freeform
+ * polygon that picks vertices + tangents inside it (segments are NOT
+ * tested — matches the main editor decision; see `@grida/hud`
+ * `VectorSelectionMode`). Valid only while `state.mode === "edit-content"`
+ * on a path; tool reverts to cursor on path-content-edit exit.
+ */
+| {
+  type: "lasso";
+}
+/**
+ * Vector content-edit bend. Sticky version of holding Meta — every
+ * segment-body drag bends instead of translating, regardless of
+ * Meta state. See `@grida/hud` `VectorBendMode`. Valid only while
+ * `state.mode === "edit-content"` on a path; tool reverts to cursor
+ * on path-content-edit exit.
+ */
+| {
+  type: "bend";
+};
+declare const TOOL_CURSOR: Tool;
+type Provenance = {
+  /** CSS cascade origin (css-cascade-5 §6.2). */origin: "author" | "user_agent"; /** Editor metadata — where in the file the winning declaration lives. */
+  carrier: "presentation_attribute" | "inline_style" | "stylesheet" | "inherited" | "defaulted";
+};
+type InvalidComputedValue = {
+  error: "invalid_at_computed_value_time";
+  reason: string;
+};
+type PropertyValue<T = string | number> = {
+  declared: string | null;
+  computed: T | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+/**
+ * Computed-time color. `current_color` stays a keyword (CSS Color 4 §4.4)
+ * — its rgb resolution happens at *used* value, which needs the surface's
+ * painting context.
+ *
+ * For `rgb`, `value` is canonical lowercase hex — `#rrggbb`, or
+ * `#rrggbbaa` when alpha < 1 — whenever the literal is resolvable without
+ * a rendering context (named colors, hex, `rgb()`, `hsl()`, `hwb()`).
+ * Literals the editor does not resolve (`lab()` / `oklch()` / `color()` —
+ * gamut mapping out of scope) pass through as authored. The authored
+ * string is always available on the `declared` channel.
+ */
+type Color = {
+  kind: "rgb";
+  value: string;
+} | {
+  kind: "current_color";
+};
+type PaintFallback = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+};
+type Paint = {
+  kind: "none";
+} | {
+  kind: "color";
+  value: Color;
+} | {
+  kind: "ref";
+  id: string;
+  fallback?: PaintFallback;
+} | {
+  kind: "context_fill";
+} | {
+  kind: "context_stroke";
+};
+type PaintValue = {
+  declared: string | null;
+  computed: Paint | InvalidComputedValue | null;
+  provenance: Provenance;
+};
+type GradientStop = {
+  offset: number;
+  color: string;
+  opacity?: number;
+};
+type LinearGradientDefinition = {
+  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";
+};
+type RadialGradientDefinition = {
+  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 GradientDefinition = LinearGradientDefinition | RadialGradientDefinition;
+type GradientEntry = {
+  id: string;
+  definition: GradientDefinition;
+  ref_count: number;
+};
+type EditorStyle = {
+  chrome_color: string;
+  handle_size: number;
+  handle_fill: string;
+  handle_stroke: string;
+  endpoint_dot_radius: number;
+  selection_outline_width: number;
+  /**
+   * Color for measurement guides (distance lines + numeric pills). Distinct
+   * from `chrome_color` so the user can tell at a glance whether something
+   * is selection chrome or a measurement readout.
+   */
+  measurement_color: string; /** `W × H` pill under each selected node, in `chrome_color`. */
+  show_size_meter: boolean;
+  /** Snap to neighbor edges, centers, and equidistant spacing during
+   *  translate. Both behavior and guides are off when `false`. */
+  snap_enabled: boolean;
+  /** Snap activation distance in HUD container pixels. Touch UIs may
+   *  prefer larger (~10–12); precision UIs smaller (~3–4). */
+  snap_threshold_px: number;
+  /** Hit-test tolerance in screen CSS pixels. The picker selects a node
+   *  whose rendered geometry is within this many pixels of the pointer,
+   *  making thin elements (1-px lines, hairline strokes) selectable
+   *  without pixel-perfect aiming. Tolerance is screen-space, not
+   *  world-space — the band stays the same width on screen regardless
+   *  of zoom. `0` disables fat-hit and falls back to elementFromPoint
+   *  exact-pixel selection. */
+  hit_tolerance_px: number;
+  /** Snap-to-pixel-grid quantization for translate. When `true`, every
+   *  translate (drag, nudge, RPC) snaps the agent-union origin to integer
+   *  multiples of `pixel_grid_size` as the final pipeline stage — composes
+   *  on top of snap-to-geometry, which still emits guides as usual. Default
+   *  `false` for SVG-fidelity: SVG paths are unitless and frequently
+   *  fractional; forcing integers would corrupt authored geometry.
+   *
+   *  Naming: this is the *action* flag (snap to the pixel grid). The
+   *  "pixel grid" itself — a visual integer-pixel overlay — is a separate
+   *  feature (see `@grida/canvas-pixelgrid`) and is unrelated. */
+  snap_to_pixel_grid: boolean;
+  /** Quantum size in HUD container pixels (`1` = integer grid). Ignored
+   *  when `snap_to_pixel_grid` is false. */
+  pixel_grid_size: number;
+  /** Show the visual pixel-grid overlay on the HUD. Independent of
+   *  `snap_to_pixel_grid` — this is the *display* flag, that one is the
+   *  *action* flag. The grid is zoom-gated; it only paints at high zoom
+   *  (see `@grida/hud` `setPixelGrid` for the threshold). Default `true`. */
+  pixel_grid: boolean;
+  /** Shift-drag snap step for rotation, in radians. Default π/12 (15°).
+   *  When `null` or `<= 0`, shift-rotate is free (no quantization). */
+  angle_snap_step_radians: number | null;
+};
+declare const DEFAULT_STYLE: EditorStyle;
+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>;
+  saveSvg(svg: string, suggestedName?: string): Promise<void>;
+};
+type Providers = {
+  clipboard?: ClipboardProvider;
+  fonts?: FontResolver;
+  file_io?: FileIOProvider;
+};
+type EditorState = {
+  readonly selection: ReadonlyArray<NodeId>;
+  readonly scope: NodeId | null;
+  readonly mode: Mode;
+  /**
+   * Active tool — orthogonal to `mode`. Default `{ type: "cursor" }`. While
+   * in `select` mode + `insert` tool, pointer-down on the surface starts
+   * an insertion gesture for the configured tag instead of selection.
+   * Switched via `editor.set_tool(...)` or the bundled `tool.set` keymap
+   * (V/R/O/L). Bumps `state.version` only.
+   */
+  readonly tool: Tool;
+  readonly dirty: boolean;
+  readonly can_undo: boolean;
+  readonly can_redo: boolean;
+  /**
+   * Bumps on every editor emission. Use this when you need to react to
+   * any change — selection, history, mutation. NOT a good cache key for
+   * tree-shape views because it fires on attribute writes too (e.g. x/y
+   * during a drag).
+   *
+   * NOT a content fingerprint either: this bumps on UI-state emissions
+   * (selection, scope, mode, tool) that leave the serialized SVG
+   * unchanged. For "did the document content change?" use
+   * {@link content_version}.
+   */
+  readonly version: number;
+  /**
+   * Bumps on every document mutation — insert, remove, reorder, attribute
+   * write, style write, undo, redo, load. Stable across pure UI-state
+   * emissions (selection, scope, mode, tool).
+   *
+   * The honest fingerprint for serialized content: if `content_version`
+   * is unchanged, `editor.serialize()` returns the same bytes. Use this
+   * — not `version` — as the freshness token when persisting, diffing,
+   * or hashing the document.
+   */
+  readonly content_version: number;
+  /**
+   * Bumps only when the document's tree shape or display-label-affecting
+   * data changes — node added/removed/reordered, text content, or the
+   * `id` attribute. Stable across pure presentation-attribute writes.
+   *
+   * The right cache key for hierarchy / layers panels: snapshot once per
+   * `structure_version` so a drag doesn't invalidate the tree view.
+   */
+  readonly structure_version: number;
+  /**
+   * Bumps when any change occurs that could shift a node's world-space
+   * bounds — geometry-affecting attribute writes (x, y, d, transform,
+   * font-size, …), text content, or structure (insert/remove). Stable
+   * across pure presentation writes (fill, stroke-color, opacity).
+   *
+   * Cache key for `GeometryProvider` — bounds caches snapshot on this
+   * so a fill-color change doesn't invalidate them.
+   */
+  readonly geometry_version: number;
+  /**
+   * Bumps once per `editor.load(svg)` call. Distinct from
+   * `structure_version` (which bumps on edits too). Starts at 0; the
+   * constructor's initial SVG does NOT count as a load. Use this when
+   * you want to react to "a new document was loaded" — e.g. refit
+   * camera to the new root, reset host-side UI state, clear per-file
+   * scratch — without firing on text edits, reorders, or deletes.
+   *
+   * Monotonic, never resets.
+   */
+  readonly load_version: number;
+};
+type Unsubscribe = () => void;
+type ReorderDirection = "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back";
+/**
+ * Continuous-gesture write session returned by
+ * `commands.preview_property(name)`: many `update()` calls during a drag,
+ * one `commit()` (→ single history step) or `discard()` (→ no step).
+ *
+ * Lifecycle invariant: **the session ends as soon as its result can no
+ * longer become the document's next state** — and after it ends, for any
+ * reason, every method is a no-op (never a throw) and `live` is `false`.
+ * The ending events:
+ *
+ * - `commit()` / `discard()` — the host closes the gesture;
+ * - a discrete write to the same property (`set_property(name, …)`, and
+ *   for paint channels `set_paint` / `set_paint_from_gradient`, which
+ *   write through it) — the discrete write is the user's final intent
+ *   and a later `commit()` must not replay the stale previewed value;
+ * - opening a second session on the same name (same supersession rule);
+ * - an operation that detaches the session's target nodes (`remove` /
+ *   `cut`, `ungroup`) — sessions on EVERY name end, since the deltas
+ *   would target detached nodes;
+ * - a document swap (`load` / `reset`) — every NodeId dies wholesale;
+ * - `undo` / `redo` — history discards all in-flight previews.
+ *
+ * A defensive `discard()` before a discrete write is valid but not
+ * required. Sessions on OTHER property names are untouched by discrete
+ * writes. Hosts that cache a session across renders should consult
+ * `live` and lazily reopen — the bundled React hooks do this.
+ *
+ * Known exclusion: the discrete GEOMETRY commands (`translate` / `nudge`,
+ * `resize*`, `rotate*`, `align`, `transform`, `flatten_transform`) write
+ * `x` / `y` / `width` / `height` / `transform` through their own
+ * pipelines and do NOT yet supersede a same-name property session —
+ * avoid mixing `preview_property` on geometry attributes with those
+ * commands until that lands.
+ */
+type PreviewSession = {
+  /** `true` while the session can still affect the document; `false`
+   *  once it has ended for any of the reasons above. */
+  readonly live: boolean;
+  update(value: string): void;
+  commit(): void;
+  discard(): void;
+};
+/** `PreviewSession` over typed `Paint` values, from
+ *  `commands.preview_paint(channel)`. Same lifecycle and supersession
+ *  contract — the channel ("fill" / "stroke") is the property name. */
+type PaintPreviewSession = {
+  readonly live: boolean;
+  update(paint: Paint): void;
+  commit(): void;
+  discard(): void;
+};
+/**
+ * Preview-bracketed insertion gesture. Returned by
+ * `editor.commands.insert_preview(...)`. The pending node is created and
+ * inserted immediately (so the HUD selection chrome renders); per-frame
+ * geometry writes call `update(attrs)`; `commit()` collapses the gesture
+ * into a single undo step; `discard()` rolls back as if the gesture never
+ * happened.
+ */
+type InsertPreviewSession = {
+  /** The live node, addressable during drag. */readonly id: NodeId;
+  update(attrs: Readonly<Record<string, string>>): void;
+  commit(): void;
+  discard(): void;
+};
+//#endregion
+//#region src/core/camera.d.ts
+/**
+ * Returns world-space bounds for the given target, or `null` when
+ * unresolvable (e.g. empty selection, unknown node id). Implemented by the
+ * surface — the camera itself has no view into the document.
+ *
+ * Only string targets are passed to the resolver — `Rect` targets are
+ * handled by the camera as identity (the rect IS its own bounds).
+ */
+type BoundsResolver = (target: "<root>" | "<selection>" | NodeId) => Rect | null;
+type CameraOptions = {
+  resolve_bounds: BoundsResolver;
+  initial?: cmath.Transform;
+};
+/**
+ * Camera viewport constraint. Discriminated union with `type` so future
+ * variants (`'contain'`, `'pan-region'`) can be added without breaking
+ * existing call sites — each future variant has its own payload shape.
+ *
+ * v1.1 ships only `'cover'`. CSS analogy: `object-fit: cover` — the
+ * bounds rect covers the viewport edge-to-edge. Zoom is lower-bounded
+ * at fit-with-padding; pan is clamped so the bounds always covers the
+ * viewport. Use for slide / page / kiosk UX where the user should
+ * never see past the artwork.
+ */
+type CameraConstraints = {
+  /** Bounds cover viewport (viewport ⊆ bounds). Keynote / slide UX. */type: "cover"; /** World-space rect, or `"<root>"` to resolve via BoundsResolver. */
+  bounds: Rect | "<root>"; /** Screen-pixel breathing room between bounds and viewport edge. */
+  padding?: number;
+  /**
+   * Screen-pixel scroll slack past the bounds edge when zoomed in past fit.
+   * Applies only on axes where the bounds strictly exceed the viewport
+   * (`sw > vp_w` / `sh > vp_h`); the centered branch is unchanged, so a
+   * fitted axis stays locked at center. Hard clamp — no elasticity, no
+   * bounce-back. Default 0 (strict cover behavior). Negative values are
+   * clamped to 0. Values approaching or exceeding the bounds extent are
+   * permitted but produce visually degenerate behavior; the constraint
+   * makes no attempt to cap.
+   */
+  pan_overshoot?: number;
+};
+/**
+ * Surface-scoped pan/zoom state.
+ *
+ * The public shape leads with the peer convention (`center` / `zoom` /
+ * `bounds`) and keeps the matrix as an advanced read. Methods mirror
+ * Figma/Penpot where they overlap.
+ */
+declare class Camera {
+  private _transform;
+  private viewport_w;
+  private viewport_h;
+  private listeners;
+  private resolve_bounds;
+  private _constraints;
+  constructor(opts: CameraOptions);
+  /**
+   * Current viewport constraint, or `null` for free pan/zoom. Set with
+   * `camera.constraints = { type: 'cover', bounds: '<root>', padding: 80 }`
+   * to clamp zoom + pan; assign `null` to clear.
+   *
+   * Constraints are applied synchronously inside `set_transform` (and
+   * `_set_viewport_size`), so every public mutation respects them
+   * automatically — the host never needs to subscribe-and-clamp itself.
+   */
+  get constraints(): CameraConstraints | null;
+  set constraints(c: CameraConstraints | null);
+  /** Underlying 2D affine. World→screen. */
+  get transform(): cmath.Transform;
+  /** Uniform scale factor. 1 = 100 %. */
+  get zoom(): number;
+  /** World-space point currently at viewport center. */
+  get center(): Vec2;
+  /** World-space rectangle visible in the viewport. */
+  get bounds(): Rect;
+  /** Translate the camera by a screen-space delta. */
+  pan(delta_screen: Vec2): void;
+  /**
+   * Multiply zoom by `factor` keeping `origin_screen` fixed in world space.
+   * Used by wheel-zoom-at-cursor and pinch-zoom.
+   */
+  zoom_at(factor: number, origin_screen: Vec2): void;
+  /** Pan so `c` lands at the viewport center. Zoom unchanged. */
+  set_center(c: Vec2): void;
+  /** Set zoom directly; pivot defaults to viewport center. */
+  set_zoom(z: number, pivot_screen?: Vec2): void;
+  /**
+   * Replace the entire transform.
+   *
+   * Idempotent: when the new transform is element-wise equal to the current
+   * one, this is a no-op (no notification fires). This is the seam that
+   * makes external constraint loops (e.g. "subscribe → compute clamped →
+   * set_transform") terminate: the clamp re-emits the same transform on
+   * the second pass, set_transform short-circuits, no recursion.
+   *
+   * When `camera.constraints` is non-null, the input transform is clamped
+   * synchronously before being stored — every public mutation respects the
+   * constraint automatically.
+   */
+  set_transform(t: cmath.Transform): void;
+  /** Viewport size in screen pixels. Read by host code computing constraints. */
+  get viewport_size(): {
+    width: number;
+    height: number;
+  };
+  /**
+   * Fit a target into the viewport.
+   *
+   * - `"<root>"` — the document root's content bounds (host-resolved).
+   * - `"<selection>"` — current editor.state.selection's union bounds.
+   * - `NodeId` — that node's content bounds.
+   * - `Rect` — an explicit world-space rectangle.
+   *
+   * No-ops if the target resolves to `null` (e.g. empty selection) or if
+   * the viewport size is 0 (no container).
+   */
+  fit(target: "<root>" | "<selection>" | NodeId | Rect, opts?: {
+    margin?: number;
+  }): void;
+  /** Snap back to identity. */
+  reset(): void;
+  /**
+   * Subscribe to camera changes. Fires on every mutation. Cheap channel —
+   * does NOT bump `editor.state.version`. Same pattern as
+   * `editor.subscribe_surface_hover`.
+   */
+  subscribe(cb: () => void): Unsubscribe;
+  /** @internal Surface drives this on container resize. */
+  _set_viewport_size(w: number, h: number): void;
+  /** Convert a screen-space point to world-space. */
+  screen_to_world(p: Vec2): Vec2;
+  /** Convert a world-space point to screen-space. */
+  world_to_screen(p: Vec2): Vec2;
+  /**
+   * Apply the current constraint (if any) to a candidate transform.
+   * Pure: returns the clamped result, never mutates state. Returns the
+   * input unchanged when constraints are null / bounds are unresolvable /
+   * viewport is 0.
+   */
+  private apply_constraints;
+  /**
+   * Re-clamp the stored transform against the current constraint. Called
+   * from the `constraints` setter; `_set_viewport_size` has its own
+   * notify-inclusive path.
+   */
+  private reenforce;
+  private notify;
+}
+//#endregion
+//#region src/core/align.d.ts
+type AlignDirection = "left" | "right" | "top" | "bottom" | "horizontal_centers" | "vertical_centers";
+//#endregion
+//#region src/core/document.d.ts
+/**
+ * What `is_vector_edit_target` returns when a node is eligible for
+ * vector (vertex) editing — a tag-discriminated snapshot of the authored
+ * geometry attributes at enter time.
+ *
+ * Consumed by `VectorEditSession` (which holds it as `source_attrs`) and by
+ * `PathModel` (whose `toNativeAttrs(source_tag)` decides on each commit
+ * whether the post-edit form is still expressible in the source tag, or
+ * whether the element must promote to `<path d="…">`).
+ *
+ * Geometry conventions:
+ *   - All coordinates are in the element's own local space, exactly as
+ *     authored. No `transform=` resolution, no parent CTM, no viewport
+ *     remap.
+ *   - `line` carries its two endpoints; `polyline` / `polygon` points are
+ *     `[x, y]` tuples so the consumer can hand them straight to
+ *     `vn.fromPolyline` / `vn.fromPolygon`.
+ *   - `rect` / `circle` / `ellipse` carry their native geometry numbers.
+ *     These geometry primitives have no addressable interior vertices in
+ *     their native form, so editing one as vector geometry re-types the
+ *     element to `<path>` (see `retype_to_path`). The document holds the
+ *     native tag until that re-type is committed. Design:
+ *     `docs/wg/feat-svg-editor/promote-to-path.md`.
+ *
+ * Re-type vs. native writeback is decided per edit, not per tag: an edit
+ * that the source tag can still express (a straight vertex move on
+ * `line` / `polyline` / `polygon`) writes back natively; one it cannot (a
+ * curve, or a topology change that leaves the tag's canonical form)
+ * re-types the element to `<path>`.
+ */
+type VectorEditSource = {
+  kind: "path";
+  d: string;
+} | {
+  kind: "line";
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+} | {
+  kind: "polyline";
+  points: ReadonlyArray<readonly [number, number]>;
+} | {
+  kind: "polygon";
+  points: ReadonlyArray<readonly [number, number]>;
+} | {
+  kind: "rect";
+  x: number;
+  y: number;
+  width: number;
+  height: number; /** Corner radii; `0` when the rect has square corners. */
+  rx: number;
+  ry: number;
+} | {
+  kind: "circle";
+  cx: number;
+  cy: number;
+  r: number;
+} | {
+  kind: "ellipse";
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+};
+/**
+ * Opaque reversal token returned by `retype_to_path`. Callers hold it and
+ * hand it back to `revert_retype` to restore the original primitive
+ * byte-for-byte; they do not inspect it. All trivia / attribute-token
+ * knowledge stays inside `SvgDocument`.
+ */
+type RetypeRecord = {
+  readonly prev_local: string;
+  readonly prev_raw_tag: string;
+  /** Geometry attribute tokens removed on re-type, with their original
+   *  index in the element's `attrs` array. Ascending by index so they can
+   *  be spliced back in order. Typed as the document's internal attr token. */
+  readonly removed: ReadonlyArray<{
+    index: number;
+    token: AttrToken;
+  }>;
+  /** True iff the re-type added a synthetic `fill="none"` (the `<line>`
+   *  fidelity guard — see `retype_to_path`). `revert_retype` removes it. */
+  readonly added_fill_none?: boolean;
+};
+interface DocumentEvents {
+  /** Fires after any structural mutation. */
+  on_change(fn: () => void): () => void;
+}
+declare class SvgDocument implements DocumentEvents {
+  private nodes;
+  private prolog;
+  private epilog;
+  /** Snapshot of the input string, used for `reset()`. */
+  private source;
+  /** Original parse result, for `reset()`. */
+  private original;
+  readonly root: NodeId;
+  private listeners;
+  /**
+   * Counter that bumps ONLY when something the hierarchy view cares about
+   * changes — tree topology (`insert`/`remove`), text-node content
+   * (`set_text`), or the `id` attribute (which feeds display labels). Pure
+   * presentation-attribute writes (x, y, fill, …) do NOT bump it.
+   *
+   * Why a separate counter: consumers like the layers panel cache snapshots
+   * keyed on this. During a drag, x/y writes fire `emit()` repeatedly but
+   * `structure_version` stays stable, so the panel's snapshot reference
+   * stays the same and React skips the re-render of the whole tree.
+   */
+  private _structure_version;
+  /** Total listener-visible mutation count. See the `revision` getter. */
+  private _revision;
+  /** Bumps on writes that can shift world-space bounds (`GEOMETRY_ATTRS`,
+   *  `set_text`, `insert`, `remove`). Cache key for `GeometryProvider`;
+   *  see ../../docs/geometry.md. */
+  private _geometry_version;
+  constructor(svg: string);
+  static parse(svg: string): SvgDocument;
+  /** Reload from the original parse, discarding all edits. */
+  reset_to_original(): void;
+  /** Replace document with new svg source (clears edits + history-owned state). */
+  load(svg: string): void;
+  on_change(fn: () => void): () => void;
+  /** See `_structure_version` for what this counter signals. */
+  get structure_version(): number;
+  /**
+   * Total mutation counter — advances on EVERY listener-visible mutation
+   * (attribute, style, text, topology, load/reset), unlike the selective
+   * `structure_version` / `geometry_version` channels. The single
+   * edit-version source: anything derived from this document — the
+   * editor's `content_version` / `dirty`, memoized reads, a rendered
+   * projection — answers "am I current?" by comparing values, with no
+   * event-ordering dependence. Advances BEFORE listeners fire, so a
+   * read issued from inside a change listener already sees the new
+   * value.
+   */
+  get revision(): number;
+  /** See `_geometry_version` for what this counter signals. */
+  get geometry_version(): number;
+  /**
+   * Advance `_geometry_version` by exactly 1 WITHOUT touching the tree,
+   * any attribute, `structure_version`, or the `on_change` listeners.
+   *
+   * The one geometry mutation with no attribute write: a `<text>` /
+   * `<tspan>` reflow the IR cannot see — a web font finishing load AFTER
+   * the `font-family` / `font-size` write was already serialized. The DOM
+   * surface observes the reflow (`document.fonts` `loadingdone`) and asks
+   * the geometry channel to advance so the bounds cache re-reads the
+   * settled glyph metrics. See ../../docs/geometry.md §Limitations.
+   *
+   * Deliberately does NOT call `emit()`: this is not a document edit, so
+   * `revision` must not advance — no dirty flag, no undo, no render
+   * flush. The editor's `_internal.bump_geometry` advances
+   * `geometry_version` here and fans out the geometry listeners itself.
+   */
+  bump_geometry(): void;
+  private emit;
+  /** Notify subscribers — for callers that mutate directly via setAttr/etc. */
+  notify(): void;
+  get(id: NodeId): AnyNode | null;
+  is_element(id: NodeId): boolean;
+  parent_of(id: NodeId): NodeId | null;
+  children_of(id: NodeId): readonly NodeId[];
+  /** Element children only — text/comment/cdata filtered out. */
+  element_children_of(id: NodeId): readonly NodeId[];
+  next_sibling_of(id: NodeId): NodeId | null;
+  next_element_sibling_of(id: NodeId): NodeId | null;
+  tag_of(id: NodeId): string;
+  contains(ancestor: NodeId, descendant: NodeId): boolean;
+  /**
+   * Filter a selection down to its **subtree roots** — drop any id whose
+   * ancestor is also in the input set.
+   *
+   * Mirrors `pruneNestedNodes` in the main canvas editor's query module
+   * ([editor/grida-canvas/query/index.ts:138](../../../../editor/grida-canvas/query/index.ts)) and shares its UX motivation:
+   * when a parent and a descendant are both selected, only the parent
+   * should drive multi-node mutations — otherwise the descendant
+   * accumulates the transform twice (once via the parent's `transform`,
+   * once via its own attribute write). Required for `commands.remove`
+   * (avoids re-attaching detached descendants on undo) and any multi-
+   * member translate path (avoids 2× drift for the Bar-chart marquee
+   * case).
+   *
+   * Order: preserves the input order for retained ids. Duplicates in
+   * the input are not deduplicated — callers are responsible (the
+   * editor's `commands.select` already dedupes).
+   *
+   * Performance: `O(n × depth)`. Builds a `Set` over the input once,
+   * then walks each id's ancestor chain at most once. The main editor's
+   * version is `O(n² × depth)` (per-pair `isAncestor`) — fine at typical
+   * selection sizes (a few dozen), worth winning here for free since
+   * `parent_of` is `O(1)` on our parent-map.
+   */
+  prune_nested_nodes(ids: ReadonlyArray<NodeId>): NodeId[];
+  all_nodes(): readonly NodeId[];
+  all_elements(): readonly NodeId[];
+  find_by_tag(ancestor: NodeId, tag: string): readonly NodeId[];
+  /** Read attribute by local name, optionally namespace-filtered. */
+  get_attr(id: NodeId, name: string, ns?: string | null): string | null;
+  /**
+   * Set / remove an attribute. If the attribute exists, it is mutated in place
+   * (preserving source position). If it doesn't, it's appended.
+   */
+  set_attr(id: NodeId, name: string, value: string | null, ns?: string | null): void;
+  attributes_of(id: NodeId): {
+    name: string;
+    ns: string | null;
+    value: string;
+  }[];
+  get_style(id: NodeId, property: string): string | null;
+  set_style(id: NodeId, property: string, value: string | null): void;
+  get_all_styles(id: NodeId): Array<{
+    property: string;
+    value: string;
+  }>;
+  /**
+   * Whether `id` can be opened in the flat-string text editor.
+   *
+   * v1 contract: the editor only operates on a *single flat text run*. That
+   * means the target must be a `<text>` or `<tspan>` whose direct children
+   * are all text nodes (or it has no children). A `<text>` containing a
+   * `<tspan>` is *not* honestly editable — `text_of` would drop the tspan
+   * content from the editor's view, and a flat-text write would leave the
+   * tspan dangling. Tspan-as-target is fine and well-defined when it's a
+   * leaf; only the host decides whether to route double-click to a tspan
+   * or its parent text.
+   */
+  is_text_edit_target(id: NodeId): boolean;
+  /**
+   * Returns a tag-discriminated snapshot of the authored geometry attrs
+   * if this node is eligible for vector (vertex) editing — else `null`.
+   *
+   * Eligibility:
+   *   - `<path>`     — requires non-empty `d`.
+   *   - `<line>`     — requires two distinct finite user-unit endpoints.
+   *   - `<polyline>` — requires `points` parseable to ≥ 2 vertices.
+   *   - `<polygon>`  — same as polyline.
+   *   - `<rect>`     — requires finite user-unit `width`/`height` > 0.
+   *   - `<circle>`   — requires finite user-unit `r` > 0.
+   *   - `<ellipse>`  — requires finite user-unit `rx`/`ry` > 0.
+   *
+   * The vertex tags (`line` / `polyline` / `polygon`) write edits back to
+   * their native attributes while the geometry stays expressible there; an
+   * edit that escapes the native form (a curve, or a topology change that
+   * leaves the canonical chain) re-types the element to `<path>`. The
+   * geometry primitives (`rect` / `circle` / `ellipse`) have no native
+   * vector form, so any vector edit re-types them. In all cases the native
+   * tag is preserved byte-for-byte until the first re-typing edit commits
+   * (see `retype_to_path`). Design:
+   * `docs/wg/feat-svg-editor/promote-to-path.md`.
+   *
+   * Geometry that is not a plain user-unit number (`%`, `px`, `em`, …) is
+   * an out-of-scope gap, so such an element returns `null` rather than
+   * advertising an edit the editor cannot perform faithfully.
+   *
+   * Rejects `<image>` / `<use>` (raster / reference bounding boxes, no
+   * editable outline).
+   */
+  /**
+   * Parse an optional SVG geometry coordinate (`x`/`y`, `cx`/`cy`, the line
+   * endpoints). An **absent** attribute takes the SVG default (`0`); a
+   * **present** attribute that is not a plain user-unit number (`%`, `px`,
+   * `em`, …) is out of scope and yields `null` so the caller refuses the
+   * element — the same gate required attrs (width / radius) already apply.
+   *
+   * The absent-vs-present distinction is the point: a bare `?? 0` would
+   * silently coerce an authored `x1="5px"` to `0`, then the first native
+   * writeback would overwrite that authored value. Refusing keeps the
+   * editor from misrepresenting geometry it cannot read faithfully.
+   */
+  private optional_user_unit_coord;
+  is_vector_edit_target(id: NodeId): VectorEditSource | null;
+  /**
+   * Re-type a native vector element (`<line>` / `<polyline>` / `<polygon>` /
+   * `<rect>` / `<circle>` / `<ellipse>`) into a `<path>` in place, consuming
+   * its native geometry attributes and setting `d`. A structural mutation:
+   * this layer executes the re-type; it does not decide when one is
+   * warranted.
+   *
+   * Idempotent: returns `null` if `id` is not currently one of those tags
+   * (so it is safe to call repeatedly — once re-typed, e.g. already a
+   * `<path>`, further calls are no-ops). Otherwise mutates the node and
+   * returns an opaque {@link RetypeRecord} reversal token.
+   *
+   * Identity, children, `self_closing`, non-geometry attributes, and all
+   * source trivia are preserved unchanged — only the tag and the geometry
+   * attributes move. Pass the token to {@link revert_retype} to restore
+   * the original primitive byte-for-byte.
+   *
+   * (see test/svg-editor-vector-promote-to-path.md)
+   */
+  retype_to_path(id: NodeId, d: string): RetypeRecord | null;
+  /**
+   * Reverse a {@link retype_to_path}: restore the original tag, remove the
+   * `d` attribute the promotion added, and splice the captured geometry
+   * attribute tokens back at their original positions (preserving their
+   * trivia, so a later `serialize()` is byte-equal to the pre-promotion
+   * source).
+   */
+  revert_retype(id: NodeId, token: RetypeRecord): void;
+  /**
+   * True iff this `<text>` / `<tspan>` carries a non-empty `rotate=""`
+   * per-glyph attribute (which conflicts with element-level rotation).
+   */
+  has_glyph_rotate(id: NodeId): boolean;
+  /**
+   * True iff this element's inline `style=""` declares a `transform:`
+   * CSS property (which would shadow the editor's `transform=` writes).
+   */
+  has_inline_css_transform(id: NodeId): boolean;
+  /**
+   * True iff this element has a direct `<animateTransform>` child
+   * (which produces a time-varying transform invisible to attribute writes).
+   * Only direct children are checked — nested cases attach to the nearer ancestor.
+   */
+  has_animate_transform_child(id: NodeId): boolean;
+  text_of(id: NodeId): string;
+  /** Replace all direct text children with a single text node carrying `value`. */
+  set_text(id: NodeId, value: string): void;
+  insert(id: NodeId, parent: NodeId, before: NodeId | null): void;
+  remove(id: NodeId): void;
+  /** Create a new element node and register it (not yet inserted). */
+  create_element(local: string, opts?: {
+    prefix?: string | null;
+    ns?: string | null;
+  }): NodeId;
+  /** Fresh internal NodeId, guaranteed unique within this document's node
+   *  map. Shared by `create_element` and fragment adoption — collisions
+   *  matter for the latter because the parser assigns sequential per-parse
+   *  ids that a second parse would repeat. */
+  private fresh_node_id;
+  /**
+   * Parse an SVG **fragment** string and adopt its element subtrees into
+   * this document's node store — registered like {@link create_element}
+   * but NOT inserted into the tree (no version bump, no emit). Callers
+   * attach the returned roots via {@link insert}; the editor's
+   * `commands.insert_fragment` is the history-bracketed consumer.
+   *
+   * Input shapes:
+   *   - A **bare fragment** — one or more sibling elements
+   *     (`<path …/><path …/>`, or a single `<g>…</g>`). The top-level
+   *     elements become the returned roots, in source order.
+   *   - A **full SVG document** — when the input's only top-level element
+   *     is an `<svg>`, that element is treated as a document SHELL, not
+   *     content: its element children become the roots and the shell
+   *     itself (viewBox, width/height, prolog, doctype) is discarded. Its
+   *     `xmlns:*` prefix declarations are harvested into `xmlns` so the
+   *     caller can re-declare prefixes the adopted content still uses.
+   *     An `<svg>` that appears as one of SEVERAL top-level elements (or
+   *     anywhere below the top level) is content, adopted as-is.
+   *
+   * Top-level non-element nodes (whitespace between roots, comments, PIs,
+   * doctype) are dropped — adoption takes elements, and the host
+   * document's own trivia stays untouched. WITHIN each adopted subtree
+   * every byte of source trivia survives verbatim (attribute order, quote
+   * styles, whitespace, comments), so the inserted markup serializes back
+   * exactly as authored — same rules as the initial parse.
+   *
+   * Authored `id=""` attributes are adopted verbatim — never rewritten,
+   * even when they collide with ids already in the document. Silent id
+   * renaming is exactly the proprietary noise this editor refuses (README
+   * "What clean means" §3); deduplication belongs to the explicit Tidy
+   * command. Internal NodeIds ARE freshly assigned (see
+   * {@link fresh_node_id}) so adopted nodes never collide in the id map.
+   *
+   * Throws `TypeError` on a non-string input and `Error` on markup the
+   * parser rejects (unclosed / mismatched tags, malformed attributes). An
+   * input with no top-level elements (empty string, whitespace, comments
+   * only) returns `{ roots: [], xmlns: [] }`.
+   */
+  create_fragment(markup: string): {
+    roots: NodeId[];
+    xmlns: ReadonlyArray<{
+      prefix: string;
+      uri: string;
+    }>;
+  };
+  /**
+   * Register `node` and its whole subtree (from a foreign parse) into this
+   * document's node map under fresh NodeIds. The parser assigns sequential
+   * per-parse ids (`n0`, `n1`, …), so adopting without a remap would
+   * collide with this document's own nodes. Children links are rewritten;
+   * the subtree root arrives detached (`parent: null`), like
+   * `create_element`. Mutates the parsed nodes in place — a parse result
+   * is single-use.
+   */
+  private adopt_parsed_subtree;
+  /**
+   * Namespace prefixes USED within `id`'s subtree (element tags and
+   * attribute names) that are not DECLARED within the subtree itself —
+   * i.e. prefixes the subtree borrows from ancestor scope. `xml` and
+   * `xmlns` are excluded (bound by the XML spec, never declared).
+   * Declaration scoping is honored per use-site: a prefix declared on the
+   * using element or any of its ancestors up to (and including) the
+   * subtree root counts as declared.
+   *
+   * Structural fact only — the caller decides what an unbound prefix
+   * means (e.g. `commands.insert_fragment` hoists a resolvable
+   * declaration onto the document root).
+   */
+  undeclared_ns_prefixes(id: NodeId): ReadonlySet<string>;
+  /**
+   * Declare a namespace prefix on the ROOT element: appends
+   * `xmlns:<prefix>="<uri>"` when the root doesn't already declare that
+   * prefix. An authored declaration always wins — this never rebinds.
+   * Policy wrapper over {@link set_attr} in the `XMLNS_NS` space; removal
+   * works through `set_attr(root, prefix, null, XMLNS_NS)` as usual.
+   */
+  declare_xmlns(prefix: string, uri: string): void;
+  serialize(): string;
+  /**
+   * Serialize a single element's subtree as an SVG **fragment**, using the
+   * same trivia-preserving rules as {@link serialize} (attribute order,
+   * quote style, whitespace, comments — emitted exactly as authored).
+   *
+   * This is NOT {@link serialize} scoped to a node — it is a deliberately
+   * weaker output (sdk-design D3, asymmetric outputs stay separate):
+   *
+   *   - `serialize()` emits the whole document and carries the P1
+   *     whole-document 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 — 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, a non-element node, or a node detached from
+   * the live tree: the contract is "the markup for a selected element,"
+   * selections are always live elements, and a string return of `""` for a
+   * bad id would hide consumer bugs. The detached case matters because
+   * `remove()` keeps the node in the id map for undo — a stale id from a
+   * removed node would otherwise serialize content no longer in the
+   * document, silently feeding a consumer deleted markup.
+   */
+  serialize_node(id: NodeId): string;
+  private emit_node;
+  private emit_attr;
+}
+//#endregion
+//#region src/core/vector-edit/model.d.ts
+type Verb = "M" | "L" | "H" | "V" | "C" | "S" | "Q" | "T" | "A" | "Z";
+type VertexId = number;
+type SegmentId = number;
+/** `[vertex_idx, 0]` = ta on segment whose `a === vertex_idx`; `[vertex_idx, 1]` = tb where `b === vertex_idx`. */
+type TangentRef = readonly [VertexId, 0 | 1];
+/**
+ * Tangent mirroring policy applied around a vertex when one tangent moves.
+ * Mirrors `vn.TangentMirroringMode`.
+ *
+ * - `auto` — infer from current state (smooth join → mirror angle+length;
+ *   broken / asymmetric → don't mirror).
+ * - `none` — only move the chosen tangent. Other tangents at this vertex
+ *   stay put.
+ * - `angle` — keep opposite tangent collinear (mirror angle), preserve its
+ *   length. Used when the user wants a sharp-vs-smooth-but-asymmetric
+ *   handle (Figma's "Mirror angle" mode).
+ * - `all` — mirror both angle and length. Standard "smooth" handle pair.
+ */
+type TangentMirrorMode = "auto" | "none" | "angle" | "all";
+type SegmentView = {
+  a: VertexId;
+  b: VertexId;
+  ta: readonly [number, number];
+  tb: readonly [number, number];
+  source_verb?: Verb;
+};
+type PathSnapshot = {
+  vertices: ReadonlyArray<readonly [number, number]>;
+  segments: ReadonlyArray<SegmentView>;
+};
+type SubSelection = {
+  vertices: ReadonlyArray<VertexId>;
+  segments: ReadonlyArray<SegmentId>;
+  tangents: ReadonlyArray<TangentRef>;
+};
+/**
+ * Per-segment metadata maintained alongside vn's segment array.
+ * `meta[i]` corresponds to `network.segments[i]`.
+ */
+type SegmentMeta = {
+  /** The SVG verb that originally produced this segment, if known. */source_verb?: Verb; /** Arc-specific metadata for segments born from an `A` command. */
+  arc?: ArcMeta; /** True iff this segment was emitted by a `Z` command (closing the subpath). */
+  is_close_segment?: boolean;
+};
+/**
+ * When an `A` command is parsed, it decomposes to N cubic segments.
+ * All segments in the same arc share the same `group_id` and the same
+ * arc parameters, plus each carries a snapshot of its original tangents
+ * (used at emit time to detect "still an arc" vs "user has edited").
+ */
+type ArcMeta = {
+  group_id: number;
+  rx: number;
+  ry: number;
+  x_rot: number;
+  large_arc_flag: 0 | 1;
+  sweep_flag: 0 | 1; /** Snapshot of this segment's ta at parse time (relative). */
+  baseline_ta: cmath.Vector2; /** Snapshot of this segment's tb at parse time (relative). */
+  baseline_tb: cmath.Vector2; /** Snapshot of this segment's end-vertex absolute position at parse time. */
+  baseline_b_abs: cmath.Vector2; /** Sequence index within the arc group (0..N-1). */
+  seq: number; /** Total segments in the arc group. */
+  count: number;
+  /** Original SVG arc command's `(x, y)` endpoint. Only populated on the
+   *  LAST segment of the arc group (seq === count - 1). Used by the emitter
+   *  to write back the exact coordinate the author wrote, avoiding floating-
+   *  point drift from arc-to-cubic decomposition. */
+  original_end?: cmath.Vector2;
+};
+/**
+ * Canonical vector-network model for a single SVG path's `d` string.
+ *
+ * `PathModel` is a self-contained geometry primitive — it parses an SVG
+ * path `d` into a vertex/segment graph (with verb hints preserved for
+ * round-trip honesty), exposes POJO observers, and serializes back to
+ * `d`. It does not hold or reference an `SvgDocument`, an editor
+ * instance, the DOM, or any host. It is safe to construct in any
+ * environment that can run the package.
+ *
+ * Public re-exported as a top-level Layer-A primitive from
+ * `@grida/svg-editor` for callers that want canonical path geometry
+ * without mounting an editor. The full mutation surface (translate /
+ * bend / set-tangent / split, etc.) is package-internal and may shift;
+ * the publicly-stable contract for external callers is the construction
+ * + serialization + observation methods documented at the entry point.
+ *
+ * @experimental Surface shape is v0; signatures may change before the
+ * package reaches semver stability.
+ */
+declare class PathModel {
+  private readonly _network;
+  private readonly _meta;
+  private constructor();
+  static fromSvgPathD(d: string): PathModel;
+  /** Construct from a vn network with no verb info (every segment defaults to undefined verb). */
+  static fromVectorNetwork(network: vn.VectorNetwork): PathModel;
+  toSvgPathD(): string;
+  snapshot(): PathSnapshot;
+  bbox(): cmath.Rectangle;
+  vertexCount(): number;
+  segmentCount(): number;
+  /**
+   * If the model's current geometry is still expressible in the source
+   * SVG tag's native attribute form, return the equivalent
+   * `VectorEditSource` (which is also the writeable shape) — else `null`.
+   *
+   * This is the decider that gates per-gesture native-attrs writeback in
+   * `VectorEditSession.apply_d`. `null` means "the user's edit cannot be
+   * faithfully written back to the source tag" — in v1 with no
+   * promotion, the gesture is refused; in v1.1+ with promotion, the
+   * element is rewritten to `<path d="…">`.
+   *
+   * v1 expressibility (all source kinds require every segment's `ta` and
+   * `tb` to be exactly zero — any tangent edit forces promotion):
+   *
+   * - **path** — always `null` (no native fallback; the canonical form
+   *   IS `<path d>`, so callers should just write `d` directly).
+   * - **line** — exactly two vertices joined by one straight segment
+   *   `0→1`. (Topology after a 2-point `vn.fromPolyline` and any sequence
+   *   of endpoint translates.)
+   * - **polyline** — segments form the canonical open chain
+   *   `0→1, 1→2, …, (n-2)→(n-1)`. (Topology after `vn.fromPolyline` and
+   *   any sequence of vertex translates.)
+   * - **polygon** — segments form the canonical closed chain
+   *   `0→1, 1→2, …, (n-1)→0`. (Topology after `vn.fromPolygon` and any
+   *   sequence of vertex translates.)
+   * - **rect / circle / ellipse** — always `null`. These geometry
+   *   primitives have no native writeback target; any vector gesture on
+   *   them re-types the element to `<path>` (see `vector_apply` /
+   *   `SvgDocument.retype_to_path`), so they never round-trip through here.
+   *
+   * Anything that changes segment topology (insert-vertex, delete-vertex,
+   * close/open shape) or introduces a curve leaves the canonical chain and
+   * returns `null` here; the caller re-types the element to `<path>`.
+   */
+  toNativeAttrs(source_tag: VectorEditSource["kind"]): Extract<VectorEditSource, {
+    kind: "line" | "polyline" | "polygon";
+  }> | null;
+  /** Translate one vertex by `delta`. Connected segments follow because
+   *  tangents are stored relative to vertices. Verb metadata is preserved
+   *  as-is; emit-time honesty handles cases where the shape no longer
+   *  matches the recorded verb (e.g. an H whose endpoint y-coord drifts). */
+  translateVertex(v: VertexId, delta: readonly [number, number]): PathModel;
+  /** Bulk-translate a set of vertices by the same delta. Atomic — either
+   *  every move succeeds or none (input is validated up-front). */
+  translateVertices(indices: ReadonlyArray<VertexId>, delta: readonly [number, number]): PathModel;
+  /** Translate one segment by `delta` — moves both endpoints, dragging
+   *  their tangents along (tangents are stored relative to vertices, so
+   *  this is automatic). Other segments connected to the moved endpoints
+   *  also follow at the shared vertex. */
+  translateSegment(seg: SegmentId, delta: readonly [number, number]): PathModel;
+  /**
+   * Bend a curve segment by dragging a point at parameter `ca` to `cb`
+   * (cb is in absolute doc-space). Delegates to vn's `bendSegment` —
+   * which solves for the new ta/tb that put `B(ca) === cb`, holding the
+   * endpoints fixed.
+   *
+   * The "frozen" snapshot of the segment at gesture start is the caller's
+   * responsibility. Convention: call this from a preview session where
+   * each frame replays from the baseline (same pattern as translate).
+   */
+  bendSegment(seg: SegmentId, ca: number, cb: readonly [number, number], frozen: {
+    a: readonly [number, number];
+    b: readonly [number, number];
+    ta: readonly [number, number];
+    tb: readonly [number, number];
+  }): PathModel;
+  /**
+   * Move one tangent control point to a new absolute position. Mirror
+   * policy follows vn's `updateTangent`. The other tangent at the same
+   * vertex is updated according to the policy.
+   *
+   * Returns a new PathModel; verb metadata is preserved verbatim.
+   * `toSvgPathD` will demote (e.g. L → C) if the new tangents make the
+   * recorded verb no longer match the geometry.
+   */
+  setTangent(t: TangentRef, abs_pos: readonly [number, number], mirror?: TangentMirrorMode): PathModel;
+  /**
+   * Split segment `seg` at parametric position `t ∈ [0,1]`, inserting a
+   * new vertex. Returns the new model and the **canonical (path-order)**
+   * index of the inserted vertex.
+   *
+   * Verb metadata for the split: the original segment's verb propagates
+   * to BOTH halves if it was a curve type (`C`/`S`/`Q`/`T`/`A`); for
+   * straight verbs (`L`/`H`/`V`), the split halves stay straight (their
+   * tangents are zero from vn's `preserveZero` path when both originals
+   * were zero). Arc-group identity is dropped from the halves — the
+   * arc is broken once split (the emitter will fall back to `C`/`L`).
+   *
+   * **Index space contract.** `VectorNetworkEditor.splitSegment` APPENDS
+   * the new vertex at the end of the network's vertices array — its
+   * index is the in-memory insertion order. But `toSvgPathD` / `fromSvgPathD`
+   * canonicalize vertices in path order, so the same vertex gets a
+   * DIFFERENT index in the d-derived model that consumers re-parse each
+   * frame (e.g., the host's `handle_translate_vertices`). Returning the
+   * insertion-order index causes the classic split-and-drag bug: the
+   * surface holds index N (insertion-order) but the live model has
+   * index M (path-order) at that position — drag moves the wrong vertex
+   * and the user sees "split happened but the new vertex doesn't move".
+   *
+   * To prevent that, we round-trip the post-split model through
+   * `toSvgPathD` → `fromSvgPathD` and return the canonical (path-order)
+   * index of the new vertex. The returned `model` is the canonical
+   * one, so any subsequent op on it uses the same index space the d
+   * roundtrip exposes. See `__tests__/README.md` §"index identity
+   * across the `d` round-trip" for the test pattern that pins this.
+   */
+  splitSegment(seg: SegmentId, t: number): {
+    model: PathModel;
+    new_vertex: VertexId;
+  };
+  /**
+   * Doc-space position of a tangent control point. `t` references a
+   * segment and which end (`a` or `b`) the tangent belongs to; the
+   * result is `vertex + tangent_value + origin`. Returns null if no
+   * segment has this tangent (e.g. the vertex is isolated).
+   */
+  tangentAbsolute(t: TangentRef, origin: readonly [number, number]): [number, number] | null;
+  /**
+   * Vertices "neighbouring" the current selection — these are the
+   * vertices whose tangent handles should render in chrome.
+   *
+   * Two-phase, mirrors `editor/grida-canvas/reducers/methods/vector.ts`
+   * `getUXNeighbouringVertices`:
+   *
+   *   1. Collect "active" vertices:
+   *      - every selected vertex
+   *      - every tangent-owning vertex
+   *      - both endpoints of every selected segment
+   *   2. Expand uniformly to 1-hop neighbours (vertices sharing a segment
+   *      with any active vertex).
+   *
+   * Without phase 2 for tangent / segment selections, selecting only a
+   * tangent would hide neighbouring-vertex tangents — the user loses
+   * spatial context. Phase 2 makes the affordance symmetric: whatever
+   * triggered selection, the 1-hop ring of tangent handles is visible.
+   *
+   * Sorted ascending; deduped.
+   */
+  neighbouringVertices(sel: SubSelection): VertexId[];
+  /**
+   * True iff segment `seg`'s curve is entirely contained in the rect.
+   * Delegates to `cmath.bezier.containedByRect`.
+   */
+  segmentContainedByRect(seg: SegmentId, rect: cmath.Rectangle, origin?: readonly [number, number]): boolean;
+  /** @internal */
+  _rawNetwork(): vn.VectorNetwork;
+  /** @internal */
+  _rawMeta(): ReadonlyArray<SegmentMeta>;
+  /**
+   * Map a `TangentRef` to a concrete `(segment_index, control)` pair.
+   *
+   * `[v, 0]` → first segment whose `a === v` (its `ta`).
+   * `[v, 1]` → first segment whose `b === v` (its `tb`).
+   *
+   * Y-junctions (multi-outgoing or multi-incoming) are uncommon for SVG
+   * `<path>` content; v1 picks the first match. If we ever support those
+   * cleanly, extend `TangentRef` to carry the segment id explicitly.
+   */
+  private _locateTangent;
+}
+//#endregion
+//#region src/core/defs.d.ts
+interface GradientsApi {
+  list(): ReadonlyArray<GradientEntry>;
+  get(id: string): GradientEntry | null;
+  upsert(definition: GradientDefinition, opts?: {
+    id?: string;
+  }): string;
+  remove(id: string): void;
+  subscribe(fn: (entries: ReadonlyArray<GradientEntry>) => void): Unsubscribe;
+}
+type Defs = {
+  gradients: GradientsApi;
+};
+//#endregion
+//#region src/commands/registry.d.ts
+/**
+ * Command registry.
+ *
+ * A passive id-keyed registry of handlers. Built so that:
+ *
+ *  - keybindings (in `src/keymap`) can address commands by stable id;
+ *  - new commands can be added in ONE place (`src/commands/defaults.ts`)
+ *    without growing the public surface of the editor;
+ *  - "one key, many meanings" can be expressed via chain semantics: a
+ *    handler returns `true` if it consumed, `false`/`void` otherwise,
+ *    and the dispatcher tries the next candidate in the chain.
+ *
+ * Handlers are plain closures — they capture whatever editor reference
+ * they need. The registry itself stays unaware of the editor's type,
+ * which avoids a circular type dependency between editor and registry.
+ */
+/** Stable, dotted id for a command, e.g. `"history.undo"`. */
+type CommandId = string;
+/**
+ * A command handler.
+ *
+ * Return `true` if the handler consumed the invocation. Return `false`
+ * or `undefined` to signal "did not apply" — the dispatcher will try
+ * the next candidate registered for the same key.
+ *
+ * Handlers are closures: they capture their editor reference. No
+ * editor parameter is passed — keep handlers self-contained.
+ */
+type CommandHandler = (args?: unknown) => boolean | void;
+declare class CommandRegistry {
+  private readonly map;
+  /**
+   * Register a command. Returns an unregister function. Re-registering
+   * the same id replaces the previous handler (last writer wins).
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a command by id. Returns `true` if the handler consumed,
+   * `false` otherwise (including unknown ids and handlers that returned
+   * `false`/`undefined`).
+   */
+  invoke(id: CommandId, args?: unknown): boolean;
+  has(id: CommandId): boolean;
+  /** All registered ids, for debugging / introspection. */
+  ids(): readonly CommandId[];
+}
+//#endregion
+//#region src/keymap/keymap.d.ts
+type KeymapBinding = {
+  /** Declarative key combination. Build with `kb()` / `c()` / `seq()`. */keybinding: Keybinding; /** Command id to invoke on match. */
+  command: CommandId; /** Forwarded as the `args` parameter to the command handler. */
+  args?: unknown; /** Higher priorities run first in the chain. Default 0. */
+  priority?: number;
+  /**
+   * Bypass the form-element focus guard. When `true`, this binding fires
+   * even if a text input is focused (`<input>`, `<textarea>`, or any
+   * `contentEditable` element).
+   *
+   * Default `false`. The platform's native text-editing shortcuts —
+   * Cmd+A (select all), Cmd+Z/Y (input undo/redo), Cmd+C/V/X
+   * (clipboard), arrow keys, Backspace, Tab, Enter — must win over
+   * editor shortcuts while the user is typing.
+   *
+   * Opt in sparingly. Reasonable candidates: truly global app shortcuts
+   * like Cmd+S (save). Unreasonable candidates: anything that has a
+   * native text-editing meaning.
+   */
+  allowInFormElement?: boolean;
+  /**
+   * Reserved for V2; not honored by the V1 dispatcher. When added, this
+   * will be evaluated before the handler runs; if false, the binding is
+   * skipped without invoking the handler.
+   */
+  when?: (ctx: unknown) => boolean;
+};
+declare class Keymap {
+  private readonly commands;
+  private readonly platformGetter;
+  /**
+   * Bindings bucketed by canonical chunk-key hash, computed per
+   * `@grida/keybinding`'s `chunkKey`. Each list is the chain for that
+   * key, sorted in dispatch order (priority desc, then registration
+   * order).
+   */
+  private readonly buckets;
+  /** Insert order, so ties on priority are deterministic. */
+  private seq;
+  constructor(commands: CommandRegistry, platformGetter?: () => Platform);
+  /**
+   * Bind a key combination to a command. Returns an unbind function.
+   * The same `Keybinding` can be bound to multiple commands — they will
+   * all be tried in chain order on dispatch.
+   */
+  bind(binding: KeymapBinding): () => void;
+  /**
+   * Remove bindings matching the spec. If both filters are passed, only
+   * bindings that match BOTH are removed.
+   */
+  unbind(spec: {
+    keybinding?: Keybinding;
+    command?: CommandId;
+  }): void;
+  /** All registered bindings, for introspection. Order is not guaranteed. */
+  bindings(): readonly KeymapBinding[];
+  /**
+   * Does the keymap have a binding that matches this event's chord —
+   * regardless of whether any handler would consume it? Hosts use this
+   * to decide whether to swallow the platform's default action (e.g.
+   * `event.preventDefault()` in the browser), so that an advertised
+   * shortcut like `Cmd+G` doesn't fall through to the browser's find
+   * bar even when the binding's handler rejects.
+   *
+   * Pure read; runs no handlers, no side effects. Honors the same
+   * form-element focus guard `dispatch` uses, so a typing user's
+   * keystroke isn't "claimed" — and the browser's native text-editing
+   * default (Cmd+A select all, Cmd+Z undo, etc.) wins.
+   */
+  claims(event: KeyboardEvent): boolean;
+  /**
+   * Match the event against bound chunks, then run candidates in chain
+   * order. Returns `true` on the first handler that consumes; returns
+   * `false` if nothing matched or all matches fell through.
+   *
+   * **Form-element focus guard.** When a text input is focused
+   * (`<input>`, `<textarea>`, contentEditable), bindings are suppressed
+   * by default so the platform's native shortcuts (Cmd+A, Cmd+Z, Cmd+C,
+   * arrow nav, …) are preserved. A binding can opt out of this guard
+   * with `allowInFormElement: true` — see `KeymapBinding`.
+   *
+   * `dispatch` is browser-agnostic: it does NOT call `preventDefault()`
+   * or touch the event in any way. The host decides what to do with the
+   * platform default — typically `if (keymap.claims(e)) e.preventDefault()`,
+   * which prevents the platform default for advertised shortcuts even
+   * when the chain rejects. See README → `editor.keymap`.
+   */
+  dispatch(event: KeyboardEvent): boolean;
+  /**
+   * Compute the set of canonical hashes a `Keybinding` lights up. A
+   * binding with aliases (multiple sequences) contributes one hash per
+   * single-chunk alias; multi-chunk sequences (chords) are skipped in
+   * V1.
+   */
+  private chunkKeysFor;
+}
+//#endregion
+//#region src/core/subtree.d.ts
+declare namespace subtree {
+  /**
+   * Document-order comparator over node ids. Builds the index once per
+   * call (one full tree walk) — create one comparator per operation and
+   * reuse it, as `clipboard.extract_payload` does.
+   */
+  function by_document_order(doc: SvgDocument): (a: NodeId, b: NodeId) => number;
+  /**
+   * Selection normalization — the half of extraction that payload
+   * extraction (copy) and subtree clone share, per the FRD:
+   * dedupe → live elements only → ancestor subtrees subsume selected
+   * descendants (`prune_nested_nodes`) → DOCUMENT order regardless of
+   * selection order (sibling order is paint order, and paint order is
+   * meaning). Stale / non-element / detached ids are skipped, never
+   * thrown — normalization is a filter, not a validator.
+   */
+  function normalize_roots(doc: SvgDocument, selection: ReadonlyArray<NodeId>, order?: (a: NodeId, b: NodeId) => number): NodeId[];
+  /** One origin → clone pairing with the clone's placement, captured at
+   *  plan time. `before` is the origin's next sibling NODE (element or
+   *  trivia) so the clone lands immediately after its origin. */
+  type SubtreeClonePlanEntry = {
+    origin: NodeId;
+    /** Registered in the document's node map, DETACHED (`create_fragment`
+     *  style) — the consumer inserts it inside its own history closure. */
+    clone: NodeId; /** `parent_of(origin)` at plan time. */
+    parent: NodeId; /** `next_sibling_of(origin)` at plan time; `null` = append. */
+    before: NodeId | null;
+  };
+  type SubtreeClonePlan = ReadonlyArray<SubtreeClonePlanEntry>;
+  /**
+   * Build a clone plan for the selection: for each normalized origin,
+   * serialize its subtree verbatim and re-adopt it under fresh runtime
+   * NodeIds via `create_fragment` — the markup round-trip rides the same
+   * trivia-preserving emit and never-rewrite-ids adoption the package
+   * already guarantees, so `serialize_node(clone) === serialize_node(origin)`
+   * byte-for-byte once inserted.
+   *
+   * Clones are returned DETACHED (plan, don't insert): consumers own
+   * insertion inside their history closures so redo can re-insert the
+   * same NodeIds (`remove` keeps nodes in the id map).
+   *
+   * Skipped origins (refusals, normalized away — not errors):
+   *   - the document root and any other parentless node (no sibling slot);
+   *   - nested `<svg>` elements — `create_fragment` deliberately treats a
+   *     lone `<svg>` root as a full-document shell and discards it (the
+   *     FRD's paste rule), which would silently unwrap the clone; refusing
+   *     beats mishandling.
+   *
+   * An empty selection (or one that normalizes to nothing) yields an
+   * empty plan — the caller's no-op.
+   */
+  function clone_plan(doc: SvgDocument, selection: ReadonlyArray<NodeId>): SubtreeClonePlan;
+  /**
+   * Attach every plan clone at its captured anchor. Anchors predate the
+   * plan (captured before any insertion), so no entry anchors on another
+   * entry's clone — each insert is independent and the interleaved
+   * `A, A′, B, B′` order falls out of the per-origin anchors.
+   *
+   * Idempotent: `doc.insert` detaches-then-splices, so re-attaching an
+   * already-live clone repositions it to the same slot. History redo
+   * closures rely on this.
+   */
+  function insert_plan(doc: SvgDocument, plan: SubtreeClonePlan): void;
+  /**
+   * Detach every plan clone. Order-independent for the same reason
+   * {@link insert_plan} is: anchors are never plan clones. Removed nodes
+   * stay in the document's id map (standard removed-node policy), so a
+   * later {@link insert_plan} over the same plan restores them.
+   */
+  function remove_plan(doc: SvgDocument, plan: SubtreeClonePlan): void;
+  /**
+   * The last committed duplication — the memory the repeating-offset
+   * behavior reads (gridaco/grida#825; spec:
+   * [docs/wg/feat-svg-editor/subtree-clone.md](../../../../docs/wg/feat-svg-editor/subtree-clone.md)
+   * §Repeating offset). Armed by `commands.duplicate` and by a cloned
+   * translate commit (Alt-drag); consumed and re-armed by the next
+   * `duplicate()`. Editor-session state — never observable, never in
+   * history. Staleness is caught at use by {@link repeat_delta}, not by
+   * per-mutation bookkeeping.
+   *
+   * The arrays are INDEX-PAIRED: `clones[i]` is the clone of
+   * `origins[i]` (both producers derive them from the same
+   * {@link SubtreeClonePlan}). {@link repeat_delta}'s per-member
+   * rigidity check depends on that pairing.
+   */
+  type DuplicationRecord = {
+    origins: ReadonlyArray<NodeId>;
+    clones: ReadonlyArray<NodeId>;
+  };
+  /**
+   * The repeating-offset delta (gridaco/grida#825): given the previous
+   * duplication's record and the CURRENT duplicate's normalized origins,
+   * return the world-space offset the fresh clones should repeat, or
+   * `null` for "no repeat — duplicate in place".
+   *
+   * The repeat fires only when the record still witnesses
+   * "duplicate, then rigidly translate the copies":
+   *   - `targets` is exactly `record.clones`, in the same (document)
+   *     order — the user is duplicating the previous duplication's
+   *     copies and nothing else;
+   *   - `bounds_of` answers for EVERY member of both sets (a detached
+   *     member, a measureless tag, or a missing geometry provider all
+   *     refuse);
+   *   - EVERY clone is rigid against its own origin (the record's
+   *     arrays are index-paired): same size, displaced by the same
+   *     delta as the union, within {@link REPEAT_RIGID_EPSILON}. The
+   *     check is per member, not per envelope — a rearranged or
+   *     resized inner copy is no longer a translate even when the
+   *     envelope-defining copies keep the union bbox intact;
+   *   - the union top-left delta exceeds the same tolerance (a copy
+   *     that never moved — or drifted by float noise only — repeats
+   *     nothing; the in-place duplicate stays byte-equal instead of
+   *     inheriting noise-sized attribute writes).
+   *
+   * Pure and gesture-grade: reads only through `bounds_of`, never
+   * throws — every failed precondition degrades to `null` (the main
+   * editor's `active_duplication` assert-on-mismatch is deliberately
+   * NOT copied; ⌘D must never crash on a stale record).
+   */
+  function repeat_delta(record: DuplicationRecord | null, targets: ReadonlyArray<NodeId>, bounds_of: (id: NodeId) => Rect | null): Vec2 | null;
+}
+//#endregion
+//#region src/core/geometry.d.ts
+/**
+ * Read-only access to world-space node bounds and hit-tests.
+ *
+ * Implementations should be cheap to call: snap (the main consumer)
+ * will query dozens of nodes per pointermove. The driver wraps SVG
+ * `getBBox` + `getCTM`; the memoizer caches per-`NodeId` to survive
+ * the surface re-rendering the SVG tree every editor tick.
+ *
+ * **Freshness contract.** Every read MUST reflect the CURRENT document
+ * — including when issued synchronously from inside a doc-change
+ * listener (`subscribe_geometry` fires mid-mutation, before any
+ * render). An implementation backed by a lazily-synced projection
+ * (e.g. a rendered DOM tree) must flush that projection before
+ * reading; compare `SvgDocument.revision` against the projection's
+ * last-rendered revision. Returning the previous document's geometry
+ * is not a transient glitch: the `MemoizedGeometryProvider` wrapper
+ * caches whatever the driver returns, so one stale read poisons every
+ * later consumer until the next invalidation (align/resize then plan
+ * against one-mutation-old bounds and oscillate — see
+ * `__tests__/geometry-stale-read.browser.test.ts`).
+ */
+interface GeometryProvider {
+  /**
+   * World-space bounding rect for a single node, or `null` when the
+   * node has no rendered geometry (orphan, detached, unsupported tag).
+   */
+  bounds_of(id: NodeId): Rect | null;
+  /**
+   * Bulk read. Missing nodes are simply absent from the result map.
+   * Drivers should be free to batch / parallelize internally.
+   */
+  bounds_of_many(ids: ReadonlyArray<NodeId>): Map<NodeId, Rect>;
+  /**
+   * Ids of nodes whose world-space bounds intersect `rect`. Order is
+   * implementation-defined.
+   */
+  nodes_in_rect(rect: Rect): NodeId[];
+  /**
+   * Topmost node id at world-space point `p`, or `null` when no node
+   * is hit. "Topmost" is defined by the renderer's z-order.
+   */
+  node_at_point(p: Vec2): NodeId | null;
+  /**
+   * Re-express a **world-space** delta vector in the frame a node's
+   * position attributes are written in — its parent user-space. For a
+   * node under a scaled/rotated `<g>` ancestor, or inside a nested
+   * `<svg>` viewport that scales its user space, the local frame differs
+   * from world by that linear transform; a translate must be written in
+   * the local frame so the on-screen motion matches the world delta
+   * (otherwise it moves `scale ×` too far).
+   *
+   * Optional: only DOM-backed providers (with a real layout engine) can
+   * derive the frame. Providers that omit it imply the flat-doc identity
+   * (world ≡ local), and callers fall back to the raw delta.
+   */
+  world_delta_to_local?(id: NodeId, delta: Vec2): Vec2;
+}
+type GeometrySignals = {
+  /** Fires when tree shape changes (insert/remove/reorder). */subscribe_structure: (cb: () => void) => Unsubscribe; /** Fires when any bounds-affecting change occurs. */
+  subscribe_geometry: (cb: () => void) => Unsubscribe;
+};
+/**
+ * Caches `bounds_of` results keyed on `NodeId`; full-clears on either
+ * `structure_version` or `geometry_version` bump. See ../../docs/geometry.md for
+ * why the cache is load-bearing under the surface's per-tick re-render.
+ */
+declare class MemoizedGeometryProvider implements GeometryProvider {
+  private readonly driver;
+  private readonly unsubscribers;
+  private cache;
+  constructor(driver: GeometryProvider, signals: GeometrySignals);
+  bounds_of(id: NodeId): Rect | null;
+  bounds_of_many(ids: ReadonlyArray<NodeId>): Map<NodeId, Rect>;
+  /**
+   * Pass-through. These are less hot than `bounds_of` (called once per
+   * gesture frame at most) and their result is sensitive to current
+   * viewport state, so caching them would be a footgun.
+   */
+  nodes_in_rect(rect: Rect): NodeId[];
+  node_at_point(p: Vec2): NodeId | null;
+  /** Pass-through. Frame projection depends on live layout, not on the
+   *  bounds cache, so there is nothing to memoize. Falls back to the raw
+   *  delta when the driver can't resolve a frame. */
+  world_delta_to_local(id: NodeId, delta: Vec2): Vec2;
+  /** Unsubscribe from both signals. Call on surface detach. */
+  dispose(): void;
+}
+//#endregion
+//#region src/gestures/gestures.d.ts
+/** Stable identifier for a gesture binding. Used by `unbind({ id })`. */
+type GestureId = string;
+/**
+ * Context passed to every installer. Exposes the seams a gesture needs:
+ * the container element to listen on, the camera to mutate, and the
+ * editor for keymap dispatch / state reads.
+ *
+ * Surface authors construct this once at attach; bindings receive it on
+ * every `install(...)` call.
+ */
+type GestureContext = {
+  /** Container element listeners attach to. */container: HTMLElement; /** SVG element being framed by the camera. Useful for hit-testing. */
+  svg_root: () => SVGSVGElement | null; /** HUD canvas overlay; sits on top of the SVG. */
+  hud_canvas: HTMLCanvasElement; /** Camera the binding mutates. */
+  camera: Camera; /** Editor for keymap dispatch / state reads. */
+  editor: SvgEditor; /** Handle for advanced bindings (e.g. wanting `camera.fit("<selection>")`). */
+  handle: SurfaceHandle;
+  /**
+   * Predicate returning `true` iff the surface is currently "attended" —
+   * focus inside the container subtree OR pointer over the container.
+   * Gesture bindings whose keydown handlers call `preventDefault()` MUST
+   * consult this before claiming, so the surface doesn't steal page-level
+   * shortcuts when embedded in a larger document. See `util/attention.ts`.
+   */
+  is_attended: () => boolean;
+};
+type GestureBinding = {
+  /** Stable id used by `unbind` / `bindings()`. */id: GestureId;
+  /**
+   * Wire DOM listeners (or any side-effect) needed for this gesture.
+   * Returns the uninstaller — called on `unbind` or surface detach.
+   */
+  install(ctx: GestureContext): () => void;
+};
+/**
+ * Sibling to `Keymap`. Owns a list of installed gesture bindings; each
+ * binding's `install(ctx)` is called eagerly when bound and uninstalled
+ * on `unbind` or surface detach.
+ */
+declare class Gestures {
+  private readonly ctx;
+  private entries;
+  constructor(ctx: GestureContext);
+  /**
+   * Install a gesture binding. Returns an unbind function.
+   * Re-binding the same `id` does NOT replace — both will be active.
+   * Use `unbind({ id })` first if you want a clean swap.
+   */
+  bind(binding: GestureBinding): () => void;
+  /**
+   * Remove bindings matching the spec. With `{ id }`, all bindings with
+   * that id are uninstalled. With no spec, this is a no-op (use
+   * `dispose()` to nuke everything).
+   */
+  unbind(spec: {
+    id?: GestureId;
+  }): void;
+  /** All currently installed bindings. Order is registration order. */
+  bindings(): readonly GestureBinding[];
+  /** @internal Uninstall every binding. Surface calls on detach. */
+  _dispose(): void;
+}
+//#endregion
+//#region src/core/editor.d.ts
+/** Resolved paint from the DOM-attached cascade. `resolved_paint` mirrors the
+ *  shape of `PaintValue.computed` so consumers can treat it uniformly with
+ *  the headless cascade. */
+type DomComputedPaint = {
+  computed: string;
+  resolved_paint: Paint | InvalidComputedValue | null;
+};
+/** Contract the DOM surface implements to delegate cascade resolution to
+ *  `getComputedStyle()`. Registered via `editor._internal.set_computed_resolver`
+ *  on attach. */
+type DomComputedResolver = {
+  computed_property(id: NodeId, name: string): string | null;
+  computed_paint(id: NodeId, channel: "fill" | "stroke"): DomComputedPaint | null;
+};
+type CreateSvgEditorOptions = {
+  svg: string;
+  providers?: Providers;
+  style?: Partial<EditorStyle>;
+};
+/**
+ * Internal-only members the package's own surfaces reach for. NOT part of
+ * the published API — `_internal` is the surface↔editor bridge, `keymap`
+ * is the keymap dispatcher the DOM surface forwards keyboard events to.
+ * Lives on the runtime object for in-package callers; stripped from the
+ * public `SvgEditor` type so the published `.d.ts` doesn't advertise them.
+ */
+type SvgEditorInternalMembers = "_internal" | "keymap";
+/** Internal handle. Use only inside `@grida/svg-editor`. */
+type SvgEditorInternal = ReturnType<typeof _create_svg_editor_internal>;
+/**
+ * The published editor type. `Omit`s the in-package-only surfaces (see
+ * `SvgEditorInternalMembers`) so consumers don't see them in IntelliSense
+ * or the dist `.d.ts`. They still exist on the runtime object — casting
+ * to `SvgEditorInternal` reaches them, but the contract is clear: stay
+ * inside the package.
+ */
+type SvgEditor = Omit<SvgEditorInternal, SvgEditorInternalMembers>;
+/**
+ * Host-provided rendering and input boundary. v0 contract is pure
+ * lifecycle: the editor calls `dispose()` on `editor.detach()` /
+ * `editor.dispose()`; the surface owns its own teardown there (event
+ * listeners, DOM nodes, retained refs).
+ *
+ * **Why so narrow?** The cross-surface vocabulary — paint push, input
+ * routing, hit-testing — isn't pinned yet. The DOM surface re-serializes
+ * the document via `editor.subscribe`, attaches its own listeners, and
+ * owns its own pick. The editor reaches into the DOM surface through
+ * the in-package `_internal` channel (`SurfaceBridge` in
+ * `core/surface-bridge.ts`), not through the public `Surface` type. A
+ * cross-surface paint / input / hit-test contract is deferred until a
+ * second surface implementation arrives and pins each shape (P6 —
+ * public only after dogfooding).
+ */
+type Surface = {
+  dispose(): void;
+};
+type SurfaceHandle = {
+  detach(): void;
+};
+type Commands = {
+  select(target: NodeId | ReadonlyArray<NodeId>, opts?: {
+    mode?: SelectMode;
+  }): void;
+  deselect(): void;
+  /**
+   * Replace the selection with every element-child of the current scope
+   * (or `doc.root` when no scope is entered). Returns `false` when the
+   * scope has no element children — letting the keymap chain fall through
+   * unchanged.
+   */
+  select_all(): boolean;
+  /**
+   * Rotate the selection to the next or previous sibling within the
+   * current single-selection's parent. Wraps at both ends. With an empty
+   * or multi-selection, falls back to selecting the first / last child of
+   * the current scope (so Tab from "nothing selected" picks something).
+   * Returns `false` when no candidate exists (empty scope).
+   */
+  select_sibling(direction: "next" | "prev"): boolean;
+  enter_scope(group: NodeId): void;
+  exit_scope(): void;
+  set_mode(mode: Mode): void;
+  set_property(name: string, value: string | null): void;
+  preview_property(name: string): PreviewSession;
+  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;
+  };
+  translate(delta: {
+    dx: number;
+    dy: number;
+  }): void;
+  nudge(delta: {
+    dx: number;
+    dy: number;
+  }): void;
+  /**
+   * Map the selection's current union-bbox to `target` as a single atomic
+   * step. Maps width/height/x/y simultaneously — each member scales
+   * around the union NW anchor, then the result is translated so the
+   * union NW lands at `target.{x, y}`. Per-tag constraints (circle
+   * uniform, text edge no-op) execute inside `apply_resize` for each
+   * member.
+   *
+   * The default selection is `state.selection`. Pass `opts.ids` to
+   * override. Members that are not resizable are skipped silently: this
+   * means both an unresizable tag (e.g. `<g>`) AND a resizable tag carrying
+   * a non-trivial transform (rotate-without-pivot, matrix, scale, skew),
+   * which can't be resized in local space without breaking round-trip — the
+   * same `is_resizable_node` gate the resize HUD applies. The gesture is a
+   * no-op when no resizable member remains. Returns `true` when a history
+   * step was pushed. `opts.label` overrides the atomic history label
+   * (default `"resize-to"`).
+   */
+  resize_to(target: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    label?: string;
+  }): boolean;
+  /**
+   * Resize the selection by a delta — PER-ELEMENT: each selected member
+   * grows/shrinks around its OWN NW corner, so members keep their positions
+   * relative to one another (NOT a union/group resize — contrast
+   * {@link resize_to}, which scales the whole selection around the shared
+   * union origin and so translates off-origin members). `delta.dw` /
+   * `delta.dh` are applied additively to each member (clamped to >= 0). The
+   * core verb behind keyboard nudge-resize.
+   *
+   * ALL-OR-NOTHING gate: refuses (returns `false`, no history step) unless
+   * EVERY member passes `is_resizable_node` — the same tag + transform-class
+   * check the resize HUD uses, applied wholesale (a mixed selection is
+   * refused, not partially resized — matches a HUD handle-drag, which is
+   * rejected when any member is unsafe). Also refuses on empty selection or
+   * when no geometry provider (DOM surface) is attached.
+   *
+   * Per-tag constraints (circle uniform, text edge no-op) apply per member.
+   * The default selection is `state.selection`; pass `opts.ids` to override.
+   */
+  resize_by(delta: {
+    dw: number;
+    dh: number;
+  }, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  /**
+   * Rotate the selection by `angle` radians around the union-bbox center
+   * (or `opts.pivot` if provided). One atomic history step. Returns
+   * `false` and a no-op when any member's transform isn't rotatable (see
+   * `is_rotatable` — refuses non-trivial transforms, `<text rotate>`,
+   * CSS-property transforms, animated transforms).
+   *
+   * Pivot defaults to bbox-center of the live selection via the attached
+   * surface's `geometry_provider`. With no surface attached, the function
+   * uses local-attribute bbox approximations (less precise for transformed
+   * ancestors, but correct for flat docs).
+   */
+  rotate(angle: number, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    pivot?: {
+      x: number;
+      y: number;
+    };
+  }): boolean;
+  /**
+   * Set the absolute rotation of each member to `angle` radians. Computes
+   * the per-member delta from each baseline's current rotation. Pivot
+   * defaults to union-bbox center. Same refusal semantics as `rotate`.
+   * One atomic history step.
+   */
+  rotate_to(angle: number, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    pivot?: {
+      x: number;
+      y: number;
+    };
+  }): boolean;
+  /**
+   * Compose an arbitrary 2×3 affine onto the selection, **relative** and
+   * applied in **world space about a pivot**. `matrix` is in SVG
+   * `matrix(a b c d e f)` order (see {@link Matrix2D}).
+   *
+   * Semantics: the effective affine written to each member is
+   * `E = T(pivot) · matrix · T(-pivot)`, so the bare flip tuples become
+   * in-place flips about the pivot. Pivot defaults to the selection
+   * union-bbox center (via the attached surface's `geometry_provider`);
+   * pass `opts.pivot` to override.
+   *
+   * 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, and a
+   * net-identity leading matrix is dropped (so flip-then-flip restores
+   * the original). One atomic history step labelled `"transform"`.
+   *
+   * Refusal (returns `false`, no-op, no history): empty selection, no
+   * `geometry_provider`, or any member failing `is_rotatable` (the same
+   * non-trivial-transform / `<text rotate>` / CSS-property / animated
+   * gate `rotate` uses). All-or-nothing — no partial writes.
+   *
+   * Flat-doc limitation: only each element's OWN transform is folded;
+   * the pivot is treated as world ≡ parent space. Nested transformed
+   * ancestors (`<g transform=…>`) are out of scope.
+   */
+  transform(matrix: Matrix2D, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+    pivot?: {
+      x: number;
+      y: number;
+    };
+  }): boolean;
+  /**
+   * Collapse each selected member's `transform=` to a single `matrix(...)`
+   * token, baking accumulated translates / rotates / scales / skews into
+   * the equivalent affine. After flatten, the element's transform list
+   * classifies as `mixed` from the parser's view — but `rotate` will then
+   * refuse it. The point isn't to enable further rotation; it's to give
+   * the user an explicit pre-rotation reset path so accumulated trig
+   * drift has a recovery option.
+   *
+   * Returns `false` when nothing was changed (selection empty or every
+   * member already has no transform / a single matrix).
+   */
+  flatten_transform(opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  /**
+   * Translate each member so its bbox aligns with the requested edge or
+   * center of the selection's union bbox. Single atomic history step.
+   * Refuses (returns `false`) when fewer than two members have a world-
+   * bbox available — alignment with a single reference is undefined here
+   * (target-to-canvas / target-to-parent semantics are not yet designed).
+   */
+  align(direction: AlignDirection, opts?: {
+    ids?: ReadonlyArray<NodeId>;
+  }): boolean;
+  reorder(direction: ReorderDirection): void;
+  remove(): void;
+  /**
+   * Copy the selection as a **standalone SVG document** (the payload is
+   * the file format — no private envelope). The payload carries the
+   * outbound `url(#…)` / `href` reference closure in one `<defs>` block
+   * and declares every namespace prefix the fragment borrows from
+   * ancestor scope; ancestor transforms, inherited presentation, and the
+   * viewport are deliberately NOT carried (verbatim policy — see the FRD).
+   *
+   * Pure read: no document mutation, no history entry. The payload is
+   * always written to the editor's internal clipboard buffer (the
+   * transport floor — cannot fail) and, when a `ClipboardProvider` is
+   * configured, delivered to it best-effort (a failed provider write is
+   * dev-warned, never a copy failure).
+   *
+   * Returns the payload string, or `null` on empty / non-live selection
+   * (a no-op, not an error — copy has no refusal path).
+   */
+  copy(): string | null;
+  /**
+   * Copy, then delete the selection — ONE history step labeled `"cut"`
+   * with {@link remove}'s exact capture/revert semantics. The payload is
+   * secured in the internal buffer BEFORE the deletion commits, so a
+   * failed external write never strands the user with deleted content
+   * and no copy. The clipboard write is not part of the history step:
+   * undo restores the document and leaves the buffer holding the payload
+   * (cut → undo → paste works as a move idiom).
+   *
+   * Returns the payload string, or `null` on empty selection (no
+   * mutation, no history).
+   */
+  cut(): string | null;
+  /**
+   * Paste SVG markup — `text` when given, else the internal clipboard
+   * buffer. Synchronous over delivered text: acquisition from a native
+   * clipboard event or an async provider read is the invoking channel's
+   * job and completes before this command runs.
+   *
+   * Accepts anything {@link insert_fragment} parses (bare fragment or
+   * full document — the editor's own payloads are an ordinary case, not
+   * a privileged one) and inserts it with the same atomic semantics:
+   * one history step, subtrees adopted verbatim, ids never rewritten,
+   * namespace declarations hoisted, appended at the document top level,
+   * inserted roots selected.
+   *
+   * **Gesture-grade refusal table** (deliberately weaker than
+   * `insert_fragment`'s): paste's input is environment-supplied — prose,
+   * URLs, and JSON are what clipboards hold most of the day — so
+   * non-parseable input is a **no-op refusal** (`[]`, no mutation, no
+   * history), never a thrown error. A non-string argument still throws
+   * `TypeError` (caller bug — no acquisition channel produces one).
+   * Empty selection→buffer misses (`undefined` text, empty buffer) also
+   * return `[]`.
+   */
+  paste(text?: string): NodeId[];
+  /**
+   * Duplicate the selection in place — the **subtree-clone** operation
+   * (the clipboard FRD's second extraction operation; design note:
+   * `docs/wg/feat-svg-editor/subtree-clone.md`). Each normalized
+   * selection root is cloned verbatim (byte-equal subtree markup — and
+   * therefore NO defs closure, NO namespace shell: the destination is
+   * the source document) and inserted as its origin's next sibling, so
+   * the clone paints directly above its origin. Selection moves to the
+   * clones. ONE history step; a single `undo()` removes the clones and
+   * restores the prior selection.
+   *
+   * Authored `id=""` attributes are cloned verbatim, NEVER rewritten —
+   * the document gains colliding ids that resolve first-in-document-order
+   * (so a clone's internal self-reference resolves to the ORIGINAL);
+   * dedup is the explicit Tidy command's job.
+   *
+   * **Repeating offset** (gridaco/grida#825, spec §Repeating offset):
+   * duplicate, move the copy, duplicate again — the next copy lands at
+   * the same relative offset from the previous one (Figma's repeating
+   * duplicate; an Alt-drag clone commit arms the same memory, so ⌘D
+   * after a clone-drag repeats the drag offset). Still ONE history
+   * step: a single `undo()` removes copy + offset together. Requires an
+   * attached geometry provider; when the repeat's preconditions don't
+   * hold (selection isn't the previous clones, a copy was resized,
+   * nothing moved, no geometry) the command degrades to the plain
+   * in-place duplicate above — never an error.
+   *
+   * Refusal (no mutation, no history): an empty selection, or one that
+   * normalizes to nothing cloneable (document root, nested `<svg>`,
+   * stale / non-element ids) → `[]`. Returns the clone ids in document
+   * order otherwise.
+   */
+  duplicate(): NodeId[];
+  /**
+   * Wrap the current selection in a new plain `<g>`. Returns `true` if
+   * the wrap was performed (a history step was pushed and the new group
+   * is the active selection); `false` if the policy in `GROUPING.md`
+   * rejected the call.
+   */
+  group(): boolean;
+  /**
+   * Dissolve the selected `<g>` (or `opts.id`), hoisting its children
+   * into the group's parent at the group's z-position. Returns `true`
+   * when a history step was pushed (children hoisted, group removed, the
+   * former children selected); `false` when the call was refused.
+   *
+   * Only the **safe clean-structural subset** is accepted (see
+   * `core/group.ts:plan_ungroup` and `../docs/grouping.md` §Ungrouping).
+   * Refused — with NO mutation and NO history entry — when: the target
+   * is not a single `<g>`; the group is inside `<defs>`; the group has
+   * no element children; the group carries any own attribute beyond
+   * `{ transform, id, data-grida-id }` (i.e. any visual / cascade state
+   * such as `opacity` / `class` / `style` / `filter` / `clip-path` /
+   * `mask` / `fill`); the group's `id` is referenced by a `<use>`; a
+   * direct child is an SMIL animation element; or — when the group has a
+   * `transform` — any child's own transform is unparseable.
+   *
+   * When the group has a `transform`, it is BAKED into each child by
+   * prepending the group's parsed ops to the child's (clean token
+   * compose, not a matrix collapse), so paint output round-trips.
+   */
+  ungroup(opts?: {
+    id?: NodeId;
+  }): boolean;
+  /**
+   * Atomic one-shot insertion. Creates a new element of the given SVG
+   * tag with the supplied attributes (merged on top of the package's
+   * default paint attrs for `rect` / `ellipse` / `line`), inserts it at
+   * the given parent (default: root), and selects it. One undo step.
+   * Returns the new node id.
+   *
+   * Use this for paste, programmatic creation, and any non-pointer
+   * insertion path. The DOM surface's drag-to-size gesture uses
+   * `insert_preview` instead so it can bracket per-frame attr writes.
+   */
+  insert(tag: string, attrs: Readonly<Record<string, string>>, opts?: {
+    parent?: NodeId;
+    index?: number;
+    select?: boolean;
+  }): NodeId;
+  /**
+   * Atomic insertion of a pre-authored SVG **fragment** — one or more
+   * sibling elements as markup (`"<g …><path …/></g>"`), or a full
+   * `<svg>` document whose element children are taken as the content
+   * (the `<svg>` shell — viewBox, width/height, prolog, doctype — is
+   * discarded; an `<svg>` that is one of several top-level elements is
+   * content and inserted as-is). The element subtrees are adopted
+   * verbatim — every byte of trivia inside each element survives
+   * (attribute order, quote styles, whitespace, comments) — inserted
+   * contiguously in source order at `opts.parent` / `opts.index`, and
+   * selected. ONE history step regardless of fragment size; a single
+   * `undo()` restores the exact pre-insert serialization. Returns the
+   * inserted top-level ids in document order.
+   *
+   * This is the markup-shaped sibling of {@link insert} — the primitive
+   * paste and asset-stamping flows compose. Use `insert` for a tag +
+   * attrs; use `insert_fragment` for markup.
+   *
+   * **Position is authored content.** There is deliberately no placement
+   * opt: to land a fragment at a document-space point, author the
+   * position into the markup before inserting — wrap it in
+   * `<g transform="translate(x y)">…</g>` or set the elements' own
+   * geometry attrs. Placement then round-trips as ordinary markup and
+   * the whole drop is the same single undo step.
+   *
+   * **`id` collisions:** authored `id=""` attributes are inserted
+   * verbatim, NEVER rewritten — silent id renaming is proprietary noise
+   * (P1; README "What clean means" §3). When a fragment id collides
+   * with an existing one, reference resolution (`url(#…)`, `href`)
+   * follows the document-order rules of the host renderer; resolving
+   * the duplication is the explicit Tidy command's job, not insertion's.
+   *
+   * **Namespaces:** when the fragment uses a prefix the document root
+   * doesn't declare, the declaration is hoisted onto the root as part
+   * of the same history step — `xlink` (well-known URI) and any prefix
+   * the discarded `<svg>` shell declared. A prefix whose URI is not
+   * discoverable is left as authored (the input was equally unbound as
+   * a standalone document). An authored root declaration always wins —
+   * never rebound.
+   *
+   * **Refusals:** an input with no top-level elements (empty /
+   * whitespace / comments-only) returns `[]` with NO history step.
+   * Throws on malformed markup (parser errors propagate), on a
+   * non-string input, and on an `opts.parent` that isn't a live element
+   * of the current document — a silent no-op there would hide consumer
+   * bugs (same stance as `serialize_node`).
+   *
+   * `opts.parent` defaults to root; `opts.index` (position in the
+   * parent's element-children list; the whole fragment lands
+   * contiguously at it) defaults to append; `opts.select` defaults to
+   * `true`.
+   */
+  insert_fragment(svg: string, opts?: {
+    parent?: NodeId;
+    index?: number;
+    select?: boolean;
+  }): NodeId[];
+  /**
+   * Preview-bracketed insertion for drag-to-size gestures. Creates and
+   * inserts the node immediately (so HUD selection chrome renders);
+   * per-frame `update(attrs)` writes geometry; `commit()` collapses the
+   * gesture into one undo step; `discard()` rolls back as if the gesture
+   * never happened.
+   */
+  insert_preview(tag: string, initial: Readonly<Record<string, string>>, opts?: {
+    parent?: NodeId;
+    index?: number;
+  }): InsertPreviewSession;
+  set_text(value: string): void;
+  load_svg(svg: string): void;
+  serialize_svg(): string;
+  undo(): void;
+  redo(): void;
+  /**
+   * Register a command handler under a stable id. Returns an unregister
+   * function. Re-registering the same id replaces the previous handler.
+   *
+   * Handlers return `true` if they consumed the invocation; `false` or
+   * `undefined` signal "did not apply" — the keymap dispatcher will try
+   * the next candidate in the chain.
+   */
+  register(id: CommandId, handler: CommandHandler): () => void;
+  /**
+   * Invoke a registered command by id. Returns `true` if a handler
+   * consumed the invocation, `false` otherwise (including unknown ids).
+   */
+  invoke(id: CommandId, args?: unknown): boolean; /** Whether an id has a registered handler. */
+  has(id: CommandId): boolean;
+};
+/**
+ * Wide internal factory — returns the full object including the
+ * `_internal` / `keymap` surfaces in its inferred type. Stays private.
+ * The public `createSvgEditor` below wraps this and narrows the return
+ * to `SvgEditor` so the published `.d.ts` doesn't advertise internals.
+ */
+declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
+  /**
+   * Low-level IR handle. Mutating directly bypasses history; prefer
+   * `editor.commands` for app code.
+   */
+  document: SvgDocument;
+  readonly state: EditorState;
+  subscribe: (fn: (state: EditorState) => void) => Unsubscribe;
+  subscribe_with_selector: <T>(selector: (s: EditorState) => T, fn: (value: T, prev: T) => void, equals?: (a: T, b: T) => boolean) => Unsubscribe;
+  node_properties: (id: NodeId, names: ReadonlyArray<string>) => {
+    readonly [name: string]: PropertyValue;
+  };
+  node_paint: (id: NodeId, channel: "fill" | "stroke") => PaintValue;
+  dom_computed_property: (id: NodeId, name: string) => string | null;
+  dom_computed_paint: (id: NodeId, channel: "fill" | "stroke") => DomComputedPaint | null;
+  /**
+   * Enter content-edit mode on a `<text>` node. Returns `false` (no-op)
+   * when no DOM surface is attached.
+   */
+  enter_content_edit: (target?: NodeId) => boolean;
+  defs: Defs;
+  commands: Commands;
+  /**
+   * Human-readable label for hierarchy panels. SVG has no native "name";
+   * this is the package's single source of truth so panels don't reinvent
+   * the rule.
+   *
+   * Rule:
+   *   - `<text>` → text content, whitespace-collapsed and truncated at
+   *     ~40 chars (falls back to `"text"` for empty content).
+   *   - Otherwise → tag name, suffixed with `#id` when the `id` attribute
+   *     is present (e.g. `"rect #sun"`).
+   *
+   * `opts.tagLabel` lets callers substitute a friendlier or localized
+   * term for the raw tag (e.g. `"rect"` → `"Rectangle"`). Only invoked
+   * on the non-text branch.
+   */
+  display_label(id: NodeId, opts?: {
+    tagLabel?: (tag: string) => string;
+  }): string;
+  tree(): {
+    root: NodeId;
+    nodes: ReadonlyMap<NodeId, {
+      id: NodeId;
+      tag: string;
+      name?: string;
+      parent: NodeId | null;
+      children: ReadonlyArray<NodeId>;
+    }>;
+  };
+  /**
+   * The effective hover from the attached HUD surface — what's under the
+   * pointer, OR whatever `set_surface_hover_override` last pushed. Used
+   * by out-of-canvas UI (layers panel, breadcrumbs) to mirror the canvas
+   * highlight. Returns `null` when nothing is hovered.
+   */
+  surface_hover(): NodeId | null;
+  /**
+   * Push a hover override into the HUD surface — e.g. when the user
+   * hovers a row in a layers panel. The HUD will render the override's
+   * outline and (when applicable) drive measurement to that node.
+   * Pass `null` to clear and let the pointer pick take over again.
+   */
+  set_surface_hover_override(id: NodeId | null): void;
+  /**
+   * Subscribe to changes in the effective surface hover. Fires when the
+   * HUD reports a new pointer pick AND when an override is set/cleared.
+   * Cheap channel — does NOT bump `state.version`.
+   */
+  subscribe_surface_hover(cb: () => void): () => void;
+  /**
+   * Subscribe to pick (tap) outcomes — a discrete click on the canvas,
+   * reporting the document-space point and the node under it (`null` for
+   * empty canvas), plus the button and modifier snapshot. Fires once per
+   * tap, after the editor's own selection handling. Observe-only: a pick
+   * cannot alter selection, and the channel does NOT bump `state.version`.
+   * See {@link PickEvent}.
+   *
+   * @unstable
+   */
+  subscribe_pick(cb: (e: PickEvent) => void): Unsubscribe;
+  /**
+   * Subscribe to bounds-affecting changes. Fires when any document
+   * mutation advances `state.geometry_version` — drag, resize, text
+   * edit, structural insert/remove. Skips presentation-only writes
+   * (fill, opacity, stroke-color).
+   */
+  subscribe_geometry(cb: () => void): () => void;
+  /**
+   * World-space geometry queries. Non-null when a DOM surface is
+   * attached; null otherwise (queries need a renderer to read bbox
+   * from). Read-only — never mutates document state.
+   */
+  readonly geometry: GeometryProvider | null;
+  modes: readonly Mode[]; /** Switch the active tool. No history entry; bumps `state.version`. */
+  set_tool: (next: Tool) => void;
+  readonly style: Readonly<EditorStyle>;
+  set_style: (partial: Partial<EditorStyle>) => void;
+  load: (svg: string) => void;
+  serialize: () => string;
+  /**
+   * Serialize a single element's subtree as an SVG **fragment**, using the
+   * same trivia-preserving rules as {@link serialize} — for handing "the
+   * markup of the element the user selected" to a downstream consumer
+   * (e.g. an AI agent) without re-serializing the whole document.
+   *
+   * Fragment, not document (see `SvgDocument.serialize_node`): it does NOT
+   * carry `serialize()`'s whole-document round-trip guarantee. Namespace
+   * declarations on an ancestor (`xmlns:xlink`, normally on the root
+   * `<svg>`) are NOT inlined — a node using `xlink:href` serializes without
+   * `xmlns:xlink`. Throws on an unknown id or a non-element node.
+   */
+  serialize_node(id: NodeId): string;
+  reset: () => void;
+  attach: (surface: Surface) => SurfaceHandle;
+  detach: () => void;
+  dispose: () => void;
+  providers: Providers;
+  _internal: {
+    doc: SvgDocument;
+    history: {
+      preview: (label: string) => import("@grida/history").Preview;
+      undo_label: () => string | null;
+    };
+    clipboard: {
+      copy: () => string | null;
+      cut: () => string | null;
+    };
+    insert_text_preview: (initial: Readonly<Record<string, string>>, opts?: {
+      parent?: NodeId;
+    }) => {
+      id: NodeId;
+      commit(): void;
+      discard(): void;
+    };
+    emit: () => void;
+    subscribe_translate_commit(cb: () => void): () => void;
+    notify_translate_commit: () => void;
+    seed_duplication(record: subtree.DuplicationRecord): void;
+    set_content_edit_driver(fn: ((target: NodeId) => boolean) | null): void;
+    set_surface_hover_override_driver(fn: ((id: NodeId | null) => void) | null): void;
+    push_surface_hover(id: NodeId | null): void;
+    push_pick(e: PickEvent): void;
+    set_computed_resolver(fn: DomComputedResolver | null): void;
+    set_geometry(p: GeometryProvider | null): void;
+    register_command(id: string, handler: CommandHandler): () => void;
+    bump_geometry(): void;
+  };
+  keymap: Keymap;
+};
+/**
+ * Construct a headless SVG editor. The returned object is the public
+ * editor surface — observation (`state`, `subscribe`), commands
+ * (`commands.*`), lifecycle (`attach` / `dispose`), and the typed-read
+ * caches (`node_paint`, `node_properties`). Surfaces (DOM, headless)
+ * attach later via `editor.attach(surface)`.
+ */
+declare function createSvgEditor(opts: CreateSvgEditorOptions): SvgEditor;
+//#endregion
+export { RadialGradientDefinition as $, EditorState as A, LinearGradientDefinition as B, BoundsResolver as C, ClipboardProvider as D, CameraOptions as E, GradientEntry as F, PaintFallback as G, Mode as H, GradientStop as I, PickEvent as J, PaintPreviewSession as K, InsertPreviewSession as L, FileIOProvider as M, FontResolver as N, Color as O, GradientDefinition as P, Providers as Q, InsertableTag as R, AlignDirection as S, CameraConstraints as T, NodeId as U, Matrix2D as V, Paint as W, PropertyValue as X, PreviewSession as Y, Provenance as Z, PathModel as _, SelectMode as a, Vec2 as at, Verb as b, SvgEditor as c, GestureContext as d, Rect as et, GestureId as f, MemoizedGeometryProvider as g, GeometrySignals as h, DomComputedResolver as i, Unsubscribe as it, EditorStyle as j, DEFAULT_STYLE as k, createSvgEditor as l, GeometryProvider as m, CreateSvgEditorOptions as n, TOOL_CURSOR as nt, Surface as o, Gestures as p, PaintValue as q, DomComputedPaint as r, Tool as rt, SurfaceHandle as s, Commands as t, ReorderDirection as tt, GestureBinding as u, PathSnapshot as v, Camera as w, VertexId as x, SegmentId as y, InvalidComputedValue as z };