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

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

@@ -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;
@@ -596,6 +644,8 @@ declare class SvgDocument implements DocumentEvents {
    * stays the same and React skips the re-render of the whole tree.
    */
   private _structure_version;
+  /** Total listener-visible mutation count. See the `revision` getter. */
+  private _revision;
   /** Bumps on writes that can shift world-space bounds (`GEOMETRY_ATTRS`,
    *  `set_text`, `insert`, `remove`). Cache key for `GeometryProvider`;
    *  see ../../docs/geometry.md. */
@@ -609,8 +659,37 @@ declare class SvgDocument implements DocumentEvents {
   on_change(fn: () => void): () => void;
   /** See `_structure_version` for what this counter signals. */
   get structure_version(): number;
+  /**
+   * Total mutation counter — advances on EVERY listener-visible mutation
+   * (attribute, style, text, topology, load/reset), unlike the selective
+   * `structure_version` / `geometry_version` channels. The single
+   * edit-version source: anything derived from this document — the
+   * editor's `content_version` / `dirty`, memoized reads, a rendered
+   * projection — answers "am I current?" by comparing values, with no
+   * event-ordering dependence. Advances BEFORE listeners fire, so a
+   * read issued from inside a change listener already sees the new
+   * value.
+   */
+  get revision(): number;
   /** See `_geometry_version` for what this counter signals. */
   get geometry_version(): number;
+  /**
+   * Advance `_geometry_version` by exactly 1 WITHOUT touching the tree,
+   * any attribute, `structure_version`, or the `on_change` listeners.
+   *
+   * The one geometry mutation with no attribute write: a `<text>` /
+   * `<tspan>` reflow the IR cannot see — a web font finishing load AFTER
+   * the `font-family` / `font-size` write was already serialized. The DOM
+   * surface observes the reflow (`document.fonts` `loadingdone`) and asks
+   * the geometry channel to advance so the bounds cache re-reads the
+   * settled glyph metrics. See ../../docs/geometry.md §Limitations.
+   *
+   * Deliberately does NOT call `emit()`: this is not a document edit, so
+   * `revision` must not advance — no dirty flag, no undo, no render
+   * flush. The editor's `_internal.bump_geometry` advances
+   * `geometry_version` here and fans out the geometry listeners itself.
+   */
+  bump_geometry(): void;
   private emit;
   /** Notify subscribers — for callers that mutate directly via setAttr/etc. */
   notify(): void;
@@ -781,6 +860,89 @@ 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
@@ -1233,6 +1395,129 @@ declare class Keymap {
   private chunkKeysFor;
 }
 //#endregion
+//#region src/core/subtree.d.ts
+declare namespace subtree {
+  /**
+   * Document-order comparator over node ids. Builds the index once per
+   * call (one full tree walk) — create one comparator per operation and
+   * reuse it, as `clipboard.extract_payload` does.
+   */
+  function by_document_order(doc: SvgDocument): (a: NodeId, b: NodeId) => number;
+  /**
+   * Selection normalization — the half of extraction that payload
+   * extraction (copy) and subtree clone share, per the FRD:
+   * dedupe → live elements only → ancestor subtrees subsume selected
+   * descendants (`prune_nested_nodes`) → DOCUMENT order regardless of
+   * selection order (sibling order is paint order, and paint order is
+   * meaning). Stale / non-element / detached ids are skipped, never
+   * thrown — normalization is a filter, not a validator.
+   */
+  function normalize_roots(doc: SvgDocument, selection: ReadonlyArray<NodeId>, order?: (a: NodeId, b: NodeId) => number): NodeId[];
+  /** One origin → clone pairing with the clone's placement, captured at
+   *  plan time. `before` is the origin's next sibling NODE (element or
+   *  trivia) so the clone lands immediately after its origin. */
+  type SubtreeClonePlanEntry = {
+    origin: NodeId;
+    /** Registered in the document's node map, DETACHED (`create_fragment`
+     *  style) — the consumer inserts it inside its own history closure. */
+    clone: NodeId; /** `parent_of(origin)` at plan time. */
+    parent: NodeId; /** `next_sibling_of(origin)` at plan time; `null` = append. */
+    before: NodeId | null;
+  };
+  type SubtreeClonePlan = ReadonlyArray<SubtreeClonePlanEntry>;
+  /**
+   * Build a clone plan for the selection: for each normalized origin,
+   * serialize its subtree verbatim and re-adopt it under fresh runtime
+   * NodeIds via `create_fragment` — the markup round-trip rides the same
+   * trivia-preserving emit and never-rewrite-ids adoption the package
+   * already guarantees, so `serialize_node(clone) === serialize_node(origin)`
+   * byte-for-byte once inserted.
+   *
+   * Clones are returned DETACHED (plan, don't insert): consumers own
+   * insertion inside their history closures so redo can re-insert the
+   * same NodeIds (`remove` keeps nodes in the id map).
+   *
+   * Skipped origins (refusals, normalized away — not errors):
+   *   - the document root and any other parentless node (no sibling slot);
+   *   - nested `<svg>` elements — `create_fragment` deliberately treats a
+   *     lone `<svg>` root as a full-document shell and discards it (the
+   *     FRD's paste rule), which would silently unwrap the clone; refusing
+   *     beats mishandling.
+   *
+   * An empty selection (or one that normalizes to nothing) yields an
+   * empty plan — the caller's no-op.
+   */
+  function clone_plan(doc: SvgDocument, selection: ReadonlyArray<NodeId>): SubtreeClonePlan;
+  /**
+   * Attach every plan clone at its captured anchor. Anchors predate the
+   * plan (captured before any insertion), so no entry anchors on another
+   * entry's clone — each insert is independent and the interleaved
+   * `A, A′, B, B′` order falls out of the per-origin anchors.
+   *
+   * Idempotent: `doc.insert` detaches-then-splices, so re-attaching an
+   * already-live clone repositions it to the same slot. History redo
+   * closures rely on this.
+   */
+  function insert_plan(doc: SvgDocument, plan: SubtreeClonePlan): void;
+  /**
+   * Detach every plan clone. Order-independent for the same reason
+   * {@link insert_plan} is: anchors are never plan clones. Removed nodes
+   * stay in the document's id map (standard removed-node policy), so a
+   * later {@link insert_plan} over the same plan restores them.
+   */
+  function remove_plan(doc: SvgDocument, plan: SubtreeClonePlan): void;
+  /**
+   * The last committed duplication — the memory the repeating-offset
+   * behavior reads (gridaco/grida#825; spec:
+   * [docs/wg/feat-svg-editor/subtree-clone.md](../../../../docs/wg/feat-svg-editor/subtree-clone.md)
+   * §Repeating offset). Armed by `commands.duplicate` and by a cloned
+   * translate commit (Alt-drag); consumed and re-armed by the next
+   * `duplicate()`. Editor-session state — never observable, never in
+   * history. Staleness is caught at use by {@link repeat_delta}, not by
+   * per-mutation bookkeeping.
+   *
+   * The arrays are INDEX-PAIRED: `clones[i]` is the clone of
+   * `origins[i]` (both producers derive them from the same
+   * {@link SubtreeClonePlan}). {@link repeat_delta}'s per-member
+   * rigidity check depends on that pairing.
+   */
+  type DuplicationRecord = {
+    origins: ReadonlyArray<NodeId>;
+    clones: ReadonlyArray<NodeId>;
+  };
+  /**
+   * The repeating-offset delta (gridaco/grida#825): given the previous
+   * duplication's record and the CURRENT duplicate's normalized origins,
+   * return the world-space offset the fresh clones should repeat, or
+   * `null` for "no repeat — duplicate in place".
+   *
+   * The repeat fires only when the record still witnesses
+   * "duplicate, then rigidly translate the copies":
+   *   - `targets` is exactly `record.clones`, in the same (document)
+   *     order — the user is duplicating the previous duplication's
+   *     copies and nothing else;
+   *   - `bounds_of` answers for EVERY member of both sets (a detached
+   *     member, a measureless tag, or a missing geometry provider all
+   *     refuse);
+   *   - EVERY clone is rigid against its own origin (the record's
+   *     arrays are index-paired): same size, displaced by the same
+   *     delta as the union, within {@link REPEAT_RIGID_EPSILON}. The
+   *     check is per member, not per envelope — a rearranged or
+   *     resized inner copy is no longer a translate even when the
+   *     envelope-defining copies keep the union bbox intact;
+   *   - the union top-left delta exceeds the same tolerance (a copy
+   *     that never moved — or drifted by float noise only — repeats
+   *     nothing; the in-place duplicate stays byte-equal instead of
+   *     inheriting noise-sized attribute writes).
+   *
+   * Pure and gesture-grade: reads only through `bounds_of`, never
+   * throws — every failed precondition degrades to `null` (the main
+   * editor's `active_duplication` assert-on-mismatch is deliberately
+   * NOT copied; ⌘D must never crash on a stale record).
+   */
+  function repeat_delta(record: DuplicationRecord | null, targets: ReadonlyArray<NodeId>, bounds_of: (id: NodeId) => Rect | null): Vec2 | null;
+}
+//#endregion
 //#region src/core/geometry.d.ts
 /**
  * Read-only access to world-space node bounds and hit-tests.
@@ -1241,6 +1526,19 @@ declare class Keymap {
  * will query dozens of nodes per pointermove. The driver wraps SVG
  * `getBBox` + `getCTM`; the memoizer caches per-`NodeId` to survive
  * the surface re-rendering the SVG tree every editor tick.
+ *
+ * **Freshness contract.** Every read MUST reflect the CURRENT document
+ * — including when issued synchronously from inside a doc-change
+ * listener (`subscribe_geometry` fires mid-mutation, before any
+ * render). An implementation backed by a lazily-synced projection
+ * (e.g. a rendered DOM tree) must flush that projection before
+ * reading; compare `SvgDocument.revision` against the projection's
+ * last-rendered revision. Returning the previous document's geometry
+ * is not a transient glitch: the `MemoizedGeometryProvider` wrapper
+ * caches whatever the driver returns, so one stale read poisons every
+ * later consumer until the next invalidation (align/resize then plan
+ * against one-mutation-old bounds and oscillate — see
+ * `__tests__/geometry-stale-read.browser.test.ts`).
  */
 interface GeometryProvider {
   /**
@@ -1482,16 +1780,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;
@@ -1527,6 +1855,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
@@ -1554,6 +1915,93 @@ type Commands = {
   }): boolean;
   reorder(direction: ReorderDirection): void;
   remove(): void;
+  /**
+   * Copy the selection as a **standalone SVG document** (the payload is
+   * the file format — no private envelope). The payload carries the
+   * outbound `url(#…)` / `href` reference closure in one `<defs>` block
+   * and declares every namespace prefix the fragment borrows from
+   * ancestor scope; ancestor transforms, inherited presentation, and the
+   * viewport are deliberately NOT carried (verbatim policy — see the FRD).
+   *
+   * Pure read: no document mutation, no history entry. The payload is
+   * always written to the editor's internal clipboard buffer (the
+   * transport floor — cannot fail) and, when a `ClipboardProvider` is
+   * configured, delivered to it best-effort (a failed provider write is
+   * dev-warned, never a copy failure).
+   *
+   * Returns the payload string, or `null` on empty / non-live selection
+   * (a no-op, not an error — copy has no refusal path).
+   */
+  copy(): string | null;
+  /**
+   * Copy, then delete the selection — ONE history step labeled `"cut"`
+   * with {@link remove}'s exact capture/revert semantics. The payload is
+   * secured in the internal buffer BEFORE the deletion commits, so a
+   * failed external write never strands the user with deleted content
+   * and no copy. The clipboard write is not part of the history step:
+   * undo restores the document and leaves the buffer holding the payload
+   * (cut → undo → paste works as a move idiom).
+   *
+   * Returns the payload string, or `null` on empty selection (no
+   * mutation, no history).
+   */
+  cut(): string | null;
+  /**
+   * Paste SVG markup — `text` when given, else the internal clipboard
+   * buffer. Synchronous over delivered text: acquisition from a native
+   * clipboard event or an async provider read is the invoking channel's
+   * job and completes before this command runs.
+   *
+   * Accepts anything {@link insert_fragment} parses (bare fragment or
+   * full document — the editor's own payloads are an ordinary case, not
+   * a privileged one) and inserts it with the same atomic semantics:
+   * one history step, subtrees adopted verbatim, ids never rewritten,
+   * namespace declarations hoisted, appended at the document top level,
+   * inserted roots selected.
+   *
+   * **Gesture-grade refusal table** (deliberately weaker than
+   * `insert_fragment`'s): paste's input is environment-supplied — prose,
+   * URLs, and JSON are what clipboards hold most of the day — so
+   * non-parseable input is a **no-op refusal** (`[]`, no mutation, no
+   * history), never a thrown error. A non-string argument still throws
+   * `TypeError` (caller bug — no acquisition channel produces one).
+   * Empty selection→buffer misses (`undefined` text, empty buffer) also
+   * return `[]`.
+   */
+  paste(text?: string): NodeId[];
+  /**
+   * Duplicate the selection in place — the **subtree-clone** operation
+   * (the clipboard FRD's second extraction operation; design note:
+   * `docs/wg/feat-svg-editor/subtree-clone.md`). Each normalized
+   * selection root is cloned verbatim (byte-equal subtree markup — and
+   * therefore NO defs closure, NO namespace shell: the destination is
+   * the source document) and inserted as its origin's next sibling, so
+   * the clone paints directly above its origin. Selection moves to the
+   * clones. ONE history step; a single `undo()` removes the clones and
+   * restores the prior selection.
+   *
+   * Authored `id=""` attributes are cloned verbatim, NEVER rewritten —
+   * the document gains colliding ids that resolve first-in-document-order
+   * (so a clone's internal self-reference resolves to the ORIGINAL);
+   * dedup is the explicit Tidy command's job.
+   *
+   * **Repeating offset** (gridaco/grida#825, spec §Repeating offset):
+   * duplicate, move the copy, duplicate again — the next copy lands at
+   * the same relative offset from the previous one (Figma's repeating
+   * duplicate; an Alt-drag clone commit arms the same memory, so ⌘D
+   * after a clone-drag repeats the drag offset). Still ONE history
+   * step: a single `undo()` removes copy + offset together. Requires an
+   * attached geometry provider; when the repeat's preconditions don't
+   * hold (selection isn't the previous clones, a copy was resized,
+   * nothing moved, no geometry) the command degrades to the plain
+   * in-place duplicate above — never an error.
+   *
+   * Refusal (no mutation, no history): an empty selection, or one that
+   * normalizes to nothing cloneable (document root, nested `<svg>`,
+   * stale / non-element ids) → `[]`. Returns the clone ids in document
+   * order otherwise.
+   */
+  duplicate(): NodeId[];
   /**
    * Wrap the current selection in a new plain `<g>`. Returns `true` if
    * the wrap was performed (a history step was pushed and the new group
@@ -1561,6 +2009,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
@@ -1577,6 +2049,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);
@@ -1685,6 +2214,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
@@ -1726,6 +2266,11 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
     doc: SvgDocument;
     history: {
       preview: (label: string) => import("@grida/history").Preview;
+      undo_label: () => string | null;
+    };
+    clipboard: {
+      copy: () => string | null;
+      cut: () => string | null;
     };
     insert_text_preview: (initial: Readonly<Record<string, string>>, opts?: {
       parent?: NodeId;
@@ -1737,11 +2282,14 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
     emit: () => void;
     subscribe_translate_commit(cb: () => void): () => void;
     notify_translate_commit: () => void;
+    seed_duplication(record: subtree.DuplicationRecord): void;
     set_content_edit_driver(fn: ((target: NodeId) => boolean) | null): void;
     set_surface_hover_override_driver(fn: ((id: NodeId | null) => void) | null): void;
     push_surface_hover(id: NodeId | null): void;
+    push_pick(e: PickEvent): void;
     set_computed_resolver(fn: DomComputedResolver | null): void;
     set_geometry(p: GeometryProvider | null): void;
+    bump_geometry(): void;
   };
   keymap: Keymap;
 };
@@ -1754,4 +2302,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 };