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

package/dist/{editor-CJ2KuRh5.d.ts → editor-BKoo9SPL.d.ts}

@@ -1,6 +1,6 @@
 import cmath from "@grida/cmath";
 import vn from "@grida/vn";
-import { AnyNode } from "@grida/svg/parser";
+import { AnyNode, AttrToken } from "@grida/svg/parser";
 import { SelectMode } from "@grida/hud";
 import { Keybinding, Platform } from "@grida/keybinding";
 
@@ -499,18 +499,76 @@ type AlignDirection = "left" | "right" | "top" | "bottom" | "horizontal_centers"
  *   - All coordinates are in the element's own local space, exactly as
  *     authored. No `transform=` resolution, no parent CTM, no viewport
  *     remap.
- *   - `polyline` / `polygon` points are `[x, y]` tuples so the consumer
- *     can hand them straight to `vn.fromPolyline` / `vn.fromPolygon`.
+ *   - `line` carries its two endpoints; `polyline` / `polygon` points are
+ *     `[x, y]` tuples so the consumer can hand them straight to
+ *     `vn.fromPolyline` / `vn.fromPolygon`.
+ *   - `rect` / `circle` / `ellipse` carry their native geometry numbers.
+ *     These geometry primitives have no addressable interior vertices in
+ *     their native form, so editing one as vector geometry re-types the
+ *     element to `<path>` (see `retype_to_path`). The document holds the
+ *     native tag until that re-type is committed. Design:
+ *     `docs/wg/feat-svg-editor/promote-to-path.md`.
+ *
+ * Re-type vs. native writeback is decided per edit, not per tag: an edit
+ * that the source tag can still express (a straight vertex move on
+ * `line` / `polyline` / `polygon`) writes back natively; one it cannot (a
+ * curve, or a topology change that leaves the tag's canonical form)
+ * re-types the element to `<path>`.
  */
 type VectorEditSource = {
   kind: "path";
   d: string;
+} | {
+  kind: "line";
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
 } | {
   kind: "polyline";
   points: ReadonlyArray<readonly [number, number]>;
 } | {
   kind: "polygon";
   points: ReadonlyArray<readonly [number, number]>;
+} | {
+  kind: "rect";
+  x: number;
+  y: number;
+  width: number;
+  height: number; /** Corner radii; `0` when the rect has square corners. */
+  rx: number;
+  ry: number;
+} | {
+  kind: "circle";
+  cx: number;
+  cy: number;
+  r: number;
+} | {
+  kind: "ellipse";
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+};
+/**
+ * Opaque reversal token returned by `retype_to_path`. Callers hold it and
+ * hand it back to `revert_retype` to restore the original primitive
+ * byte-for-byte; they do not inspect it. All trivia / attribute-token
+ * knowledge stays inside `SvgDocument`.
+ */
+type RetypeRecord = {
+  readonly prev_local: string;
+  readonly prev_raw_tag: string;
+  /** Geometry attribute tokens removed on re-type, with their original
+   *  index in the element's `attrs` array. Ascending by index so they can
+   *  be spliced back in order. Typed as the document's internal attr token. */
+  readonly removed: ReadonlyArray<{
+    index: number;
+    token: AttrToken;
+  }>;
+  /** True iff the re-type added a synthetic `fill="none"` (the `<line>`
+   *  fidelity guard — see `retype_to_path`). `revert_retype` removes it. */
+  readonly added_fill_none?: boolean;
 };
 interface DocumentEvents {
   /** Fires after any structural mutation. */
@@ -629,24 +687,74 @@ declare class SvgDocument implements DocumentEvents {
    * Returns a tag-discriminated snapshot of the authored geometry attrs
    * if this node is eligible for vector (vertex) editing — else `null`.
    *
-   * v1 eligibility:
+   * 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`.
    *
-   * Deliberately rejects `<line>` in v1: the only useful vertex-edit
-   * gestures on a `<line>` are (a) introducing a new vertex (which would
-   * have to promote it to `<polyline>`) and (b) bending it with a tangent
-   * (which would have to promote it to `<path>`). Both promotions are
-   * out of scope for v1, so opening a `<line>` in vector-edit mode would
-   * advertise capabilities that don't work.
+   * 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.
    *
-   * Also rejects `<rect>`, `<circle>`, `<ellipse>`, `<image>`, `<use>` —
-   * those would force the same promotion-to-`<path>` machinery (trivia
-   * transfer, cross-cutting attr carry, DOM-element swap, history-bracket
-   * changes) that v1 keeps out of scope.
+   * 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.
+   */
+  private optional_user_unit_coord;
   is_vector_edit_target(id: NodeId): VectorEditSource | 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: NodeId, d: string): RetypeRecord | null;
+  /**
+   * 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: NodeId, token: RetypeRecord): void;
   /**
    * True iff this `<text>` / `<tspan>` carries a non-empty `rotate=""`
    * per-glyph attribute (which conflicts with element-level rotation).
@@ -674,6 +782,31 @@ declare class SvgDocument implements DocumentEvents {
     ns?: string | null;
   }): NodeId;
   serialize(): string;
+  /**
+   * 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: NodeId): string;
   private emit_node;
   private emit_attr;
 }
@@ -795,20 +928,26 @@ declare class PathModel {
    *
    * - **path** — always `null` (no native fallback; the canonical form
    *   IS `<path d>`, so callers should just write `d` directly).
+   * - **line** — exactly two vertices joined by one straight segment
+   *   `0→1`. (Topology after a 2-point `vn.fromPolyline` and any sequence
+   *   of endpoint translates.)
    * - **polyline** — segments form the canonical open chain
    *   `0→1, 1→2, …, (n-2)→(n-1)`. (Topology after `vn.fromPolyline` and
    *   any sequence of vertex translates.)
    * - **polygon** — segments form the canonical closed chain
    *   `0→1, 1→2, …, (n-1)→0`. (Topology after `vn.fromPolygon` and any
    *   sequence of vertex translates.)
+   * - **rect / circle / ellipse** — always `null`. These geometry
+   *   primitives have no native writeback target; any vector gesture on
+   *   them re-types the element to `<path>` (see `vector_apply` /
+   *   `SvgDocument.retype_to_path`), so they never round-trip through here.
    *
    * Anything that changes segment topology (insert-vertex, delete-vertex,
-   * close/open shape) leaves the canonical chain and returns `null` here;
-   * the higher layer is responsible for routing those to tag-promotion
-   * (intra-Vertex or to-path).
+   * close/open shape) or introduces a curve leaves the canonical chain and
+   * returns `null` here; the caller re-types the element to `<path>`.
    */
-  toNativeAttrs(source_tag: VectorEditSource["kind"]): Exclude<VectorEditSource, {
-    kind: "path";
+  toNativeAttrs(source_tag: VectorEditSource["kind"]): Extract<VectorEditSource, {
+    kind: "line" | "polyline" | "polygon";
   }> | null;
   /** Translate one vertex by `delta`. Connected segments follow because
    *  tangents are stored relative to vertices. Verb metadata is preserved
@@ -1124,6 +1263,20 @@ interface GeometryProvider {
    * is hit. "Topmost" is defined by the renderer's z-order.
    */
   node_at_point(p: Vec2): NodeId | null;
+  /**
+   * Re-express a **world-space** delta vector in the frame a node's
+   * position attributes are written in — its parent user-space. For a
+   * node under a scaled/rotated `<g>` ancestor, or inside a nested
+   * `<svg>` viewport that scales its user space, the local frame differs
+   * from world by that linear transform; a translate must be written in
+   * the local frame so the on-screen motion matches the world delta
+   * (otherwise it moves `scale ×` too far).
+   *
+   * Optional: only DOM-backed providers (with a real layout engine) can
+   * derive the frame. Providers that omit it imply the flat-doc identity
+   * (world ≡ local), and callers fall back to the raw delta.
+   */
+  world_delta_to_local?(id: NodeId, delta: Vec2): Vec2;
 }
 type GeometrySignals = {
   /** Fires when tree shape changes (insert/remove/reorder). */subscribe_structure: (cb: () => void) => Unsubscribe; /** Fires when any bounds-affecting change occurs. */
@@ -1148,6 +1301,10 @@ declare class MemoizedGeometryProvider implements GeometryProvider {
    */
   nodes_in_rect(rect: Rect): NodeId[];
   node_at_point(p: Vec2): NodeId | null;
+  /** Pass-through. Frame projection depends on live layout, not on the
+   *  bounds cache, so there is nothing to memoize. Falls back to the raw
+   *  delta when the driver can't resolve a frame. */
+  world_delta_to_local(id: NodeId, delta: Vec2): Vec2;
   /** Unsubscribe from both signals. Call on surface detach. */
   dispose(): void;
 }
@@ -1547,6 +1704,19 @@ declare function _create_svg_editor_internal(opts: CreateSvgEditorOptions): {
   set_style: (partial: Partial<EditorStyle>) => void;
   load: (svg: string) => void;
   serialize: () => string;
+  /**
+   * 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: NodeId): string;
   reset: () => void;
   attach: (surface: Surface) => SurfaceHandle;
   detach: () => void;

package/dist/{editor-B6pchGYk.mjs → editor-CvWpD5mu.mjs}

@@ -1,4 +1,4 @@
-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-DIzZmeyf.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";
@@ -756,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
@@ -1073,26 +1122,53 @@ var SvgDocument = class SvgDocument {
 	* Returns a tag-discriminated snapshot of the authored geometry attrs
 	* if this node is eligible for vector (vertex) editing — else `null`.
 	*
-	* v1 eligibility:
+	* 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`.
 	*
-	* Deliberately rejects `<line>` in v1: the only useful vertex-edit
-	* gestures on a `<line>` are (a) introducing a new vertex (which would
-	* have to promote it to `<polyline>`) and (b) bending it with a tangent
-	* (which would have to promote it to `<path>`). Both promotions are
-	* out of scope for v1, so opening a `<line>` in vector-edit mode would
-	* advertise capabilities that don't work.
+	* 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.
 	*
-	* Also rejects `<rect>`, `<circle>`, `<ellipse>`, `<image>`, `<use>` —
-	* those would force the same promotion-to-`<path>` machinery (trivia
-	* transfer, cross-cutting attr carry, DOM-element swap, history-bracket
-	* changes) that v1 keeps out of scope.
+	* 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");
@@ -1102,6 +1178,21 @@ var SvgDocument = class SvgDocument {
 					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") ?? "";
@@ -1116,10 +1207,172 @@ var SvgDocument = class SvgDocument {
 					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).
 	*/
@@ -1242,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);
@@ -1845,7 +2129,8 @@ function _create_svg_editor_internal(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) => {
@@ -2691,6 +2976,21 @@ function _create_svg_editor_internal(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,