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

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

@@ -644,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. */
@@ -657,6 +659,18 @@ 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;
   /**
@@ -671,10 +685,9 @@ declare class SvgDocument implements DocumentEvents {
    * 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.
+   * `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;
@@ -1382,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.
@@ -1390,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 {
   /**
@@ -1766,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
@@ -2030,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;
@@ -2041,6 +2282,7 @@ 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;

package/dist/{editor-D2eQe8lB.d.mts → editor-KqpIW1qm.d.mts}

@@ -644,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. */
@@ -657,6 +659,18 @@ 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;
   /**
@@ -671,10 +685,9 @@ declare class SvgDocument implements DocumentEvents {
    * 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.
+   * `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;
@@ -1382,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.
@@ -1390,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 {
   /**
@@ -1766,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
@@ -2030,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;
@@ -2041,6 +2282,7 @@ 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;