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

package/README.md

@@ -304,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.
@@ -608,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)
@@ -616,12 +637,57 @@ 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;
 
+  // clipboard — the payload is a STANDALONE SVG DOCUMENT, not a private
+  // format (the file is the IR, so the clipboard is the file format).
+  // Copy carries the outbound url(#…)/href reference closure in one
+  // <defs> block and declares borrowed xmlns prefixes on the payload
+  // shell; ancestor transforms / inherited presentation / viewport are
+  // deliberately NOT carried (verbatim policy). Cut = copy + remove as
+  // ONE history step labeled "cut"; undo restores the document and the
+  // clipboard keeps the payload (cut → undo → paste = move). Paste is
+  // synchronous over delivered text (`text ?? internal buffer`) and has
+  // a gesture-grade refusal table: non-parseable environment input is a
+  // no-op `[]`, never a throw (insert_fragment keeps strict semantics).
+  // System-clipboard wiring is the DOM surface's native ClipboardEvent
+  // transport (text/plain = the markup itself) plus the optional
+  // ClipboardProvider seam. Full contract:
+  // https://grida.co/docs/wg/feat-svg-editor/clipboard
+  copy(): string | null;              // payload | null on empty selection; no history
+  cut(): string | null;               // one undoable step; buffer secured before delete
+  paste(text?: string): NodeId[];     // inserted roots (selected); [] = refusal
+
+  // duplicate — the clipboard FRD's SECOND extraction operation
+  // (subtree clone): in-document, so NO defs closure and NO xmlns
+  // shell are carried; subtrees and authored ids clone verbatim
+  // (colliding ids resolve first-in-document-order; Tidy dedups).
+  // Each clone lands as its origin's next sibling (paints above it);
+  // selection moves to the clones; ONE history step. Alt-drag
+  // translate-with-clone consumes the same operation. Repeating
+  // offset: duplicate → move the copy → duplicate repeats the
+  // translate delta (an Alt-drag clone commit arms the same memory);
+  // still one undo step, degrades to in-place when the preconditions
+  // don't hold. Contract:
+  // https://grida.co/docs/wg/feat-svg-editor/subtree-clone
+  duplicate(): NodeId[];              // clone ids (selected); [] = refusal
+
   // 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
@@ -643,6 +709,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
@@ -880,6 +948,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-CsKXTaNw.d.ts → dom-BMzX1CXZ.d.ts}

@@ -1,4 +1,4 @@
-import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-BKoo9SPL.js";
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-BSxTUsW_.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;
   /**
@@ -19,6 +48,18 @@ type DomSurfaceOptions = {
    * carte via `handle.gestures.bind(...)`.
    */
   gestures?: boolean;
+  /**
+   * Wire native ClipboardEvent transport — `copy` / `cut` / `paste`
+   * listeners on the owner document, gated by the clipboard attention
+   * discipline. Default `true`. Pass `false` to route ALL clipboard
+   * traffic through the `ClipboardProvider` seam instead (the
+   * configuration under which a host's paste-time screening governs
+   * every path) — see docs/wg/feat-svg-editor/clipboard.md §Transport
+   * "Host control over the native path". Focus management (the container
+   * focusing on pointerdown) stays either way — it is a general canvas
+   * mitigation, not a clipboard feature.
+   */
+  clipboard?: boolean;
   /**
    * Auto-fit the document into the viewport on initial attach. Default
    * `false`. Mirrors Excalidraw's `initialData.scrollToContent`.
@@ -31,6 +72,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 +163,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-DILY80j7.mjs → dom-Bjj9xySE.mjs}

@@ -1,4 +1,4 @@
-import { _ as is_text_input_focused, a as paint, c as hit_shape_svg, d as NudgeDwellWatcher, f as TranslateOrchestrator, g as array_shallow_equal, h as group, i as TOOL_CURSOR, l as RotateOrchestrator, m as transform, n as insertions, o as ResizeOrchestrator, s as resize_pipeline, t as PathModel } from "./model-B2UWgViT.mjs";
+import { S as is_text_input_focused, a as paint, c as hit_shape_svg, d as NudgeDwellWatcher, f as TranslateOrchestrator, h as transform, i as TOOL_CURSOR, l as RotateOrchestrator, m as group, n as insertions, o as ResizeOrchestrator, s as resize_pipeline, t as PathModel, x as array_shallow_equal } from "./model-DMaN5GnH.mjs";
 import cmath from "@grida/cmath";
 import { svg_parse } from "@grida/svg/parse";
 import { SVGShapes } from "@grida/svg/pathdata";
@@ -1005,15 +1005,18 @@ function create_attention_tracker(container) {
 	};
 	container.addEventListener("pointerenter", on_enter);
 	container.addEventListener("pointerleave", on_leave);
-	const is_attended = () => {
+	const is_focus_within = () => {
 		const owner = container.ownerDocument;
-		if (!owner) return pointer_over;
+		if (!owner) return false;
 		const active = owner.activeElement;
-		if (active && active !== owner.body && container.contains(active)) return true;
-		return pointer_over;
+		return !!active && active !== owner.body && container.contains(active);
+	};
+	const is_attended = () => {
+		return is_focus_within() || pointer_over;
 	};
 	return {
 		is_attended,
+		is_focus_within,
 		dispose: () => {
 			container.removeEventListener("pointerenter", on_enter);
 			container.removeEventListener("pointerleave", on_leave);
@@ -1638,6 +1641,48 @@ const IS_MODIFIER_KEY = {
 *  live `<text>` element out from under the about-to-mount text surface. */
 const TEXT_EDIT_PENDING = { __pending: true };
 /**
+* 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.
+*/
+function install_font_load_geometry_bump(source, bump) {
+	if (!source) return () => {};
+	const on_fonts_settled = () => bump();
+	source.addEventListener("loadingdone", on_fonts_settled);
+	let alive = true;
+	const ready = source.ready;
+	if (ready && typeof ready.then === "function") ready.then(() => {
+		if (alive) bump();
+	});
+	return () => {
+		alive = false;
+		source.removeEventListener("loadingdone", on_fonts_settled);
+	};
+}
+/**
 * Attach a DOM surface to a headless editor. Returns a `DomSurfaceHandle`
 * whose `detach()` is the inverse — DOM cleared, listeners removed,
 * gestures uninstalled.
@@ -1663,6 +1708,7 @@ var DomSurface = class DomSurface {
 		this.svg_root = null;
 		this.teardown = [];
 		this.element_index = /* @__PURE__ */ new Map();
+		this.rendered_doc_revision = -1;
 		this.last_pointer = {
 			x: 0,
 			y: 0
@@ -1687,6 +1733,7 @@ var DomSurface = class DomSurface {
 		this.container = options.container;
 		const container = this.container;
 		this.fit_on_attach = options.fit === true;
+		this.clipboard_enabled = options.clipboard !== false;
 		this.attention = create_attention_tracker(container);
 		this.teardown.push(() => this.attention.dispose());
 		if (process.env.NODE_ENV !== "production" && container.children.length > 0) console.warn("@grida/svg-editor: surface container is not empty at attach time. Render chrome (toolbars, layer lists, inspectors) as siblings of the container, not children — otherwise clicks on those children will silently break. See README §Surface.");
@@ -1694,6 +1741,8 @@ var DomSurface = class DomSurface {
 		container.style.overflow = "hidden";
 		container.style.userSelect = "none";
 		container.style.webkitUserSelect = "none";
+		container.tabIndex = -1;
+		container.style.outline = "none";
 		const translate_options = () => {
 			const style = this.editor.style;
 			const zoom = this.camera.zoom || 1;
@@ -1709,7 +1758,9 @@ var DomSurface = class DomSurface {
 			open_preview: (label) => this.editor_internal().history.preview(label),
 			open_snap: (ids) => this.open_snap_session_for(ids),
 			options: translate_options,
-			project_delta: (id, d) => this._geometry_provider?.world_delta_to_local(id, d) ?? d
+			project_delta: (id, d) => this._geometry_provider?.world_delta_to_local(id, d) ?? d,
+			set_selection: (ids) => this.editor.commands.select(ids),
+			on_clone_commit: (record) => this.editor_internal().seed_duplication(record)
 		});
 		const resize_options = () => {
 			const style = this.editor.style;
@@ -1777,6 +1828,7 @@ var DomSurface = class DomSurface {
 			shapeOf: (id) => this.shape_of(id),
 			vectorOf: (id) => this.vector_of(id),
 			onIntent: (i) => this.commit_intent(i),
+			onTap: (t) => this.handle_tap(t),
 			style: {
 				chromeColor: editor.style.chrome_color,
 				showRotationHandles: true
@@ -1836,7 +1888,7 @@ var DomSurface = class DomSurface {
 			this.current_tool = editor.state.tool;
 			this.hud.setVectorSelectionMode(this.current_tool.type === "lasso" ? "lasso" : "marquee");
 			this.hud.setVectorBendMode(this.current_tool.type === "bend" ? "always" : "auto");
-			this.render();
+			this.flush_dom();
 			this.sync_surface_selection();
 			this.hud.setPixelGrid({
 				enabled: editor.style.pixel_grid,
@@ -1883,6 +1935,8 @@ var DomSurface = class DomSurface {
 			win.addEventListener("resize", fn);
 			this.teardown.push(() => win.removeEventListener("resize", fn));
 		}
+		const detach_font_listener = install_font_load_geometry_bump(options.font_load_source ?? container.ownerDocument.fonts ?? null, () => editor._internal.bump_geometry());
+		this.teardown.push(detach_font_listener);
 		this.wire_events();
 		const internal = editor._internal;
 		this.editor_hover_internal = internal;
@@ -1890,12 +1944,14 @@ var DomSurface = class DomSurface {
 		this.teardown.push(() => internal.set_content_edit_driver(null));
 		internal.set_computed_resolver({
 			computed_property: (id, name) => {
+				this.flush_dom();
 				const el = this.element_index.get(id);
 				if (!el) return null;
 				const value = getComputedStyle(el).getPropertyValue(name);
 				return value === "" ? null : value;
 			},
 			computed_paint: (id, channel) => {
+				this.flush_dom();
 				const el = this.element_index.get(id);
 				if (!el) return null;
 				const computed = getComputedStyle(el).getPropertyValue(channel);
@@ -1912,7 +1968,8 @@ var DomSurface = class DomSurface {
 			root: () => this.svg_root,
 			camera: () => this.camera,
 			container: () => this.container,
-			pick_at_world: (p, allow_root) => this._pick_node_at_world(p, allow_root)
+			pick_at_world: (p, allow_root) => this._pick_node_at_world(p, allow_root),
+			flush: () => this.flush_dom()
 		}), {
 			subscribe_structure: (cb) => editor.subscribe_with_selector((s) => s.structure_version, () => cb()),
 			subscribe_geometry: (cb) => editor.subscribe_geometry(cb)
@@ -2094,6 +2151,25 @@ var DomSurface = class DomSurface {
 	detach_gestures() {
 		this.gestures._dispose();
 	}
+	/**
+	* Bring the live DOM up to date with the doc IR iff it is stale.
+	*
+	* Staleness contract: anything that reads the LIVE DOM as a proxy for
+	* document state — the geometry driver (`getBBox` / `getCTM`), the
+	* computed-style resolver — MUST call this first. Doc listeners (the
+	* geometry channel, editor `subscribe`) fire synchronously inside the
+	* mutation, BEFORE the surface's render listener has projected the new
+	* attrs into the DOM; a read in that window returns the PREVIOUS
+	* geometry, and through `MemoizedGeometryProvider` it would be cached as
+	* if current — every later consumer (align, resize_to, snap) then plans
+	* against one-mutation-stale bounds. Same model as CSS layout: reading
+	* `offsetWidth` flushes pending layout; reading `bounds_of` flushes the
+	* pending render.
+	*/
+	flush_dom() {
+		if (this.rendered_doc_revision === this.editor._internal.doc.revision) return;
+		this.render();
+	}
 	render() {
 		if (this.text_edit) return;
 		const owner_doc = this.container.ownerDocument;
@@ -2120,6 +2196,7 @@ var DomSurface = class DomSurface {
 			for (let c = el.firstElementChild; c; c = c.nextElementSibling) if (c instanceof SVGElement) tag_walk(c);
 		};
 		tag_walk(new_svg);
+		this.rendered_doc_revision = doc.revision;
 	}
 	sync_canvas_size() {
 		const cr = this.container.getBoundingClientRect();
@@ -2714,6 +2791,60 @@ var DomSurface = class DomSurface {
 		});
 		on(win, "blur", () => this.sync_modifiers(null));
 		on(this.container, "contextmenu", (e) => e.preventDefault());
+		if (this.clipboard_enabled) {
+			on(owner_doc, "copy", (e) => this.on_copy_or_cut(e, "copy"));
+			on(owner_doc, "cut", (e) => this.on_copy_or_cut(e, "cut"));
+			on(owner_doc, "paste", (e) => this.on_paste(e));
+		}
+	}
+	/**
+	* Gate for claiming a native clipboard gesture. Deliberately STRICTER
+	* than the keyboard attention gate: focus-based only — pointer-over is
+	* a sufficient signal for a keystroke (worst case: a stolen scroll) but
+	* not for clipboard (worst case: destroying what the user believed they
+	* copied, or routing a paste meant for a host text field into the
+	* document). A user with text selected in a sibling panel and the
+	* pointer idly over the canvas must get their text copy.
+	*/
+	claims_clipboard(kind) {
+		if (this.text_edit) return false;
+		if (this.editor.state.mode !== "select") return false;
+		if (!this.attention.is_focus_within()) return false;
+		if (is_text_input_focused()) return false;
+		if (kind !== "paste") {
+			const sel = this.container.ownerDocument.getSelection();
+			if (sel && !sel.isCollapsed) return false;
+		}
+		return true;
+	}
+	/**
+	* Act-then-claim: an empty selection returns without `preventDefault()`,
+	* leaving the browser default (and the OS clipboard) untouched. The
+	* buffer-only `_internal.clipboard` variants are used here — the event's
+	* DataTransfer is this gesture's ONE external channel (the public
+	* commands would additionally write the provider; one gesture, one
+	* external write — FRD §Transport).
+	*/
+	on_copy_or_cut(e, kind) {
+		if (!this.claims_clipboard(kind)) return;
+		if (!e.clipboardData) return;
+		const internal = this.editor_internal();
+		const payload = kind === "copy" ? internal.clipboard.copy() : internal.clipboard.cut();
+		if (payload === null) return;
+		e.clipboardData.setData("text/plain", payload);
+		e.preventDefault();
+	}
+	/**
+	* Claim-then-act (mirrors the keydown claim doctrine: swallow when the
+	* gesture is aimed at the editor, not just when a handler consumed):
+	* a refused paste — junk text — still claims; the suppressed default is
+	* a no-op on a div anyway.
+	*/
+	on_paste(e) {
+		if (!this.claims_clipboard("paste")) return;
+		e.preventDefault();
+		const text = e.clipboardData?.getData("text/plain");
+		if (text) this.editor.commands.paste(text);
 	}
 	/**
 	* Master signal for modifier-driven UX consumers (measurement, future
@@ -2735,7 +2866,7 @@ var DomSurface = class DomSurface {
 			kind: "modifiers",
 			mods: next
 		});
-		if (prev.shift !== next.shift && this.translate_orchestrator.has_active_session()) this.translate_orchestrator.redrive_modifiers(this.current_translate_modifiers());
+		if ((prev.shift !== next.shift || prev.alt !== next.alt) && this.translate_orchestrator.has_active_session()) this.translate_orchestrator.redrive_modifiers(this.current_translate_modifiers());
 		if (prev.shift !== next.shift && this.resize_orchestrator.has_active_session()) this.resize_orchestrator.redrive_modifiers(this.current_resize_modifiers());
 		if (prev.shift !== next.shift && this.rotate_orchestrator.has_active_session()) this.rotate_orchestrator.redrive_modifiers(this.current_rotate_modifiers());
 		this.redraw();
@@ -2756,6 +2887,7 @@ var DomSurface = class DomSurface {
 			} else if (kind === "pointer_up") this.text_edit.pointerUp();
 			return;
 		}
+		if (kind === "pointer_down") this.container.focus({ preventScroll: true });
 		const cr = this.container.getBoundingClientRect();
 		const x = e.clientX - cr.left;
 		const y = e.clientY - cr.top;
@@ -2966,6 +3098,26 @@ var DomSurface = class DomSurface {
 		if (this.editor.keymap.claims(e)) e.preventDefault();
 		this.editor.keymap.dispatch(e);
 	}
+	/**
+	* Re-express a HUD tap as an editor {@link PickEvent} and fan it out on the
+	* editor's pick channel. The HUD already resolved everything that matters —
+	* the pointer-down point, the hit node, and click-vs-drag — so this is a
+	* pure translation (HUD `[x, y]` tuple → editor `{ x, y }` doc-space point)
+	* with NO re-hit-testing. Taking the hit from the HUD (not a fresh
+	* `node_at_point`) guarantees the pick and the selection it accompanies can
+	* never disagree. Observe-only: this mutates no editor state.
+	*/
+	handle_tap(tap) {
+		this.editor._internal.push_pick({
+			point: {
+				x: tap.point[0],
+				y: tap.point[1]
+			},
+			node_id: tap.hit,
+			button: tap.button,
+			mods: tap.mods
+		});
+	}
 	commit_intent(intent) {
 		switch (intent.kind) {
 			case "select":
@@ -3052,13 +3204,15 @@ var DomSurface = class DomSurface {
 		});
 		if (intent.phase === "commit") this.request_redraw();
 	}
-	/** Snapshot of HUD modifier state mapped to pipeline `TranslateModifiers`.
+	/** Snapshot of HUD modifier state mapped to the orchestrator's `GestureModifiers`.
 	*  Pull-at-consume: HUD is the canonical store (see `sync_modifiers`),
 	*  read live so mid-drag Shift press/release reflects on the next pass. */
 	current_translate_modifiers() {
+		const mods = this.hud.modifiers();
 		return {
-			axis_lock: this.hud.modifiers().shift ? "by_dominance" : "off",
-			force_disable_snap: false
+			axis_lock: mods.shift ? "by_dominance" : "off",
+			force_disable_snap: false,
+			clone: mods.alt
 		};
 	}
 	/** Snapshot of HUD modifier state mapped to `ResizeModifiers`. Same
@@ -4397,6 +4551,7 @@ var SvgGeometryDriver = class {
 		this.accessors = accessors;
 	}
 	bounds_of(id) {
+		this.accessors.flush();
 		const el = this.accessors.element_for(id);
 		if (!el) return null;
 		if (el instanceof SVGSVGElement) return svg_viewport_bounds(el);
@@ -4448,6 +4603,7 @@ var SvgGeometryDriver = class {
 		return out;
 	}
 	nodes_in_rect(rect) {
+		this.accessors.flush();
 		const root = this.accessors.root();
 		if (!root) return [];
 		const hits = [];
@@ -4460,6 +4616,7 @@ var SvgGeometryDriver = class {
 		return hits;
 	}
 	node_at_point(p) {
+		this.accessors.flush();
 		return this.accessors.pick_at_world(p, true);
 	}
 	/** World→local delta projection. The frame an element's position is
@@ -4475,6 +4632,7 @@ var SvgGeometryDriver = class {
 	*  the local delta. Identity (→ delta unchanged) for flat frames,
 	*  top-level nodes, and any degenerate / unavailable matrix. */
 	world_delta_to_local(id, delta) {
+		this.accessors.flush();
 		const parent = this.accessors.element_for(id)?.parentNode;
 		const root = this.accessors.root();
 		if (!(parent instanceof SVGGraphicsElement) || !root) return delta;
@@ -4515,4 +4673,4 @@ var SvgHitShapeDriver = class {
 	}
 };
 //#endregion
-export { Gestures as a, Camera as c, project_point_through_ctm as i, inverse_project_rect as n, DEFAULT_SNAP_OPTIONS as o, project_delta_inverse_ctm as r, MemoizedGeometryProvider as s, attach_dom_surface as t };
+export { project_point_through_ctm as a, MemoizedGeometryProvider as c, project_delta_inverse_ctm as i, Camera as l, install_font_load_geometry_bump as n, Gestures as o, inverse_project_rect as r, DEFAULT_SNAP_OPTIONS as s, attach_dom_surface as t };