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

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

@@ -1,6 +1,6 @@
 import cmath from "@grida/cmath";
 import vn from "@grida/vn";
-import { AnyNode } from "@grida/svg/parser";
+import { AnyNode, AttrToken } from "@grida/svg/parser";
 import { SelectMode } from "@grida/hud";
 import { Keybinding, Platform } from "@grida/keybinding";
 
@@ -22,6 +22,54 @@ type Rect = {
   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;
@@ -499,18 +547,76 @@ type AlignDirection = "left" | "right" | "top" | "bottom" | "horizontal_centers"
  *   - 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`.
+ *   - `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. */
@@ -553,6 +659,24 @@ declare class SvgDocument implements DocumentEvents {
   get structure_version(): 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
+   * it must not bump `doc_version` / mark the doc dirty / touch undo
+   * (the editor's `on_change` handler does all three). 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;
@@ -629,24 +753,74 @@ declare class SvgDocument implements DocumentEvents {
    * Returns a tag-discriminated snapshot of the authored geometry attrs
    * if this node is eligible for vector (vertex) editing — else `null`.
    *
-   * v1 eligibility:
+   * 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`.
    *
-   * 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.
+   * 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.
    *
-   * 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.
+   * 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).
@@ -673,7 +847,115 @@ declare class SvgDocument implements DocumentEvents {
     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;
 }
@@ -795,20 +1077,26 @@ declare class PathModel {
    *
    * - **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) leaves the canonical chain and returns `null` here;
-   * the higher layer is responsible for routing those to tag-promotion
-   * (intra-Vertex or to-path).
+   * 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"]): Exclude<VectorEditSource, {
-    kind: "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
@@ -1124,6 +1412,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. */
@@ -1148,6 +1450,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;
 }
@@ -1325,16 +1631,46 @@ type Commands = {
    * member.
    *
    * The default selection is `state.selection`. Pass `opts.ids` to
-   * override. Members whose tag is not resizable
-   * (e.g. `<g>`) are skipped silently; the gesture is a no-op when no
-   * resizable member remains. Returns `true` when a history step was
-   * pushed.
+   * 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;
@@ -1370,6 +1706,39 @@ type Commands = {
       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
@@ -1404,6 +1773,30 @@ type Commands = {
    * 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
@@ -1420,6 +1813,63 @@ type Commands = {
     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);
@@ -1528,6 +1978,17 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
    * 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
@@ -1547,6 +2008,19 @@ declare function _create_svg_editor_internal(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;
@@ -1570,8 +2044,10 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
     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;
+    bump_geometry(): void;
   };
   keymap: Keymap;
 };
@@ -1584,4 +2060,4 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
  */
 declare function createSvgEditor(opts: CreateSvgEditorOptions): SvgEditor;
 //#endregion
-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 };
+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 };