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

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

@@ -1,6 +1,6 @@
 import cmath from "@grida/cmath";
+import vn from "@grida/vn";
 import { AnyNode } from "@grida/svg/parser";
-import * as _$_grida_history0 from "@grida/history";
 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,33 @@ 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.
+ *   - `polyline` / `polygon` points are `[x, y]` tuples so the consumer
+ *     can hand them straight to `vn.fromPolyline` / `vn.fromPolygon`.
+ */
+type VectorEditSource = {
+  kind: "path";
+  d: string;
+} | {
+  kind: "polyline";
+  points: ReadonlyArray<readonly [number, number]>;
+} | {
+  kind: "polygon";
+  points: ReadonlyArray<readonly [number, number]>;
+};
 interface DocumentEvents {
   /** Fires after any structural mutation. */
   on_change(fn: () => void): () => void;
@@ -462,7 +540,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 +625,44 @@ 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`.
+   *
+   * v1 eligibility:
+   *   - `<path>`     — requires non-empty `d`.
+   *   - `<polyline>` — requires `points` parseable to ≥ 2 vertices.
+   *   - `<polygon>`  — same as polyline.
+   *
+   * Deliberately rejects `<line>` in v1: the only useful vertex-edit
+   * gestures on a `<line>` are (a) introducing a new vertex (which would
+   * have to promote it to `<polyline>`) and (b) bending it with a tangent
+   * (which would have to promote it to `<path>`). Both promotions are
+   * out of scope for v1, so opening a `<line>` in vector-edit mode would
+   * advertise capabilities that don't work.
+   *
+   * Also rejects `<rect>`, `<circle>`, `<ellipse>`, `<image>`, `<use>` —
+   * those would force the same promotion-to-`<path>` machinery (trivia
+   * transfer, cross-cutting attr carry, DOM-element swap, history-bracket
+   * changes) that v1 keeps out of scope.
+   */
+  is_vector_edit_target(id: NodeId): VectorEditSource | null;
+  /**
+   * 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;
@@ -562,6 +678,262 @@ declare class SvgDocument implements DocumentEvents {
   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).
+   * - **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.)
+   *
+   * Anything that changes segment topology (insert-vertex, delete-vertex,
+   * close/open shape) leaves the canonical chain and returns `null` here;
+   * the higher layer is responsible for routing those to tag-promotion
+   * (intra-Vertex or to-path).
+   */
+  toNativeAttrs(source_tag: VectorEditSource["kind"]): Exclude<VectorEditSource, {
+    kind: "path";
+  }> | 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 +1002,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 +1062,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 +1072,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 +1092,6 @@ declare class Keymap {
    * V1.
    */
   private chunkKeysFor;
-  private has_safe_mod;
 }
 //#endregion
 //#region src/core/geometry.d.ts
@@ -738,7 +1131,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 {
@@ -777,6 +1170,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 +1236,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 +1452,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.
@@ -1118,22 +1555,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 };