@grida/svg-editor 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/{editor-Bd4-VCEJ.d.ts → editor-BKoo9SPL.d.ts}

@@ -1,6 +1,6 @@
 import cmath from "@grida/cmath";
-import { AnyNode } from "@grida/svg/parser";
-import * as _$_grida_history0 from "@grida/history";
+import vn from "@grida/vn";
+import { AnyNode, AttrToken } from "@grida/svg/parser";
 import { SelectMode } from "@grida/hud";
 import { Keybinding, Platform } from "@grida/keybinding";
 
@@ -24,12 +24,14 @@ type Rect = {
 };
 type Mode = "select" | "edit-content";
 /**
- * SVG element tags supported by the insertion subsystem. Closed set; adding
- * a new insertable tag requires a PR.
+ * SVG element tags inserted by the **drag-to-size** subsystem. Closed set;
+ * adding a new insertable tag requires a PR.
  *
- * `text` is deliberately out of v1: `<text>` has no intrinsic size and any
- * usable text-insert UX must immediately mount the inline content-editor on
- * the new node rather than dropping a placeholder. Reserved for a future 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";
 /**
@@ -48,6 +50,39 @@ type Tool = {
 } | {
   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 = {
@@ -221,8 +256,24 @@ type EditorState = {
    * 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
@@ -434,6 +485,91 @@ declare class Camera {
 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;
@@ -462,7 +598,7 @@ declare class SvgDocument implements DocumentEvents {
   private _structure_version;
   /** Bumps on writes that can shift world-space bounds (`GEOMETRY_ATTRS`,
    *  `set_text`, `insert`, `remove`). Cache key for `GeometryProvider`;
-   *  see docs/wg/feat-svg-editor/geometry.md. */
+   *  see ../../docs/geometry.md. */
   private _geometry_version;
   constructor(svg: string);
   static parse(svg: string): SvgDocument;
@@ -547,6 +683,94 @@ declare class SvgDocument implements DocumentEvents {
    * 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;
@@ -558,10 +782,297 @@ declare class SvgDocument implements DocumentEvents {
     ns?: string | null;
   }): NodeId;
   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>;
@@ -630,6 +1141,21 @@ type KeymapBinding = {
   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
@@ -675,8 +1201,9 @@ declare class Keymap {
    * bar even when the binding's handler rejects.
    *
    * Pure read; runs no handlers, no side effects. Honors the same
-   * text-input-focused guard `dispatch` uses, so a typing user's
-   * keystroke isn't "claimed" by an unrelated unmodified key.
+   * 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;
   /**
@@ -684,6 +1211,12 @@ declare class Keymap {
    * 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()`,
@@ -698,7 +1231,6 @@ declare class Keymap {
    * V1.
    */
   private chunkKeysFor;
-  private has_safe_mod;
 }
 //#endregion
 //#region src/core/geometry.d.ts
@@ -731,6 +1263,20 @@ interface GeometryProvider {
    * 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. */
@@ -738,7 +1284,7 @@ type GeometrySignals = {
 };
 /**
  * Caches `bounds_of` results keyed on `NodeId`; full-clears on either
- * `structure_version` or `geometry_version` bump. See docs/wg/feat-svg-editor/geometry.md for
+ * `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 {
@@ -755,6 +1301,10 @@ declare class MemoizedGeometryProvider implements GeometryProvider {
    */
   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;
 }
@@ -777,6 +1327,14 @@ type GestureContext = {
   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;
@@ -835,11 +1393,41 @@ type CreateSvgEditorOptions = {
   providers?: Providers;
   style?: Partial<EditorStyle>;
 };
-type SvgEditor = ReturnType<typeof createSvgEditor>;
+/**
+ * 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 = {
-  paint(snapshot: unknown): void;
-  hit_test(x: number, y: number): NodeId | null;
-  on_input(listener: (event: unknown) => void): Unsubscribe;
   dispose(): void;
 };
 type SurfaceHandle = {
@@ -1021,7 +1609,13 @@ type Commands = {
   invoke(id: CommandId, args?: unknown): boolean; /** Whether an id has a registered handler. */
   has(id: CommandId): boolean;
 };
-declare function createSvgEditor(opts: CreateSvgEditorOptions): {
+/**
+ * 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.
@@ -1110,6 +1704,19 @@ declare function createSvgEditor(opts: CreateSvgEditorOptions): {
   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;
@@ -1118,22 +1725,33 @@ declare function createSvgEditor(opts: CreateSvgEditorOptions): {
   _internal: {
     doc: SvgDocument;
     history: {
-      preview: (label: string) => _$_grida_history0.Preview;
+      preview: (label: string) => import("@grida/history").Preview;
+    };
+    insert_text_preview: (initial: Readonly<Record<string, string>>, opts?: {
+      parent?: NodeId;
+    }) => {
+      id: NodeId;
+      commit(): void;
+      discard(): void;
     };
     emit: () => void;
-    /** Fires after a drag-commit (via orchestrator), `commands.nudge`, or
-     *  `commands.translate`. The nudge-dwell watcher subscribes here. */
-    subscribe_translate_commit(cb: () => void): () => void; /** Drag-commit publisher; nudge/translate commands publish directly. */
+    subscribe_translate_commit(cb: () => void): () => void;
     notify_translate_commit: () => void;
     set_content_edit_driver(fn: ((target: NodeId) => boolean) | null): void;
-    /** Fires the driver immediately with the current override so the
-     *  surface can sync state on attach. */
     set_surface_hover_override_driver(fn: ((id: NodeId | null) => void) | null): void;
     push_surface_hover(id: NodeId | null): void;
-    set_computed_resolver(fn: DomComputedResolver | null): void; /** Surface registers its geometry provider on attach; clears on detach. */
+    set_computed_resolver(fn: DomComputedResolver | null): void;
     set_geometry(p: GeometryProvider | null): 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 { GradientEntry as A, PaintPreviewSession as B, Color as C, FileIOProvider as D, EditorStyle as E, LinearGradientDefinition as F, Providers as G, PreviewSession as H, Mode as I, ReorderDirection as J, RadialGradientDefinition as K, NodeId as L, InsertPreviewSession as M, InsertableTag as N, FontResolver as O, InvalidComputedValue as P, Vec2 as Q, Paint as R, ClipboardProvider as S, EditorState as T, PropertyValue as U, PaintValue as V, Provenance as W, Tool as X, TOOL_CURSOR as Y, Unsubscribe as Z, AlignDirection as _, SelectMode as a, CameraConstraints as b, SvgEditor as c, GestureContext as d, GestureId as f, MemoizedGeometryProvider as g, GeometrySignals as h, DomComputedResolver as i, GradientStop as j, GradientDefinition as k, createSvgEditor as l, GeometryProvider as m, CreateSvgEditorOptions as n, Surface as o, Gestures as p, Rect as q, DomComputedPaint as r, SurfaceHandle as s, Commands as t, GestureBinding as u, BoundsResolver as v, DEFAULT_STYLE as w, CameraOptions as x, Camera as y, PaintFallback as z };
+export { ReorderDirection as $, EditorState as A, LinearGradientDefinition as B, BoundsResolver as C, ClipboardProvider as D, CameraOptions as E, GradientEntry as F, PaintPreviewSession as G, NodeId as H, GradientStop as I, PropertyValue as J, PaintValue as K, InsertPreviewSession as L, FileIOProvider as M, FontResolver as N, Color as O, GradientDefinition as P, Rect as Q, InsertableTag as R, AlignDirection as S, CameraConstraints as T, Paint as U, Mode as V, PaintFallback as W, Providers as X, Provenance as Y, RadialGradientDefinition as Z, PathModel as _, SelectMode as a, Verb as b, SvgEditor as c, GestureContext as d, TOOL_CURSOR as et, GestureId as f, MemoizedGeometryProvider as g, GeometrySignals as h, DomComputedResolver as i, EditorStyle as j, DEFAULT_STYLE as k, createSvgEditor as l, GeometryProvider as m, CreateSvgEditorOptions as n, Unsubscribe as nt, Surface as o, Gestures as p, PreviewSession as q, DomComputedPaint as r, Vec2 as rt, SurfaceHandle as s, Commands as t, Tool as tt, GestureBinding as u, PathSnapshot as v, Camera as w, VertexId as x, SegmentId as y, InvalidComputedValue as z };