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

package/README.md

@@ -249,9 +249,32 @@ editor.dispose(): void; // permanent teardown
 ```ts
 editor.load(svg: string): void; // replace the document (e.g. file-on-disk changed)
 editor.serialize(): string; // emit clean SVG — guaranteed round-trip per P1
+editor.serialize_node(id: NodeId): string; // emit ONE element's subtree — a fragment, see below
 editor.reset(): void; // back to last load() input, clears history
 ```
 
+`serialize_node(id)` exports the markup of a single element — the bridge from
+"what the user selected" (a `NodeId`) to "the SVG for that element," e.g. to
+hand a downstream consumer (an AI agent) the selected subtree without
+re-serializing the whole document. It reuses `serialize()`'s trivia-preserving
+rules (attribute order, quotes, whitespace, comments — emitted as authored).
+
+It is deliberately **weaker** than `serialize()`, and the two must not be
+conflated: `serialize()` emits the whole document and carries the P1
+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 into the fragment — 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 or a non-element node (selections are always elements).
+
+> A stable reference to a node that survives a `load()` — and survives an
+> external rewrite of the file — is a separate, unsolved problem (`NodeId`
+> regenerates on each parse). Positional child-index paths address only the
+> deterministic-re-parse case, not structural edits; durable node identity is
+> under design — see
+> [durable node identity](https://grida.co/docs/wg/feat-svg-editor/durable-node-identity).
+
 ### Observation — state
 
 ```ts
@@ -281,6 +304,25 @@ editor.subscribe_with_selector<T>(
 
 `state` is a frozen snapshot. Consumers never destructure into internals; if a view they need isn't here or in the purpose-built views below, that's an API gap.
 
+### Observation — pick (tap)
+
+A **pick** is a discrete tap on the canvas — a press and release within the drag threshold, no drag. It is observe-only and 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," which selection alone cannot express); a secondary (right-button) tap emits a pick and does **not** change selection. This is the seam a click-driven host tool needs — a comment / annotation tool anchors UI at `point` and scopes its action to `node_id`, or to the whole document when `null`.
+
+```ts
+type PickEvent = {
+  point: Vec2; // document-space — the pointer-DOWN point the tap resolved against
+  node_id: NodeId | null; // topmost node under point; null = empty canvas
+  button: "primary" | "secondary"; // middle is pan, never taps
+  mods: { shift: boolean; alt: boolean; meta: boolean; ctrl: boolean };
+};
+
+editor.subscribe_pick(fn: (e: PickEvent) => void): Unsubscribe;
+```
+
+The point is document-space and always the pointer-**down** point — so it stays correct even for a tap on an already-selected node (whose selection commits on pointer-up). The channel does **not** bump `state.version`. In React, wire it with `useEditorPick(handler)`.
+
+> **Status:** `@unstable` — shipped against one consumer; the shape is open until a second click-driven tool exercises it (P6).
+
 ### Observation — properties
 
 This section is about **property semantics on a single node**, following the CSS / SVG spec. Multi-selection ("mixed values") is a separate concern; see the [Multi-selection](#multi-selection-mixed-values) section below. The two are kept apart on purpose: property semantics is defined by the spec; mixed semantics is an aggregation layer the editor adds because it supports multi-select.
@@ -585,6 +627,8 @@ editor.commands.{
   resize_to(target: { width: number; height: number; anchor?: ResizeAnchor }): void;
   rotate(args: { angle: number; pivot?: { x: number; y: number } }): void;
   rotate_to(args: { angle: number; pivot?: { x: number; y: number } }): void;
+  // `matrix` is SVG `matrix(a b c d e f)` order (the `Matrix2D` tuple).
+  transform(matrix: Matrix2D, opts?: { ids?: NodeId[]; pivot?: { x: number; y: number } }): boolean;
   flatten_transform(): void;          // bake `transform=` into native attrs where possible
 
   // alignment (operates on selection of ≥2 nodes against their union bbox)
@@ -593,12 +637,24 @@ editor.commands.{
   // structure
   reorder(direction: "bring_forward" | "send_backward" | "bring_to_front" | "send_to_back"): void;
   group(): void;                      // wrap selection in a new <g>
+  ungroup(opts?: { id?: NodeId }): boolean; // dissolve a plain structural <g>
+                                      // (clean-structural subset only; refuses
+                                      // groups with visual state — see TODO §10)
   remove(): void;
 
   // insertion — `tag` is an open string (so paste / RPC can create any element,
   // e.g. "path"); only the closed `InsertableTag` set gets a pointer-driven
   // draw gesture and default paint.
   insert(tag: string, attrs?: Readonly<Record<string, string>>): NodeId;
+  // markup-shaped sibling of `insert` — one or more sibling elements, or a
+  // full `<svg>` doc (the shell is discarded; its children are the content).
+  // Subtrees adopted verbatim; ONE history step; returns root ids in
+  // document order. Authored ids are NEVER rewritten (dedup is Tidy's job);
+  // undeclared `xlink:` / shell-declared prefixes are hoisted onto the root
+  // in the same step. Position is authored content: wrap the fragment in
+  // `<g transform="translate(x y)">` to land it at a point — same single
+  // undo step, no placement opt.
+  insert_fragment(svg: string, opts?: { parent?: NodeId; index?: number; select?: boolean }): NodeId[];
   insert_preview(tag: string, initial?: Readonly<Record<string, string>>): InsertPreviewSession;
 
   // content
@@ -620,6 +676,8 @@ editor.commands.{
 
 All commands operate on `state.selection` unless they take an explicit target. Commands that can't apply (e.g. `set_text` with no text node selected) are no-ops, not errors.
 
+`transform` composes a general 2×3 affine onto the selection **relative** and **in world space about a pivot** (default: the selection union-bbox center) — `E = T(pivot) · matrix · T(-pivot)` — so a bare `[-1, 0, 0, 1, 0, 0]` is an in-place horizontal flip and `[1, 0, 0, -1, 0, 0]` a vertical one. The editor owns the 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; a net-identity leading matrix is dropped). It refuses (returns `false`, no history) on empty selection, no attached surface, or any member that isn't rotatable (matrix / scale / skew / `<text rotate>` / CSS-property / animated transforms — same gate as `rotate`; Flatten Transform is the recovery path). Flat-doc only: nested transformed ancestors are out of scope.
+
 (Naming convention for the API surface is `snake_case` to match the SVG / CSS property naming the editor already echoes — `set_property("stroke-width", …)` reads cleanly next to `set_paint("fill", …)`. JavaScript identifiers use `snake_case`; user-facing strings that mirror SVG attribute names stay `kebab-case` exactly as the spec writes them.)
 
 ### Providers
@@ -857,6 +915,7 @@ What this editor will never be. Each one is a defensive perimeter for the princi
 - **Not customizable in HUD layout.** Style spec only — no overlay slots, no handle replacement, no custom chrome components.
 - **Not a private IR.** SVG is the source of truth. The editor does not maintain an alternative on-disk format, and the bytes are not projected from any in-memory canonical store. (The internal typed element IR described under [Paradigm § Element IR (internal)](#element-ir-internal) is a typed view over the parsed AST, not a store the file is derived from — the AST and the file are the source of truth, and the IR is rebuilt from them on each load.)
 - **Not a serializer playground.** Round-trip rules are fixed (P1). No "compact mode," no "Prettier mode," no consumer-supplied formatter.
+- **Not an input-interception hook.** The pick/tap observation (`subscribe_pick`) reports a click that already happened; it cannot prevent, delay, or replace the editor's own selection and gesture handling. A host that needs to intercept input owns the container and splices its own layer in (the DOM escape hatch) — it does not get a veto through the observation surface.
 
 If a consumer needs any of the above, the right answer is "this is the wrong tool." Saying yes to any one is the path that turned the Grida main editor into a 6,800-line god-class.
 

package/dist/{dom-Dz_V6q0Y.d.mts → dom-98AUOfsP.d.mts}

@@ -1,4 +1,4 @@
-import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-YQwdWHBb.mjs";
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-D2eQe8lB.mjs";
 import cmath from "@grida/cmath";
 import { guide } from "@grida/cmath/_snap";
 
@@ -13,6 +13,35 @@ type SnapOptions = {
 declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
 //#endregion
 //#region src/dom.d.ts
+/**
+ * Wire a web-font settle source to the editor's geometry channel.
+ *
+ * The DOM surface re-serializes the `<svg>` on every editor tick, but a
+ * `<text>` / `<tspan>` bbox can change with NO attribute write: a web font
+ * finishing load AFTER its `font-family` / `font-size` was already written.
+ * The IR never sees that reflow, so nothing bumps `geometry_version` and
+ * every bounds-keyed consumer (snap, HUD chrome, size meter) stays stuck at
+ * the fallback-face metrics until the next real edit.
+ *
+ * Listens for `loadingdone` on `source` (a `FontFaceSet`, or any injected
+ * `EventTarget` in tests) and calls `bump` once per settle. COARSE on
+ * purpose: one bump clears the WHOLE bounds cache, not just text nodes —
+ * consistent with the package's pessimistic-invalidation stance, and far
+ * cheaper than scoping the bump to the (possibly many) reflowed runs.
+ *
+ * Also bumps once when `source.ready` resolves (when present): fonts that
+ * settled before attach — a cache hit, or `font-display` resolving the same
+ * tick the surface mounts — never re-fire `loadingdone`, so a document
+ * mounted post-settle still needs one bump to re-read at the real metrics.
+ *
+ * Returns a teardown that removes the listener and neutralizes the pending
+ * `ready` bump (leak guard) — call it on surface detach.
+ *
+ * Factored out of the surface so it can be unit-tested with a fake
+ * `EventTarget` in the node-only test env (jsdom's `FontFaceSet` is
+ * incomplete); never a real font / network.
+ */
+declare function install_font_load_geometry_bump(source: EventTarget | null, bump: () => void): () => void;
 type DomSurfaceOptions = {
   /** Mount the SVG inside this container. */container: HTMLElement;
   /**
@@ -33,6 +62,19 @@ type DomSurfaceOptions = {
    * when `fit: true`.
    */
   initial_camera?: cmath.Transform;
+  /**
+   * Font-load settle source — the `EventTarget` whose `loadingdone` event
+   * signals "web fonts finished loading, text may have reflowed." Defaults
+   * to `container.ownerDocument.fonts` (the live `FontFaceSet`). The
+   * surface installs a `loadingdone` listener that advances the editor's
+   * geometry channel so text bounds re-read at the settled glyph metrics
+   * (see ../docs/geometry.md §Limitations "Text bbox depends on font").
+   *
+   * Injectable as a DOM seam: jsdom's `FontFaceSet` is incomplete, so
+   * tests pass a plain `EventTarget` stub and `dispatchEvent(new Event(
+   * "loadingdone"))` to simulate a settle without a real font / network.
+   */
+  font_load_source?: EventTarget;
 };
 /**
  * Surface handle for the DOM surface. Extends the editor's core
@@ -111,4 +153,4 @@ declare function inverse_project_rect(rect: {
   f: number;
 }, offset: readonly [number, number]): cmath.Rectangle | null;
 //#endregion
-export { project_delta_inverse_ctm as a, SnapOptions as c, inverse_project_rect as i, DomSurfaceOptions as n, project_point_through_ctm as o, attach_dom_surface as r, DEFAULT_SNAP_OPTIONS as s, DomSurfaceHandle as t };
+export { inverse_project_rect as a, DEFAULT_SNAP_OPTIONS as c, install_font_load_geometry_bump as i, SnapOptions as l, DomSurfaceOptions as n, project_delta_inverse_ctm as o, attach_dom_surface as r, project_point_through_ctm as s, DomSurfaceHandle as t };

package/dist/{dom-D4dy6kq5.d.ts → dom-BO2-E9oK.d.ts}

@@ -1,4 +1,4 @@
-import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-CJ2KuRh5.js";
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-CYoGJ3Hf.js";
 import cmath from "@grida/cmath";
 //#region src/core/snap/options.d.ts
 type SnapOptions = {
@@ -11,6 +11,35 @@ type SnapOptions = {
 declare const DEFAULT_SNAP_OPTIONS: SnapOptions;
 //#endregion
 //#region src/dom.d.ts
+/**
+ * Wire a web-font settle source to the editor's geometry channel.
+ *
+ * The DOM surface re-serializes the `<svg>` on every editor tick, but a
+ * `<text>` / `<tspan>` bbox can change with NO attribute write: a web font
+ * finishing load AFTER its `font-family` / `font-size` was already written.
+ * The IR never sees that reflow, so nothing bumps `geometry_version` and
+ * every bounds-keyed consumer (snap, HUD chrome, size meter) stays stuck at
+ * the fallback-face metrics until the next real edit.
+ *
+ * Listens for `loadingdone` on `source` (a `FontFaceSet`, or any injected
+ * `EventTarget` in tests) and calls `bump` once per settle. COARSE on
+ * purpose: one bump clears the WHOLE bounds cache, not just text nodes —
+ * consistent with the package's pessimistic-invalidation stance, and far
+ * cheaper than scoping the bump to the (possibly many) reflowed runs.
+ *
+ * Also bumps once when `source.ready` resolves (when present): fonts that
+ * settled before attach — a cache hit, or `font-display` resolving the same
+ * tick the surface mounts — never re-fire `loadingdone`, so a document
+ * mounted post-settle still needs one bump to re-read at the real metrics.
+ *
+ * Returns a teardown that removes the listener and neutralizes the pending
+ * `ready` bump (leak guard) — call it on surface detach.
+ *
+ * Factored out of the surface so it can be unit-tested with a fake
+ * `EventTarget` in the node-only test env (jsdom's `FontFaceSet` is
+ * incomplete); never a real font / network.
+ */
+declare function install_font_load_geometry_bump(source: EventTarget | null, bump: () => void): () => void;
 type DomSurfaceOptions = {
   /** Mount the SVG inside this container. */container: HTMLElement;
   /**
@@ -31,6 +60,19 @@ type DomSurfaceOptions = {
    * when `fit: true`.
    */
   initial_camera?: cmath.Transform;
+  /**
+   * Font-load settle source — the `EventTarget` whose `loadingdone` event
+   * signals "web fonts finished loading, text may have reflowed." Defaults
+   * to `container.ownerDocument.fonts` (the live `FontFaceSet`). The
+   * surface installs a `loadingdone` listener that advances the editor's
+   * geometry channel so text bounds re-read at the settled glyph metrics
+   * (see ../docs/geometry.md §Limitations "Text bbox depends on font").
+   *
+   * Injectable as a DOM seam: jsdom's `FontFaceSet` is incomplete, so
+   * tests pass a plain `EventTarget` stub and `dispatchEvent(new Event(
+   * "loadingdone"))` to simulate a settle without a real font / network.
+   */
+  font_load_source?: EventTarget;
 };
 /**
  * Surface handle for the DOM surface. Extends the editor's core
@@ -109,4 +151,4 @@ declare function inverse_project_rect(rect: {
   f: number;
 }, offset: readonly [number, number]): cmath.Rectangle | null;
 //#endregion
-export { project_delta_inverse_ctm as a, SnapOptions as c, inverse_project_rect as i, DomSurfaceOptions as n, project_point_through_ctm as o, attach_dom_surface as r, DEFAULT_SNAP_OPTIONS as s, DomSurfaceHandle as t };
+export { inverse_project_rect as a, DEFAULT_SNAP_OPTIONS as c, install_font_load_geometry_bump as i, SnapOptions as l, DomSurfaceOptions as n, project_delta_inverse_ctm as o, attach_dom_surface as r, project_point_through_ctm as s, DomSurfaceHandle as t };