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

package/dist/{editor-DtuRIs-Q.mjs → editor-CvWpD5mu.mjs}

@@ -1,8 +1,9 @@
-import { A as is_text_input_focused, D as parse_transform_list, E as emit_transform_list, _ as apply_translate, a as DEFAULT_STYLE, c as serialize_paint, g as apply_rotate, h as apply_resize, k as plan_group, m as STAGES_NUDGE, o as TOOL_CURSOR, p as prepare_translate_rpc, r as default_paint_attrs, s as parse_paint, u as prepare_rotate_rpc, v as capture_resize_baseline, x as is_resizable, y as capture_translate_baseline } from "./insertions-Okcuo-Ck.mjs";
+import { _ as is_text_input_focused, a as paint, g as array_shallow_equal, h as group, i as TOOL_CURSOR, m as transform, n as insertions, p as translate_pipeline, r as DEFAULT_STYLE, s as resize_pipeline, u as rotate_pipeline } from "./model-B2UWgViT.mjs";
 import { HistoryImpl } from "@grida/history";
 import { KeyCode, M, chunkKey, eventToChunk, getKeyboardOS, kb, keybindingsToKeyCodes } from "@grida/keybinding";
 import cmath from "@grida/cmath";
 import { XLINK_NS, encode_attr_value, encode_text, parse_svg } from "@grida/svg/parser";
+import { svg_parse } from "@grida/svg/parse";
 //#region src/commands/registry.ts
 var CommandRegistry = class {
 	constructor() {
@@ -118,6 +119,7 @@ function registerDefaultCommands(reg, editor) {
 		if (editor.state.mode !== "select") return false;
 		return editor.commands.align(args);
 	});
+	reg.register("content.enter", () => editor.enter_content_edit());
 	reg.register("hierarchy.enter", () => {
 		if (editor.state.selection.length !== 1) return false;
 		const id = editor.state.selection[0];
@@ -142,8 +144,10 @@ function registerDefaultCommands(reg, editor) {
 		return true;
 	});
 	reg.register(TOOL_SET, (args) => {
-		if (editor.state.mode !== "select") return false;
-		editor.set_tool(args);
+		const next = args;
+		const required_mode = next.type === "lasso" || next.type === "bend" ? "edit-content" : next.type === "insert" || next.type === "insert-text" ? "select" : null;
+		if (required_mode !== null && editor.state.mode !== required_mode) return false;
+		editor.set_tool(next);
 		return true;
 	});
 }
@@ -163,12 +167,6 @@ function registerDefaultCommands(reg, editor) {
 * measurement). That stays on the HUD modifiers channel. The keymap
 * only sees Mod+D-shape chords.
 */
-/** Modifiers that, when held, allow a binding to fire even inside a text input. */
-const TEXT_INPUT_SAFE_MODS = new Set([
-	KeyCode.Meta,
-	KeyCode.Ctrl,
-	KeyCode.Alt
-]);
 var Keymap = class {
 	constructor(commands, platformGetter = getKeyboardOS) {
 		this.commands = commands;
@@ -234,15 +232,16 @@ var Keymap = class {
 	* bar even when the binding's handler rejects.
 	*
 	* Pure read; runs no handlers, no side effects. Honors the same
-	* text-input-focused guard `dispatch` uses, so a typing user's
-	* keystroke isn't "claimed" by an unrelated unmodified key.
+	* form-element focus guard `dispatch` uses, so a typing user's
+	* keystroke isn't "claimed" — and the browser's native text-editing
+	* default (Cmd+A select all, Cmd+Z undo, etc.) wins.
 	*/
 	claims(event) {
 		const chunk = eventToChunk(event);
 		if (chunk.keys.length === 0) return false;
 		const list = this.buckets.get(chunkKey(chunk));
 		if (!list || list.length === 0) return false;
-		if (is_text_input_focused() && !this.has_safe_mod(chunk.mods)) return false;
+		if (is_text_input_focused()) return list.some(({ binding }) => binding.allowInFormElement === true);
 		return true;
 	}
 	/**
@@ -250,6 +249,12 @@ var Keymap = class {
 	* order. Returns `true` on the first handler that consumes; returns
 	* `false` if nothing matched or all matches fell through.
 	*
+	* **Form-element focus guard.** When a text input is focused
+	* (`<input>`, `<textarea>`, contentEditable), bindings are suppressed
+	* by default so the platform's native shortcuts (Cmd+A, Cmd+Z, Cmd+C,
+	* arrow nav, …) are preserved. A binding can opt out of this guard
+	* with `allowInFormElement: true` — see `KeymapBinding`.
+	*
 	* `dispatch` is browser-agnostic: it does NOT call `preventDefault()`
 	* or touch the event in any way. The host decides what to do with the
 	* platform default — typically `if (keymap.claims(e)) e.preventDefault()`,
@@ -264,7 +269,7 @@ var Keymap = class {
 		if (!list || list.length === 0) return false;
 		const text_focused = is_text_input_focused();
 		for (const { binding } of list) {
-			if (text_focused && !this.has_safe_mod(chunk.mods)) continue;
+			if (text_focused && binding.allowInFormElement !== true) continue;
 			if (this.commands.invoke(binding.command, binding.args)) return true;
 		}
 		return false;
@@ -284,10 +289,6 @@ var Keymap = class {
 		}
 		return out;
 	}
-	has_safe_mod(mods) {
-		for (const m of mods) if (TEXT_INPUT_SAFE_MODS.has(m)) return true;
-		return false;
-	}
 };
 function compareEntries(a, b) {
 	const pa = a.binding.priority ?? 0;
@@ -382,6 +383,10 @@ const DEFAULT_BINDINGS = [
 		command: "selection.align",
 		args: "vertical_centers"
 	},
+	{
+		keybinding: kb(KeyCode.Enter),
+		command: "content.enter"
+	},
 	{
 		keybinding: kb(KeyCode.Enter),
 		command: "hierarchy.enter"
@@ -483,6 +488,16 @@ const DEFAULT_BINDINGS = [
 			tag: "line"
 		}
 	},
+	{
+		keybinding: kb(KeyCode.KeyT),
+		command: TOOL_SET,
+		args: { type: "insert-text" }
+	},
+	{
+		keybinding: kb(KeyCode.KeyQ),
+		command: TOOL_SET,
+		args: { type: "lasso" }
+	},
 	{
 		keybinding: kb(KeyCode.BracketRight),
 		command: "reorder",
@@ -509,14 +524,6 @@ function applyDefaultBindings(keymap) {
 	for (const b of DEFAULT_BINDINGS) keymap.bind(b);
 }
 //#endregion
-//#region src/util/equal.ts
-function array_shallow_equal(a, b) {
-	if (a === b) return true;
-	if (a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
-	return true;
-}
-//#endregion
 //#region src/core/defs.ts
 var GradientsRegistry = class {
 	constructor(doc) {
@@ -749,6 +756,55 @@ function create_defs(doc) {
 }
 //#endregion
 //#region src/core/document.ts
+/** The native vector tags `retype_to_path` can re-type, keyed by tag → the
+*  native geometry attributes it consumes (so no orphaned geometry attr
+*  survives on the resulting `<path>`). Covers the geometry primitives
+*  (rect / circle / ellipse — always re-typed) and the vertex tags (line /
+*  polyline / polygon — re-typed only when an edit escapes their native
+*  form). */
+const RETYPABLE_GEOMETRY_ATTRS = {
+	line: new Set([
+		"x1",
+		"y1",
+		"x2",
+		"y2"
+	]),
+	polyline: new Set(["points"]),
+	polygon: new Set(["points"]),
+	rect: new Set([
+		"x",
+		"y",
+		"width",
+		"height",
+		"rx",
+		"ry"
+	]),
+	circle: new Set([
+		"cx",
+		"cy",
+		"r"
+	]),
+	ellipse: new Set([
+		"cx",
+		"cy",
+		"rx",
+		"ry"
+	])
+};
+/**
+* Parse a single SVG length attribute as a plain user-unit number. Returns
+* `null` for absent, non-finite, or unit/percentage values (`50%`, `5px`,
+* `5em`) — those are an out-of-scope geometry gap, and refusing them here
+* means the editor never offers a promotion it cannot perform faithfully.
+*/
+function parse_user_unit(raw) {
+	if (raw === null) return null;
+	const s = raw.trim();
+	if (s === "") return null;
+	if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) return null;
+	const n = Number(s);
+	return Number.isFinite(n) ? n : null;
+}
 /**
 * Attribute names whose writes can shift a node's rendered bounds.
 * Membership drives `_geometry_version` bumps in `set_attr`. Only
@@ -791,11 +847,14 @@ const GEOMETRY_ATTRS = new Set([
 	"marker-mid",
 	"marker-end"
 ]);
+/** `transform:` CSS property at the start of a declaration list or after `;`. */
+const CSS_TRANSFORM_PROPERTY = /(?:^|;)\s*transform\s*:/i;
 var SvgDocument = class SvgDocument {
 	constructor(svg) {
 		this.listeners = /* @__PURE__ */ new Set();
 		this._structure_version = 0;
 		this._geometry_version = 0;
+		if (typeof svg !== "string") throw new TypeError(`new SvgDocument(svg) requires a string source, got ${svg === null ? "null" : typeof svg}`);
 		this.source = svg;
 		const parsed = parse_svg(svg);
 		this.original = parsed;
@@ -821,6 +880,7 @@ var SvgDocument = class SvgDocument {
 	}
 	/** Replace document with new svg source (clears edits + history-owned state). */
 	load(svg) {
+		if (typeof svg !== "string") throw new TypeError(`SvgDocument.load(svg) requires a string source, got ${svg === null ? "null" : typeof svg}`);
 		this.source = svg;
 		const parsed = parse_svg(svg);
 		this.original = parsed;
@@ -1058,6 +1118,292 @@ var SvgDocument = class SvgDocument {
 		for (const c of n.children) if (this.nodes.get(c)?.kind !== "text") return false;
 		return true;
 	}
+	/**
+	* Returns a tag-discriminated snapshot of the authored geometry attrs
+	* if this node is eligible for vector (vertex) editing — else `null`.
+	*
+	* Eligibility:
+	*   - `<path>`     — requires non-empty `d`.
+	*   - `<line>`     — requires two distinct finite user-unit endpoints.
+	*   - `<polyline>` — requires `points` parseable to ≥ 2 vertices.
+	*   - `<polygon>`  — same as polyline.
+	*   - `<rect>`     — requires finite user-unit `width`/`height` > 0.
+	*   - `<circle>`   — requires finite user-unit `r` > 0.
+	*   - `<ellipse>`  — requires finite user-unit `rx`/`ry` > 0.
+	*
+	* The vertex tags (`line` / `polyline` / `polygon`) write edits back to
+	* their native attributes while the geometry stays expressible there; an
+	* edit that escapes the native form (a curve, or a topology change that
+	* leaves the canonical chain) re-types the element to `<path>`. The
+	* geometry primitives (`rect` / `circle` / `ellipse`) have no native
+	* vector form, so any vector edit re-types them. In all cases the native
+	* tag is preserved byte-for-byte until the first re-typing edit commits
+	* (see `retype_to_path`). Design:
+	* `docs/wg/feat-svg-editor/promote-to-path.md`.
+	*
+	* Geometry that is not a plain user-unit number (`%`, `px`, `em`, …) is
+	* an out-of-scope gap, so such an element returns `null` rather than
+	* advertising an edit the editor cannot perform faithfully.
+	*
+	* Rejects `<image>` / `<use>` (raster / reference bounding boxes, no
+	* editable outline).
+	*/
+	/**
+	* Parse an optional SVG geometry coordinate (`x`/`y`, `cx`/`cy`, the line
+	* endpoints). An **absent** attribute takes the SVG default (`0`); a
+	* **present** attribute that is not a plain user-unit number (`%`, `px`,
+	* `em`, …) is out of scope and yields `null` so the caller refuses the
+	* element — the same gate required attrs (width / radius) already apply.
+	*
+	* The absent-vs-present distinction is the point: a bare `?? 0` would
+	* silently coerce an authored `x1="5px"` to `0`, then the first native
+	* writeback would overwrite that authored value. Refusing keeps the
+	* editor from misrepresenting geometry it cannot read faithfully.
+	*/
+	optional_user_unit_coord(id, name) {
+		const raw = this.get_attr(id, name);
+		if (raw === null) return 0;
+		return parse_user_unit(raw);
+	}
+	is_vector_edit_target(id) {
+		const n = this.nodes.get(id);
+		if (!n || n.kind !== "element") return null;
+		if (RETYPABLE_GEOMETRY_ATTRS[n.local] && n.attrs.some((a) => a.prefix === null && a.ns === null && a.local === "d")) return null;
+		switch (n.local) {
+			case "path": {
+				const d = this.get_attr(id, "d");
+				if (d === null || d.trim().length === 0) return null;
+				return {
+					kind: "path",
+					d
+				};
+			}
+			case "line": {
+				const x1 = this.optional_user_unit_coord(id, "x1");
+				const y1 = this.optional_user_unit_coord(id, "y1");
+				const x2 = this.optional_user_unit_coord(id, "x2");
+				const y2 = this.optional_user_unit_coord(id, "y2");
+				if (x1 === null || y1 === null || x2 === null || y2 === null) return null;
+				if (x1 === x2 && y1 === y2) return null;
+				return {
+					kind: "line",
+					x1,
+					y1,
+					x2,
+					y2
+				};
+			}
+			case "polyline":
+			case "polygon": {
+				const raw = this.get_attr(id, "points") ?? "";
+				const parsed = svg_parse.parse_points(raw);
+				if (parsed.length < 2) return null;
+				const points = parsed.map((p) => [p.x, p.y]);
+				return n.local === "polyline" ? {
+					kind: "polyline",
+					points
+				} : {
+					kind: "polygon",
+					points
+				};
+			}
+			case "rect": {
+				const x = this.optional_user_unit_coord(id, "x");
+				const y = this.optional_user_unit_coord(id, "y");
+				if (x === null || y === null) return null;
+				const width = parse_user_unit(this.get_attr(id, "width"));
+				const height = parse_user_unit(this.get_attr(id, "height"));
+				if (width === null || height === null) return null;
+				if (width <= 0 || height <= 0) return null;
+				const rx_attr = this.get_attr(id, "rx");
+				const ry_attr = this.get_attr(id, "ry");
+				const rx_parsed = rx_attr === null ? null : parse_user_unit(rx_attr);
+				const ry_parsed = ry_attr === null ? null : parse_user_unit(ry_attr);
+				if (rx_attr !== null && rx_parsed === null) return null;
+				if (ry_attr !== null && ry_parsed === null) return null;
+				let rx = rx_parsed ?? ry_parsed ?? 0;
+				let ry = ry_parsed ?? rx_parsed ?? 0;
+				rx = Math.max(0, Math.min(rx, width / 2));
+				ry = Math.max(0, Math.min(ry, height / 2));
+				return {
+					kind: "rect",
+					x,
+					y,
+					width,
+					height,
+					rx,
+					ry
+				};
+			}
+			case "circle": {
+				const cx = this.optional_user_unit_coord(id, "cx");
+				const cy = this.optional_user_unit_coord(id, "cy");
+				if (cx === null || cy === null) return null;
+				const r = parse_user_unit(this.get_attr(id, "r"));
+				if (r === null || r <= 0) return null;
+				return {
+					kind: "circle",
+					cx,
+					cy,
+					r
+				};
+			}
+			case "ellipse": {
+				const cx = this.optional_user_unit_coord(id, "cx");
+				const cy = this.optional_user_unit_coord(id, "cy");
+				if (cx === null || cy === null) return null;
+				const rx = parse_user_unit(this.get_attr(id, "rx"));
+				const ry = parse_user_unit(this.get_attr(id, "ry"));
+				if (rx === null || ry === null) return null;
+				if (rx <= 0 || ry <= 0) return null;
+				return {
+					kind: "ellipse",
+					cx,
+					cy,
+					rx,
+					ry
+				};
+			}
+			default: return null;
+		}
+	}
+	/**
+	* Re-type a native vector element (`<line>` / `<polyline>` / `<polygon>` /
+	* `<rect>` / `<circle>` / `<ellipse>`) into a `<path>` in place, consuming
+	* its native geometry attributes and setting `d`. A structural mutation:
+	* this layer executes the re-type; it does not decide when one is
+	* warranted.
+	*
+	* Idempotent: returns `null` if `id` is not currently one of those tags
+	* (so it is safe to call repeatedly — once re-typed, e.g. already a
+	* `<path>`, further calls are no-ops). Otherwise mutates the node and
+	* returns an opaque {@link RetypeRecord} reversal token.
+	*
+	* Identity, children, `self_closing`, non-geometry attributes, and all
+	* source trivia are preserved unchanged — only the tag and the geometry
+	* attributes move. Pass the token to {@link revert_retype} to restore
+	* the original primitive byte-for-byte.
+	*
+	* (see test/svg-editor-vector-promote-to-path.md)
+	*/
+	retype_to_path(id, d) {
+		const n = this.nodes.get(id);
+		if (!n || n.kind !== "element") return null;
+		const geom = RETYPABLE_GEOMETRY_ATTRS[n.local];
+		if (!geom) return null;
+		const prev_local = n.local;
+		const prev_raw_tag = n.raw_tag;
+		const removed = [];
+		for (let i = n.attrs.length - 1; i >= 0; i--) {
+			const a = n.attrs[i];
+			if (a.prefix === null && a.ns === null && geom.has(a.local)) {
+				removed.push({
+					index: i,
+					token: a
+				});
+				n.attrs.splice(i, 1);
+			}
+		}
+		removed.reverse();
+		n.local = "path";
+		n.raw_tag = n.prefix ? `${n.prefix}:path` : "path";
+		n.attrs.push({
+			raw_name: "d",
+			prefix: null,
+			local: "d",
+			ns: null,
+			value: d,
+			pre: " ",
+			eq_trivia: "",
+			quote: "\""
+		});
+		let added_fill_none = false;
+		if (prev_local === "line" && this.get_attr(id, "fill") === null && this.get_style(id, "fill") === null) {
+			n.attrs.push({
+				raw_name: "fill",
+				prefix: null,
+				local: "fill",
+				ns: null,
+				value: "none",
+				pre: " ",
+				eq_trivia: "",
+				quote: "\""
+			});
+			added_fill_none = true;
+		}
+		this._structure_version++;
+		this._geometry_version++;
+		this.emit();
+		return {
+			prev_local,
+			prev_raw_tag,
+			removed,
+			added_fill_none
+		};
+	}
+	/**
+	* Reverse a {@link retype_to_path}: restore the original tag, remove the
+	* `d` attribute the promotion added, and splice the captured geometry
+	* attribute tokens back at their original positions (preserving their
+	* trivia, so a later `serialize()` is byte-equal to the pre-promotion
+	* source).
+	*/
+	revert_retype(id, token) {
+		const n = this.nodes.get(id);
+		if (!n || n.kind !== "element") return;
+		for (let i = n.attrs.length - 1; i >= 0; i--) {
+			const a = n.attrs[i];
+			if (a.prefix === null && a.ns === null && a.local === "d") {
+				n.attrs.splice(i, 1);
+				break;
+			}
+		}
+		if (token.added_fill_none) for (let i = n.attrs.length - 1; i >= 0; i--) {
+			const a = n.attrs[i];
+			if (a.prefix === null && a.ns === null && a.local === "fill") {
+				n.attrs.splice(i, 1);
+				break;
+			}
+		}
+		n.local = token.prev_local;
+		n.raw_tag = token.prev_raw_tag;
+		for (const { index, token: t } of token.removed) n.attrs.splice(index, 0, t);
+		this._structure_version++;
+		this._geometry_version++;
+		this.emit();
+	}
+	/**
+	* True iff this `<text>` / `<tspan>` carries a non-empty `rotate=""`
+	* per-glyph attribute (which conflicts with element-level rotation).
+	*/
+	has_glyph_rotate(id) {
+		const tag = this.tag_of(id);
+		if (tag !== "text" && tag !== "tspan") return false;
+		const value = this.get_attr(id, "rotate");
+		if (value === null) return false;
+		return value.trim() !== "";
+	}
+	/**
+	* True iff this element's inline `style=""` declares a `transform:`
+	* CSS property (which would shadow the editor's `transform=` writes).
+	*/
+	has_inline_css_transform(id) {
+		const style = this.get_attr(id, "style");
+		if (!style) return false;
+		return CSS_TRANSFORM_PROPERTY.test(style);
+	}
+	/**
+	* True iff this element has a direct `<animateTransform>` child
+	* (which produces a time-varying transform invisible to attribute writes).
+	* Only direct children are checked — nested cases attach to the nearer ancestor.
+	*/
+	has_animate_transform_child(id) {
+		for (const c of this.children_of(id)) {
+			const n = this.nodes.get(c);
+			if (n?.kind === "element" && n.local === "animateTransform") return true;
+		}
+		return false;
+	}
 	text_of(id) {
 		const n = this.nodes.get(id);
 		if (!n || n.kind !== "element") return "";
@@ -1149,6 +1495,37 @@ var SvgDocument = class SvgDocument {
 		for (const e of this.epilog) out += this.emit_node(e);
 		return out;
 	}
+	/**
+	* Serialize a single element's subtree as an SVG **fragment**, using the
+	* same trivia-preserving rules as {@link serialize} (attribute order,
+	* quote style, whitespace, comments — emitted exactly as authored).
+	*
+	* This is NOT {@link serialize} scoped to a node — it is a deliberately
+	* weaker output (sdk-design D3, asymmetric outputs stay separate):
+	*
+	*   - `serialize()` emits the whole document and carries the P1
+	*     whole-document 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 — 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, a non-element node, or a node detached from
+	* the live tree: the contract is "the markup for a selected element,"
+	* selections are always live elements, and a string return of `""` for a
+	* bad id would hide consumer bugs. The detached case matters because
+	* `remove()` keeps the node in the id map for undo — a stale id from a
+	* removed node would otherwise serialize content no longer in the
+	* document, silently feeding a consumer deleted markup.
+	*/
+	serialize_node(id) {
+		const n = this.nodes.get(id);
+		if (!n) throw new Error(`serialize_node: unknown node id ${JSON.stringify(id)}`);
+		if (n.kind !== "element") throw new Error(`serialize_node: node ${JSON.stringify(id)} is a ${n.kind} node, not an element`);
+		if (!this.contains(this.root, id)) throw new Error(`serialize_node: node ${JSON.stringify(id)} is detached from the current document`);
+		return this.emit_node(n);
+	}
 	emit_node(n) {
 		switch (n.kind) {
 			case "text": return encode_text(n.value);
@@ -1248,153 +1625,162 @@ function delta_for(bbox, target, direction) {
 }
 //#endregion
 //#region src/core/properties.ts
-/** SVG properties that inherit per SVG 2 §6 (subset; the common ones). */
-const INHERITED = new Set([
-	"color",
-	"cursor",
-	"direction",
-	"fill",
-	"fill-opacity",
-	"fill-rule",
-	"font",
-	"font-family",
-	"font-size",
-	"font-style",
-	"font-variant",
-	"font-weight",
-	"letter-spacing",
-	"marker",
-	"marker-end",
-	"marker-mid",
-	"marker-start",
-	"paint-order",
-	"pointer-events",
-	"shape-rendering",
-	"stroke",
-	"stroke-dasharray",
-	"stroke-dashoffset",
-	"stroke-linecap",
-	"stroke-linejoin",
-	"stroke-miterlimit",
-	"stroke-opacity",
-	"stroke-width",
-	"text-anchor",
-	"text-rendering",
-	"visibility",
-	"word-spacing",
-	"writing-mode"
-]);
-/** Initial values for known properties (subset). */
-const INITIAL = {
-	fill: "black",
-	stroke: "none",
-	"fill-opacity": "1",
-	"stroke-opacity": "1",
-	"stroke-width": "1",
-	opacity: "1",
-	visibility: "visible",
-	display: "inline"
-};
-/**
-* Resolve a property's declared value and its provenance for a single node.
-*
-* The cascade engine here covers what the README says is in scope:
-* presentation attributes + inline style + parent inheritance + initial.
-* `<style>` block matching is deferred.
-*/
-function resolve_declared(doc, id, property) {
-	const inline = doc.get_style(id, property);
-	if (inline !== null && inline !== "") return {
-		declared: inline,
-		provenance: {
-			origin: "author",
-			carrier: "inline_style"
-		}
+let properties;
+(function(_properties) {
+	/** SVG properties that inherit per SVG 2 §6 (subset; the common ones). */
+	const INHERITED = new Set([
+		"color",
+		"cursor",
+		"direction",
+		"fill",
+		"fill-opacity",
+		"fill-rule",
+		"font",
+		"font-family",
+		"font-size",
+		"font-style",
+		"font-variant",
+		"font-weight",
+		"letter-spacing",
+		"marker",
+		"marker-end",
+		"marker-mid",
+		"marker-start",
+		"paint-order",
+		"pointer-events",
+		"shape-rendering",
+		"stroke",
+		"stroke-dasharray",
+		"stroke-dashoffset",
+		"stroke-linecap",
+		"stroke-linejoin",
+		"stroke-miterlimit",
+		"stroke-opacity",
+		"stroke-width",
+		"text-anchor",
+		"text-rendering",
+		"visibility",
+		"word-spacing",
+		"writing-mode"
+	]);
+	/** Initial values for known properties (subset). */
+	const INITIAL = {
+		fill: "black",
+		stroke: "none",
+		"fill-opacity": "1",
+		"stroke-opacity": "1",
+		"stroke-width": "1",
+		opacity: "1",
+		visibility: "visible",
+		display: "inline"
 	};
-	const attr = doc.get_attr(id, property);
-	if (attr !== null && attr !== "") return {
-		declared: attr,
-		provenance: {
-			origin: "author",
-			carrier: "presentation_attribute"
-		}
-	};
-	if (INHERITED.has(property)) {
-		const parent = doc.parent_of(id);
-		if (parent !== null && doc.is_element(parent)) {
-			const r = resolve_declared(doc, parent, property);
-			if (r.declared !== null) return {
-				declared: r.declared,
-				provenance: {
-					origin: "author",
-					carrier: "inherited"
-				}
-			};
+	function resolve_declared(doc, id, property) {
+		const inline = doc.get_style(id, property);
+		if (inline !== null && inline !== "") return {
+			declared: inline,
+			provenance: {
+				origin: "author",
+				carrier: "inline_style"
+			}
+		};
+		const attr = doc.get_attr(id, property);
+		if (attr !== null && attr !== "") return {
+			declared: attr,
+			provenance: {
+				origin: "author",
+				carrier: "presentation_attribute"
+			}
+		};
+		if (INHERITED.has(property)) {
+			const parent = doc.parent_of(id);
+			if (parent !== null && doc.is_element(parent)) {
+				const r = resolve_declared(doc, parent, property);
+				if (r.declared !== null) return {
+					declared: r.declared,
+					provenance: {
+						origin: "author",
+						carrier: "inherited"
+					}
+				};
+			}
 		}
+		return {
+			declared: INITIAL[property] ?? null,
+			provenance: {
+				origin: "user_agent",
+				carrier: "defaulted"
+			}
+		};
 	}
-	return {
-		declared: INITIAL[property] ?? null,
-		provenance: {
-			origin: "user_agent",
-			carrier: "defaulted"
-		}
-	};
-}
-/**
-* Type-parsed computed value for known properties. Unknown property names
-* return the declared string as-is.
-*/
-function compute_known(property, declared) {
-	if (declared === null) return null;
-	const trimmed = declared.trim();
-	if (trimmed === "inherit" || trimmed === "initial" || trimmed === "unset" || trimmed === "revert" || trimmed === "revert-layer") return null;
-	if (/^var\s*\(/i.test(trimmed)) return {
-		error: "invalid_at_computed_value_time",
-		reason: `var() substitution requires a cascade engine (not implemented)`
-	};
-	switch (property) {
-		case "opacity":
-		case "fill-opacity":
-		case "stroke-opacity":
-		case "stroke-width":
-		case "x":
-		case "y":
-		case "width":
-		case "height":
-		case "cx":
-		case "cy":
-		case "r":
-		case "rx":
-		case "ry":
-		case "font-size": {
-			const n = parseFloat(trimmed);
-			return Number.isFinite(n) ? n : trimmed;
+	_properties.resolve_declared = resolve_declared;
+	function compute_known(property, declared) {
+		if (declared === null) return null;
+		const trimmed = declared.trim();
+		if (trimmed === "inherit" || trimmed === "initial" || trimmed === "unset" || trimmed === "revert" || trimmed === "revert-layer") return null;
+		if (/^var\s*\(/i.test(trimmed)) return {
+			error: "invalid_at_computed_value_time",
+			reason: `var() substitution requires a cascade engine (not implemented)`
+		};
+		switch (property) {
+			case "opacity":
+			case "fill-opacity":
+			case "stroke-opacity":
+			case "stroke-width":
+			case "x":
+			case "y":
+			case "width":
+			case "height":
+			case "cx":
+			case "cy":
+			case "r":
+			case "rx":
+			case "ry":
+			case "font-size": {
+				const n = parseFloat(trimmed);
+				return Number.isFinite(n) ? n : trimmed;
+			}
+			default: return trimmed;
 		}
-		default: return trimmed;
 	}
-}
-function read_property(doc, id, property) {
-	const { declared, provenance } = resolve_declared(doc, id, property);
-	return {
-		declared,
-		computed: compute_known(property, declared),
-		provenance
-	};
-}
-/** Which carrier should a `set_property` write to? Per the README (P1):
-*  whichever carrier currently wins the cascade. If nothing wins (defaulted /
-*  inherited), write a presentation attribute by default. */
-function choose_write_carrier(doc, id, property) {
-	const inline = doc.get_style(id, property);
-	if (inline !== null && inline !== "") return "inline_style";
-	return "presentation_attribute";
-}
+	_properties.compute_known = compute_known;
+	function read(doc, id, property) {
+		const { declared, provenance } = resolve_declared(doc, id, property);
+		return {
+			declared,
+			computed: compute_known(property, declared),
+			provenance
+		};
+	}
+	_properties.read = read;
+	function choose_write_carrier(doc, id, property) {
+		const inline = doc.get_style(id, property);
+		if (inline !== null && inline !== "") return "inline_style";
+		return "presentation_attribute";
+	}
+	_properties.choose_write_carrier = choose_write_carrier;
+	function value_equals(a, b) {
+		if (a === b) return true;
+		if (a.declared !== b.declared) return false;
+		if (a.provenance.carrier !== b.provenance.carrier) return false;
+		if (a.provenance.origin !== b.provenance.origin) return false;
+		if (a.computed === b.computed) return true;
+		if (a.computed && b.computed && typeof a.computed === "object" && typeof b.computed === "object" && "error" in a.computed && "error" in b.computed) return a.computed.error === b.computed.error && a.computed.reason === b.computed.reason;
+		return false;
+	}
+	_properties.value_equals = value_equals;
+})(properties || (properties = {}));
 //#endregion
 //#region src/core/editor.ts
 const PROVIDER_ID = "svg-editor";
 /** Max characters in a synthesized display label before truncation. */
 const DISPLAY_LABEL_MAX_LEN = 40;
-function createSvgEditor(opts) {
+/**
+* Wide internal factory — returns the full object including the
+* `_internal` / `keymap` surfaces in its inferred type. Stays private.
+* The public `createSvgEditor` below wraps this and narrows the return
+* to `SvgEditor` so the published `.d.ts` doesn't advertise internals.
+*/
+function _create_svg_editor_internal(opts) {
 	const doc = new SvgDocument(opts.svg);
 	const history = new HistoryImpl();
 	const defs = create_defs(doc);
@@ -1438,6 +1824,7 @@ function createSvgEditor(opts) {
 			can_undo: history.stack.canUndo,
 			can_redo: history.stack.canRedo,
 			version,
+			content_version: doc_version,
 			structure_version: doc.structure_version,
 			geometry_version: doc.geometry_version,
 			load_version
@@ -1526,7 +1913,7 @@ function createSvgEditor(opts) {
 	}
 	function tools_equal(a, b) {
 		if (a.type !== b.type) return false;
-		if (a.type === "cursor") return true;
+		if (a.type === "cursor" || a.type === "lasso" || a.type === "bend" || a.type === "insert-text") return true;
 		return b.type === "insert" && a.tag === b.tag;
 	}
 	function set_tool(next) {
@@ -1587,8 +1974,8 @@ function createSvgEditor(opts) {
 		const key = `${id}${name}`;
 		const cached = property_cache.get(key);
 		if (cached && cached.doc_version === doc_version) return cached.value;
-		const next = read_property(doc, id, name);
-		if (cached && property_value_equals(cached.value, next)) {
+		const next = properties.read(doc, id, name);
+		if (cached && properties.value_equals(cached.value, next)) {
 			cached.doc_version = doc_version;
 			return cached.value;
 		}
@@ -1624,13 +2011,13 @@ function createSvgEditor(opts) {
 		const key = `${id}${channel}`;
 		const cached = paint_cache.get(key);
 		if (cached && cached.doc_version === doc_version) return cached.value;
-		const { declared, provenance } = resolve_declared(doc, id, channel);
+		const { declared, provenance } = properties.resolve_declared(doc, id, channel);
 		const next = {
 			declared,
-			computed: parse_paint(declared),
+			computed: paint.parse(declared),
 			provenance
 		};
-		if (cached && paint_value_equals(cached.value, next)) {
+		if (cached && paint.value_equals(cached.value, next)) {
 			cached.doc_version = doc_version;
 			return cached.value;
 		}
@@ -1641,7 +2028,7 @@ function createSvgEditor(opts) {
 		return next;
 	}
 	function write_property(id, name, value) {
-		if (choose_write_carrier(doc, id, name) === "inline_style") doc.set_style(id, name, value);
+		if (properties.choose_write_carrier(doc, id, name) === "inline_style") doc.set_style(id, name, value);
 		else doc.set_attr(id, name, value);
 	}
 	function set_property(name, value) {
@@ -1704,14 +2091,14 @@ function createSvgEditor(opts) {
 			discard: () => preview.discard()
 		};
 	}
-	function set_paint(channel, paint) {
+	function set_paint(channel, p) {
 		if (selection.length === 0) return;
-		set_property(channel, serialize_paint(paint));
+		set_property(channel, paint.serialize(p));
 	}
 	function preview_paint(channel) {
 		const session = preview_property(channel);
 		return {
-			update: (paint) => session.update(serialize_paint(paint)),
+			update: (p) => session.update(paint.serialize(p)),
 			commit: () => session.commit(),
 			discard: () => session.discard()
 		};
@@ -1729,7 +2116,7 @@ function createSvgEditor(opts) {
 	function do_translate_oneshot(delta, stages, label) {
 		if (selection.length === 0) return false;
 		if (delta.dx === 0 && delta.dy === 0) return false;
-		const { apply, revert } = prepare_translate_rpc({
+		const { apply, revert } = translate_pipeline.prepare_rpc({
 			doc,
 			ids: selection,
 			delta: {
@@ -1742,7 +2129,8 @@ function createSvgEditor(opts) {
 				snap_threshold_px: style.snap_threshold_px
 			},
 			emit,
-			stages
+			stages,
+			project: (id, d) => geometry_provider?.world_delta_to_local?.(id, d) ?? d
 		});
 		apply();
 		history.atomic(label, (tx) => {
@@ -1758,7 +2146,7 @@ function createSvgEditor(opts) {
 		if (do_translate_oneshot(delta, void 0, "translate")) notify_translate_commit();
 	}
 	function nudge(delta) {
-		if (do_translate_oneshot(delta, STAGES_NUDGE, "nudge")) notify_translate_commit();
+		if (do_translate_oneshot(delta, translate_pipeline.stages.NUDGE, "nudge")) notify_translate_commit();
 	}
 	/**
 	* One-shot multi-member resize to an explicit target rect. Mirrors a
@@ -1783,13 +2171,13 @@ function createSvgEditor(opts) {
 		if (!geometry_provider) return false;
 		const members = [];
 		for (const id of ids) {
-			if (!is_resizable(doc.tag_of(id))) continue;
+			if (!resize_pipeline.intent.is_resizable(doc.tag_of(id))) continue;
 			const bbox = geometry_provider.bounds_of(id);
 			if (!bbox) continue;
 			members.push({
 				id,
-				rz: capture_resize_baseline(doc, id, bbox),
-				tx_pre: capture_translate_baseline(doc, id),
+				rz: resize_pipeline.intent.capture_baseline(doc, id, bbox),
+				tx_pre: translate_pipeline.intent.capture_baseline(doc, id),
 				transform_pre: doc.get_attr(id, "transform"),
 				bbox
 			});
@@ -1805,16 +2193,16 @@ function createSvgEditor(opts) {
 		const dx = target.x - union.x;
 		const dy = target.y - union.y;
 		const apply = () => {
-			for (const m of members) apply_resize(doc, m.id, m.rz, sx, sy, origin);
+			for (const m of members) resize_pipeline.intent.apply(doc, m.id, m.rz, sx, sy, origin);
 			if (dx !== 0 || dy !== 0) for (const m of members) {
-				const tx_after = capture_translate_baseline(doc, m.id);
-				apply_translate(doc, m.id, tx_after, dx, dy);
+				const tx_after = translate_pipeline.intent.capture_baseline(doc, m.id);
+				translate_pipeline.intent.apply(doc, m.id, tx_after, dx, dy);
 			}
 			emit();
 		};
 		const revert = () => {
 			for (const m of members) {
-				apply_resize(doc, m.id, m.rz, 1, 1, origin);
+				resize_pipeline.intent.apply(doc, m.id, m.rz, 1, 1, origin);
 				doc.set_attr(m.id, "transform", m.transform_pre);
 			}
 			emit();
@@ -1855,10 +2243,11 @@ function createSvgEditor(opts) {
 	function rotate(angle, opts) {
 		const ids = opts?.ids ?? selection;
 		if (ids.length === 0) return false;
-		const prepared = prepare_rotate_rpc({
+		const pivot = opts?.pivot ?? default_rotate_pivot(ids);
+		const prepared = rotate_pipeline.prepare_rpc({
 			doc,
 			ids,
-			pivot: opts?.pivot ?? default_rotate_pivot(ids),
+			pivot,
 			angle_radians: angle,
 			options: { angle_snap_step_radians: style.angle_snap_step_radians },
 			emit
@@ -1877,10 +2266,11 @@ function createSvgEditor(opts) {
 	function rotate_to(angle, opts) {
 		const ids = opts?.ids ?? selection;
 		if (ids.length === 0) return false;
-		const probe = prepare_rotate_rpc({
+		const pivot = opts?.pivot ?? default_rotate_pivot(ids);
+		const probe = rotate_pipeline.prepare_rpc({
 			doc,
 			ids,
-			pivot: opts?.pivot ?? default_rotate_pivot(ids),
+			pivot,
 			angle_radians: 0,
 			options: { angle_snap_step_radians: style.angle_snap_step_radians },
 			emit: () => {}
@@ -1890,12 +2280,12 @@ function createSvgEditor(opts) {
 		const apply = () => {
 			for (const m of probe.plan.members) {
 				const delta = angle - m.baseline.current_rotation_deg * DEG_TO_RAD;
-				apply_rotate(doc, m.id, m.baseline, delta);
+				rotate_pipeline.intent.apply(doc, m.id, m.baseline, delta);
 			}
 			emit();
 		};
 		const revert = () => {
-			for (const m of probe.plan.members) apply_rotate(doc, m.id, m.baseline, 0);
+			for (const m of probe.plan.members) rotate_pipeline.intent.apply(doc, m.id, m.baseline, 0);
 			emit();
 		};
 		apply();
@@ -1915,7 +2305,7 @@ function createSvgEditor(opts) {
 		for (const id of ids) {
 			const pre = doc.get_attr(id, "transform");
 			if (pre === null) continue;
-			const ops = parse_transform_list(pre);
+			const ops = transform.parse(pre);
 			if (ops === null) continue;
 			if (ops.length === 1 && ops[0].type === "matrix") continue;
 			members.push({
@@ -1925,104 +2315,11 @@ function createSvgEditor(opts) {
 			});
 		}
 		if (members.length === 0) return false;
-		const IDENT = [
-			1,
-			0,
-			0,
-			1,
-			0,
-			0
-		];
-		function mul(m1, m2) {
-			const [a1, b1, c1, d1, e1, f1] = m1;
-			const [a2, b2, c2, d2, e2, f2] = m2;
-			return [
-				a1 * a2 + c1 * b2,
-				b1 * a2 + d1 * b2,
-				a1 * c2 + c1 * d2,
-				b1 * c2 + d1 * d2,
-				a1 * e2 + c1 * f2 + e1,
-				b1 * e2 + d1 * f2 + f1
-			];
-		}
-		function op_to_mat(op) {
-			switch (op.type) {
-				case "matrix": return [
-					op.a,
-					op.b,
-					op.c,
-					op.d,
-					op.e,
-					op.f
-				];
-				case "translate": return [
-					1,
-					0,
-					0,
-					1,
-					op.tx,
-					op.ty
-				];
-				case "rotate": {
-					const rad = op.angle * Math.PI / 180;
-					const c = Math.cos(rad);
-					const s = Math.sin(rad);
-					if (op.cx === 0 && op.cy === 0) return [
-						c,
-						s,
-						-s,
-						c,
-						0,
-						0
-					];
-					const e = op.cx - c * op.cx + s * op.cy;
-					const f = op.cy - s * op.cx - c * op.cy;
-					return [
-						c,
-						s,
-						-s,
-						c,
-						e,
-						f
-					];
-				}
-				case "scale": return [
-					op.sx,
-					0,
-					0,
-					op.sy,
-					0,
-					0
-				];
-				case "skewX": {
-					const rad = op.angle * Math.PI / 180;
-					return [
-						1,
-						0,
-						Math.tan(rad),
-						1,
-						0,
-						0
-					];
-				}
-				case "skewY": {
-					const rad = op.angle * Math.PI / 180;
-					return [
-						1,
-						Math.tan(rad),
-						0,
-						1,
-						0,
-						0
-					];
-				}
-			}
-		}
 		const apply = () => {
 			for (const m of members) {
-				let mat = IDENT;
-				for (const op of m.ops) mat = mul(mat, op_to_mat(op));
-				doc.set_attr(m.id, "transform", emit_transform_list([{
+				let mat = FLATTEN_IDENT;
+				for (const op of m.ops) mat = flatten_mul(mat, flatten_op_to_mat(op));
+				doc.set_attr(m.id, "transform", transform.emit([{
 					type: "matrix",
 					a: mat[0],
 					b: mat[1],
@@ -2072,7 +2369,7 @@ function createSvgEditor(opts) {
 		for (const id of ids) {
 			const bbox = geometry_provider.bounds_of(id);
 			if (!bbox) continue;
-			const baseline = capture_translate_baseline(doc, id);
+			const baseline = translate_pipeline.intent.capture_baseline(doc, id);
 			if (baseline.type === "unsupported") continue;
 			members.push({
 				id,
@@ -2094,12 +2391,12 @@ function createSvgEditor(opts) {
 		const apply = () => {
 			for (const m of members) {
 				const d = deltas.get(m.id);
-				if (d) apply_translate(doc, m.id, m.baseline, d.x, d.y);
+				if (d) translate_pipeline.intent.apply(doc, m.id, m.baseline, d.x, d.y);
 			}
 			emit();
 		};
 		const revert = () => {
-			for (const m of members) if (deltas.has(m.id)) apply_translate(doc, m.id, m.baseline, 0, 0);
+			for (const m of members) if (deltas.has(m.id)) translate_pipeline.intent.apply(doc, m.id, m.baseline, 0, 0);
 			emit();
 		};
 		apply();
@@ -2224,8 +2521,8 @@ function createSvgEditor(opts) {
 			});
 		});
 	}
-	function group() {
-		const plan = plan_group(doc, selection);
+	function group$1() {
+		const plan = group.plan(doc, selection);
 		if (!plan) return false;
 		const group_id = doc.create_element("g");
 		const original_selection = selection;
@@ -2353,12 +2650,70 @@ function createSvgEditor(opts) {
 			}
 		};
 	}
+	/**
+	* Text-creation bracket for the click-to-place text tool. Creates an
+	* empty `<text>` with `initial` attrs, opens a single history preview,
+	* and selects it — the DOM surface then mounts inline content-edit on
+	* it. The surface finalizes the returned session when content-edit
+	* exits:
+	*
+	*  - `commit()` — snapshots the live text content into the delta and
+	*    commits ONE undo step (create + text together). Redo replays both,
+	*    so a redone text insert keeps its content (a plain `insert_preview`
+	*    would lose it — text is not an attribute).
+	*  - `discard()` — rolls the creation back entirely: no node, no
+	*    committed history entry. This is the empty-equals-delete rule for a
+	*    freshly-placed node (design:
+	*    `docs/wg/feat-svg-editor/text-tool.md`).
+	*
+	* The node is inserted empty on open (so the caret has somewhere to
+	* live); live edits mutate its text in place, and `commit()` reads the
+	* final text back off the document.
+	*/
+	function insert_text_preview(initial, opts) {
+		const parent = opts?.parent ?? doc.root;
+		const id = doc.create_element("text");
+		const previous_selection = selection;
+		const attrs = { ...initial };
+		let committed_text = "";
+		const apply = () => {
+			for (const name in attrs) doc.set_attr(id, name, attrs[name]);
+			if (doc.parent_of(id) === null) doc.insert(id, parent, null);
+			doc.set_text(id, committed_text);
+			set_selection([id]);
+		};
+		const revert = () => {
+			doc.remove(id);
+			set_selection(previous_selection);
+		};
+		const preview = history.preview("insert text");
+		let active = true;
+		preview.set({
+			providerId: PROVIDER_ID,
+			apply,
+			revert
+		});
+		return {
+			id,
+			commit() {
+				if (!active) return;
+				active = false;
+				committed_text = doc.text_of(id);
+				preview.commit();
+			},
+			discard() {
+				if (!active) return;
+				active = false;
+				preview.discard();
+			}
+		};
+	}
 	/** Per-tag default paint attrs. Wrapped so callers don't need to depend
 	*  on the InsertableTag type — `insert()` accepts arbitrary string tags
 	*  (so `commands.insert("path", ...)` works for paste / RPC) but only
 	*  the closed insertable set gets default paint. */
 	function default_paint_attrs_for(tag) {
-		if (tag === "rect" || tag === "ellipse" || tag === "line") return default_paint_attrs(tag);
+		if (tag === "rect" || tag === "ellipse" || tag === "line") return insertions.default_paint_attrs(tag);
 		return {};
 	}
 	function set_text(value) {
@@ -2407,7 +2762,7 @@ function createSvgEditor(opts) {
 	function enter_content_edit(target) {
 		const id = target ?? (selection.length === 1 ? selection[0] : null);
 		if (!id) return false;
-		if (!doc.is_text_edit_target(id)) return false;
+		if (!doc.is_text_edit_target(id) && doc.is_vector_edit_target(id) === null) return false;
 		if (!content_edit_driver) return false;
 		return content_edit_driver(id);
 	}
@@ -2455,7 +2810,7 @@ function createSvgEditor(opts) {
 		align,
 		reorder,
 		remove,
-		group,
+		group: group$1,
 		insert,
 		insert_preview,
 		set_text,
@@ -2511,6 +2866,10 @@ function createSvgEditor(opts) {
 		emit();
 	}
 	const public_editor = {
+		/**
+		* Low-level IR handle. Mutating directly bypasses history; prefer
+		* `editor.commands` for app code.
+		*/
 		document: doc,
 		get state() {
 			return snapshot();
@@ -2521,9 +2880,28 @@ function createSvgEditor(opts) {
 		node_paint,
 		dom_computed_property,
 		dom_computed_paint,
+		/**
+		* Enter content-edit mode on a `<text>` node. Returns `false` (no-op)
+		* when no DOM surface is attached.
+		*/
 		enter_content_edit,
 		defs,
 		commands,
+		/**
+		* Human-readable label for hierarchy panels. SVG has no native "name";
+		* this is the package's single source of truth so panels don't reinvent
+		* the rule.
+		*
+		* Rule:
+		*   - `<text>` → text content, whitespace-collapsed and truncated at
+		*     ~40 chars (falls back to `"text"` for empty content).
+		*   - Otherwise → tag name, suffixed with `#id` when the `id` attribute
+		*     is present (e.g. `"rect #sun"`).
+		*
+		* `opts.tagLabel` lets callers substitute a friendlier or localized
+		* term for the raw tag (e.g. `"rect"` → `"Rectangle"`). Only invoked
+		* on the non-text branch.
+		*/
 		display_label(id, opts) {
 			const tag = doc.tag_of(id);
 			if (tag === "text") {
@@ -2538,30 +2916,59 @@ function createSvgEditor(opts) {
 		tree() {
 			return tree_snapshot();
 		},
+		/**
+		* The effective hover from the attached HUD surface — what's under the
+		* pointer, OR whatever `set_surface_hover_override` last pushed. Used
+		* by out-of-canvas UI (layers panel, breadcrumbs) to mirror the canvas
+		* highlight. Returns `null` when nothing is hovered.
+		*/
 		surface_hover() {
 			return current_surface_hover;
 		},
+		/**
+		* Push a hover override into the HUD surface — e.g. when the user
+		* hovers a row in a layers panel. The HUD will render the override's
+		* outline and (when applicable) drive measurement to that node.
+		* Pass `null` to clear and let the pointer pick take over again.
+		*/
 		set_surface_hover_override(id) {
 			if (surface_hover_override === id) return;
 			surface_hover_override = id;
 			if (surface_hover_override_driver) surface_hover_override_driver(id);
 		},
+		/**
+		* Subscribe to changes in the effective surface hover. Fires when the
+		* HUD reports a new pointer pick AND when an override is set/cleared.
+		* Cheap channel — does NOT bump `state.version`.
+		*/
 		subscribe_surface_hover(cb) {
 			surface_hover_listeners.add(cb);
 			return () => {
 				surface_hover_listeners.delete(cb);
 			};
 		},
+		/**
+		* Subscribe to bounds-affecting changes. Fires when any document
+		* mutation advances `state.geometry_version` — drag, resize, text
+		* edit, structural insert/remove. Skips presentation-only writes
+		* (fill, opacity, stroke-color).
+		*/
 		subscribe_geometry(cb) {
 			geometry_listeners.add(cb);
 			return () => {
 				geometry_listeners.delete(cb);
 			};
 		},
+		/**
+		* World-space geometry queries. Non-null when a DOM surface is
+		* attached; null otherwise (queries need a renderer to read bbox
+		* from). Read-only — never mutates document state.
+		*/
 		get geometry() {
 			return geometry_provider;
 		},
 		modes,
+		/** Switch the active tool. No history entry; bumps `state.version`. */
 		set_tool,
 		get style() {
 			return style;
@@ -2569,6 +2976,21 @@ function createSvgEditor(opts) {
 		set_style,
 		load,
 		serialize,
+		/**
+		* Serialize a single element's subtree as an SVG **fragment**, using the
+		* same trivia-preserving rules as {@link serialize} — for handing "the
+		* markup of the element the user selected" to a downstream consumer
+		* (e.g. an AI agent) without re-serializing the whole document.
+		*
+		* Fragment, not document (see `SvgDocument.serialize_node`): it does NOT
+		* carry `serialize()`'s whole-document round-trip guarantee. Namespace
+		* declarations on an ancestor (`xmlns:xlink`, normally on the root
+		* `<svg>`) are NOT inlined — a node using `xlink:href` serializes without
+		* `xmlns:xlink`. Throws on an unknown id or a non-element node.
+		*/
+		serialize_node(id) {
+			return doc.serialize_node(id);
+		},
 		reset,
 		attach,
 		detach,
@@ -2577,6 +2999,7 @@ function createSvgEditor(opts) {
 		_internal: {
 			doc,
 			history: { preview: (label) => history.preview(label) },
+			insert_text_preview,
 			emit,
 			subscribe_translate_commit(cb) {
 				translate_commit_listeners.add(cb);
@@ -2608,37 +3031,112 @@ function createSvgEditor(opts) {
 	applyDefaultBindings(keymap);
 	return public_editor;
 }
-function paint_value_equals(a, b) {
-	if (a === b) return true;
-	if (a.declared !== b.declared) return false;
-	if (a.provenance.carrier !== b.provenance.carrier) return false;
-	if (a.provenance.origin !== b.provenance.origin) return false;
-	return paint_equals(a.computed, b.computed);
-}
-function paint_equals(a, b) {
-	if (a === b) return true;
-	if (a == null || b == null) return false;
-	if ("error" in a || "error" in b) return "error" in a && "error" in b && a.error === b.error && a.reason === b.reason;
-	if (a.kind !== b.kind) return false;
-	if (a.kind === "color" && b.kind === "color") {
-		if (a.value.kind !== b.value.kind) return false;
-		if (a.value.kind === "rgb" && b.value.kind === "rgb") return a.value.value === b.value.value;
-		return true;
+/**
+* Construct a headless SVG editor. The returned object is the public
+* editor surface — observation (`state`, `subscribe`), commands
+* (`commands.*`), lifecycle (`attach` / `dispose`), and the typed-read
+* caches (`node_paint`, `node_properties`). Surfaces (DOM, headless)
+* attach later via `editor.attach(surface)`.
+*/
+function createSvgEditor(opts) {
+	if (opts == null || typeof opts.svg !== "string") {
+		const got = opts == null ? String(opts) : opts.svg === null ? "null" : typeof opts.svg;
+		throw new TypeError(`createSvgEditor({ svg }) requires { svg: string }, got svg=${got}`);
 	}
-	if (a.kind === "ref" && b.kind === "ref") return a.id === b.id;
-	if (a.kind === "none" && b.kind === "none") return true;
-	if (a.kind === "context_fill" && b.kind === "context_fill") return true;
-	if (a.kind === "context_stroke" && b.kind === "context_stroke") return true;
-	return false;
+	return _create_svg_editor_internal(opts);
 }
-function property_value_equals(a, b) {
-	if (a === b) return true;
-	if (a.declared !== b.declared) return false;
-	if (a.provenance.carrier !== b.provenance.carrier) return false;
-	if (a.provenance.origin !== b.provenance.origin) return false;
-	if (a.computed === b.computed) return true;
-	if (a.computed && b.computed && typeof a.computed === "object" && typeof b.computed === "object" && "error" in a.computed && "error" in b.computed) return a.computed.error === b.computed.error && a.computed.reason === b.computed.reason;
-	return false;
+const FLATTEN_IDENT = [
+	1,
+	0,
+	0,
+	1,
+	0,
+	0
+];
+function flatten_mul(m1, m2) {
+	const [a1, b1, c1, d1, e1, f1] = m1;
+	const [a2, b2, c2, d2, e2, f2] = m2;
+	return [
+		a1 * a2 + c1 * b2,
+		b1 * a2 + d1 * b2,
+		a1 * c2 + c1 * d2,
+		b1 * c2 + d1 * d2,
+		a1 * e2 + c1 * f2 + e1,
+		b1 * e2 + d1 * f2 + f1
+	];
+}
+function flatten_op_to_mat(op) {
+	switch (op.type) {
+		case "matrix": return [
+			op.a,
+			op.b,
+			op.c,
+			op.d,
+			op.e,
+			op.f
+		];
+		case "translate": return [
+			1,
+			0,
+			0,
+			1,
+			op.tx,
+			op.ty
+		];
+		case "rotate": {
+			const rad = op.angle * Math.PI / 180;
+			const c = Math.cos(rad);
+			const s = Math.sin(rad);
+			if (op.cx === 0 && op.cy === 0) return [
+				c,
+				s,
+				-s,
+				c,
+				0,
+				0
+			];
+			const e = op.cx - c * op.cx + s * op.cy;
+			const f = op.cy - s * op.cx - c * op.cy;
+			return [
+				c,
+				s,
+				-s,
+				c,
+				e,
+				f
+			];
+		}
+		case "scale": return [
+			op.sx,
+			0,
+			0,
+			op.sy,
+			0,
+			0
+		];
+		case "skewX": {
+			const rad = op.angle * Math.PI / 180;
+			return [
+				1,
+				0,
+				Math.tan(rad),
+				1,
+				0,
+				0
+			];
+		}
+		case "skewY": {
+			const rad = op.angle * Math.PI / 180;
+			return [
+				1,
+				Math.tan(rad),
+				0,
+				1,
+				0,
+				0
+			];
+		}
+	}
 }
 //#endregion
 export { createSvgEditor as t };