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

package/dist/{editor-BKoo9SPL.d.ts → editor-CYoGJ3Hf.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;
@@ -611,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;
@@ -781,6 +847,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
@@ -1482,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;
@@ -1527,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
@@ -1561,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
@@ -1577,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);
@@ -1685,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
@@ -1740,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;
 };
@@ -1754,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 };