@glissade/backend-dom 0.21.0-pre.0 → 0.21.0-pre.2

package/README.md

@@ -56,6 +56,36 @@ stage.addEventListener('click', (e) => {
 });
 ```
 
+> **One `emitWithIds()` feeds BOTH `setIds` and `render`.** The id stream is
+> positional by command index, so `setIds(...)` and `render(...)` must come from
+> the *same* emit — `setIds(emitWithIds(sceneA, …).ids)` then
+> `render(evaluate(sceneB, …))` silently mis-maps `data-node-id`. Always destructure
+> one call: `const { displayList, ids } = emitWithIds(scene, tl, t)`.
+
+## No-build (`<script src>`)
+
+The DOM tier ships as a separate **optional** IIFE, `glissade-dom.browser.js`, a
+second `<script>` loaded *after* the base bundle — it augments `window.glissade`
+with `DomBackend` + `emitWithIds` (the base playback bundle stays lean and
+`DomBackend`-free):
+
+```html
+<script src="https://unpkg.com/@glissade/browser/dist/glissade.browser.js"></script>
+<script src="https://unpkg.com/@glissade/browser/dist/glissade-dom.browser.js"></script>
+<script type="module">
+  const backend = new glissade.DomBackend(document.getElementById('stage'));
+  function frame(t) {
+    for (const m of movements) m.run(t);
+    const { displayList, ids } = glissade.emitWithIds(scene, EMPTY, t); // ONE emit
+    backend.setIds(ids);
+    backend.render(displayList);
+  }
+</script>
+```
+
+Load order is fail-loud: `glissade-dom.browser.js` throws a clear error if the
+base bundle is absent or a different version (never a cryptic `undefined`).
+
 ## What it maps
 
 | IR op | DOM/SVG |

package/dist/index.d.ts

@@ -6,8 +6,9 @@ import { NodeIdStream } from "@glissade/scene/identity";
 /**
  * A DOM/SVG `RenderBackend`. Construct with a host element (renders into it) or a
  * bare `Document` (builds a detached `root` you read off `backend.root`). Each
- * `render()` rebuilds the tree (forward render; the cross-frame retained-DOM
- * reconciler is Stage S3). Preview / non-parity — see the module header.
+ * `render()` REUSES + PATCHES a retained tree keyed on `data-node-id` (Stage S3),
+ * so inline-edit state, host overlays, listeners, and CSS transitions survive a
+ * re-render. Preview / non-parity — see the module header.
  */
 declare class DomBackend implements RenderBackend {
   #private;

package/dist/index.js

@@ -69,11 +69,22 @@ function segsToD(segs) {
 	}
 	return parts.join(" ");
 }
+/** Short, stable FNV-1a hash (hex) over a string — for deterministic def ids
+* that survive reorder (same scope+key → same id across frames). */
+function hashKey(s) {
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(36);
+}
 /**
 * A DOM/SVG `RenderBackend`. Construct with a host element (renders into it) or a
 * bare `Document` (builds a detached `root` you read off `backend.root`). Each
-* `render()` rebuilds the tree (forward render; the cross-frame retained-DOM
-* reconciler is Stage S3). Preview / non-parity — see the module header.
+* `render()` REUSES + PATCHES a retained tree keyed on `data-node-id` (Stage S3),
+* so inline-edit state, host overlays, listeners, and CSS transitions survive a
+* re-render. Preview / non-parity — see the module header.
 */
 var DomBackend = class {
 	root;
@@ -81,13 +92,16 @@ var DomBackend = class {
 	#host;
 	#images = /* @__PURE__ */ new Map();
 	#videos = /* @__PURE__ */ new Map();
+	#frame = 0;
+	#recon = /* @__PURE__ */ new WeakMap();
+	#owned = /* @__PURE__ */ new WeakMap();
 	#ids = [];
-	#defCounter = 0;
 	#measureSpan = null;
 	#warnedMeasure = false;
 	#warnedMesh = false;
 	#warnedGradientInterp = false;
 	#warnedShader = false;
+	#warnedUnbalanced = false;
 	constructor(target) {
 		const isDoc = target.nodeType === 9;
 		this.#doc = isDoc ? target : target.ownerDocument ?? target;
@@ -111,16 +125,18 @@ var DomBackend = class {
 	render(list) {
 		const doc = this.#doc;
 		const ids = this.#ids;
-		this.#defCounter = 0;
-		this.root.replaceChildren();
-		this.root.style.width = `${list.size.w}px`;
-		this.root.style.height = `${list.size.h}px`;
+		this.#frame++;
+		this.#enterCursor(this.root, "");
+		{
+			const w = `${list.size.w}px`;
+			const h = `${list.size.h}px`;
+			if (this.root.style.width !== w) this.root.style.width = w;
+			if (this.root.style.height !== h) this.root.style.height = h;
+		}
 		let cursor = this.root;
 		const stack = [];
-		const stamp = (el, i) => {
-			const id = ids[i];
-			if (id !== void 0) el.setAttribute("data-node-id", id);
-		};
+		let scope = "";
+		const scopeStack = [];
 		const pathSegs = (id) => {
 			const res = list.resources[id];
 			return res && res.kind === "path" ? res.segs : [];
@@ -137,130 +153,215 @@ var DomBackend = class {
 			return svg;
 		};
 		list.commands.forEach((cmd, i) => {
+			const id = ids[i];
 			switch (cmd.op) {
 				case "save":
 					stack.push(cursor);
+					scopeStack.push(scope);
 					break;
 				case "restore":
+					this.#pruneCursor(cursor);
 					cursor = stack.pop() ?? this.root;
+					scope = scopeStack.pop() ?? "";
 					break;
 				case "transform": {
-					const wrap = doc.createElement("div");
-					wrap.style.position = "absolute";
-					wrap.style.transformOrigin = "0 0";
-					wrap.style.transform = cssMatrix(cmd.m);
-					stamp(wrap, i);
-					cursor.appendChild(wrap);
-					cursor = wrap;
+					const key = this.#keyFor(cursor, id, "transform");
+					const o = this.#matchOrCreate(cursor, key, "transform", () => {
+						const wrap = doc.createElement("div");
+						wrap.style.position = "absolute";
+						wrap.style.transformOrigin = "0 0";
+						return {
+							op: "transform",
+							el: wrap,
+							props: {}
+						};
+					});
+					this.#setStyle(o, o.el, "transform", cssMatrix(cmd.m));
+					this.#stamp(o, o.el, id);
+					cursor = o.el;
+					scope = scope + "/" + key;
+					this.#enterCursor(cursor, scope);
 					break;
 				}
 				case "clip": {
-					const id = `gsclip${this.#defCounter++}`;
-					const svg = island();
-					const defs = doc.createElementNS(SVG_NS, "defs");
-					const cp = doc.createElementNS(SVG_NS, "clipPath");
-					cp.setAttribute("id", id);
-					cp.setAttribute("clipPathUnits", "userSpaceOnUse");
-					const p = doc.createElementNS(SVG_NS, "path");
-					p.setAttribute("d", segsToD(pathSegs(cmd.path)));
-					p.setAttribute("clip-rule", cmd.rule ?? "nonzero");
-					cp.appendChild(p);
-					defs.appendChild(cp);
-					svg.appendChild(defs);
-					cursor.appendChild(svg);
-					const wrap = doc.createElement("div");
-					wrap.style.position = "absolute";
-					wrap.style.left = "0";
-					wrap.style.top = "0";
-					wrap.style.clipPath = `url(#${id})`;
-					stamp(wrap, i);
-					cursor.appendChild(wrap);
-					cursor = wrap;
+					const key = this.#keyFor(cursor, id, "clip");
+					const defId = "gsclip_" + hashKey(scope + " " + key);
+					const o = this.#matchOrCreate(cursor, key, "clip", () => {
+						const svg = island();
+						const defs = doc.createElementNS(SVG_NS, "defs");
+						const cp = doc.createElementNS(SVG_NS, "clipPath");
+						cp.setAttribute("clipPathUnits", "userSpaceOnUse");
+						const p = doc.createElementNS(SVG_NS, "path");
+						cp.appendChild(p);
+						defs.appendChild(cp);
+						svg.appendChild(defs);
+						const wrap = doc.createElement("div");
+						wrap.style.position = "absolute";
+						wrap.style.left = "0";
+						wrap.style.top = "0";
+						return {
+							op: "clip",
+							el: wrap,
+							aux: svg,
+							path: p,
+							props: {}
+						};
+					});
+					o.defId = defId;
+					const p = o.path;
+					const cp = o.aux.querySelector("clipPath");
+					this.#setAttr(p, o, "d", "d", segsToD(pathSegs(cmd.path)));
+					this.#setAttr(p, o, "clipRule", "clip-rule", cmd.rule ?? "nonzero");
+					this.#setAttr(cp, o, "cpId", "id", defId);
+					this.#setStyle(o, o.el, "clipPath", `url(#${defId})`);
+					this.#stamp(o, o.el, id);
+					cursor = o.el;
+					scope = scope + "/" + key;
+					this.#enterCursor(cursor, scope);
 					break;
 				}
 				case "fillPath": {
-					const svg = island();
-					const path = doc.createElementNS(SVG_NS, "path");
-					path.setAttribute("d", segsToD(pathSegs(cmd.path)));
-					path.setAttribute("fill", this.#resolvePaint(cmd.paint, svg, path));
-					stamp(path, i);
-					svg.appendChild(path);
-					cursor.appendChild(svg);
+					const key = this.#keyFor(cursor, id, "fillPath");
+					const o = this.#matchOrCreate(cursor, key, "fillPath", () => {
+						const svg = island();
+						const path = doc.createElementNS(SVG_NS, "path");
+						svg.appendChild(path);
+						return {
+							op: "fillPath",
+							el: svg,
+							path,
+							props: {}
+						};
+					});
+					const path = o.path;
+					this.#setAttr(path, o, "d", "d", segsToD(pathSegs(cmd.path)));
+					this.#setAttr(path, o, "fill", "fill", this.#resolvePaint(cmd.paint, o, scope, key));
+					this.#stamp(o, path, id);
 					break;
 				}
 				case "strokePath": {
-					const svg = island();
-					const path = doc.createElementNS(SVG_NS, "path");
-					path.setAttribute("d", segsToD(pathSegs(cmd.path)));
-					path.setAttribute("fill", "none");
-					path.setAttribute("stroke", this.#resolvePaint(cmd.paint, svg, path));
-					applyStroke(path, cmd.stroke);
-					stamp(path, i);
-					svg.appendChild(path);
-					cursor.appendChild(svg);
+					const key = this.#keyFor(cursor, id, "strokePath");
+					const o = this.#matchOrCreate(cursor, key, "strokePath", () => {
+						const svg = island();
+						const path = doc.createElementNS(SVG_NS, "path");
+						svg.appendChild(path);
+						return {
+							op: "strokePath",
+							el: svg,
+							path,
+							props: {}
+						};
+					});
+					const path = o.path;
+					this.#setAttr(path, o, "d", "d", segsToD(pathSegs(cmd.path)));
+					this.#setAttr(path, o, "fill", "fill", "none");
+					this.#setAttr(path, o, "stroke", "stroke", this.#resolvePaint(cmd.paint, o, scope, key));
+					this.#applyStroke(path, o, cmd.stroke);
+					this.#stamp(o, path, id);
 					break;
 				}
 				case "fillText": {
-					const div = doc.createElement("div");
-					div.style.position = "absolute";
-					div.style.left = `${cmd.x}px`;
-					div.style.top = `${cmd.y}px`;
-					div.style.transform = "translateY(-0.8em)";
-					div.style.whiteSpace = "pre";
-					div.style.font = fontString(cmd.font);
-					if (cmd.font.fontVariationSettings !== void 0) div.style.fontVariationSettings = cmd.font.fontVariationSettings;
-					div.style.color = this.#solid(cmd.paint);
-					if (cmd.paint.kind !== "color") div.setAttribute("data-approx", "true");
-					if (cmd.align) div.style.textAlign = cmd.align;
-					div.textContent = cmd.text;
-					stamp(div, i);
-					cursor.appendChild(div);
+					const key = this.#keyFor(cursor, id, "fillText");
+					const o = this.#matchOrCreate(cursor, key, "fillText", () => {
+						const div = doc.createElement("div");
+						div.style.position = "absolute";
+						div.style.transform = "translateY(-0.8em)";
+						div.style.whiteSpace = "pre";
+						return {
+							op: "fillText",
+							el: div,
+							props: {}
+						};
+					});
+					const div = o.el;
+					this.#setStyle(o, div, "left", `${cmd.x}px`);
+					this.#setStyle(o, div, "top", `${cmd.y}px`);
+					this.#setStyle(o, div, "font", fontString(cmd.font));
+					this.#setStyle(o, div, "fontVariationSettings", cmd.font.fontVariationSettings !== void 0 ? cmd.font.fontVariationSettings : void 0);
+					this.#setStyle(o, div, "color", this.#solid(cmd.paint));
+					this.#setAttr(div, o, "dataApprox", "data-approx", cmd.paint.kind !== "color" ? "true" : void 0);
+					this.#setStyle(o, div, "textAlign", cmd.align !== void 0 ? cmd.align : void 0);
+					this.#setText(div, o, cmd.text);
+					this.#stamp(o, div, id);
 					break;
 				}
 				case "drawImage": {
 					const res = list.resources[cmd.image];
 					const assetId = res && (res.kind === "image" || res.kind === "videoFrame") ? res.assetId : void 0;
-					const img = doc.createElement("img");
-					img.style.position = "absolute";
-					img.style.left = `${cmd.dst.x}px`;
-					img.style.top = `${cmd.dst.y}px`;
-					img.style.width = `${cmd.dst.w}px`;
-					img.style.height = `${cmd.dst.h}px`;
-					img.style.objectFit = "fill";
-					if (cmd.smoothing === false) img.style.imageRendering = "pixelated";
-					if (assetId !== void 0) {
-						img.setAttribute("data-asset-id", assetId);
-						const src = this.#imageSrc(assetId);
-						if (src !== void 0) img.src = src;
+					const key = this.#keyFor(cursor, id, "drawImage");
+					const o = this.#matchOrCreate(cursor, key, "drawImage", () => {
+						const img = doc.createElement("img");
+						img.style.position = "absolute";
+						img.style.objectFit = "fill";
+						return {
+							op: "drawImage",
+							el: img,
+							props: {}
+						};
+					});
+					const img = o.el;
+					this.#setStyle(o, img, "left", `${cmd.dst.x}px`);
+					this.#setStyle(o, img, "top", `${cmd.dst.y}px`);
+					this.#setStyle(o, img, "width", `${cmd.dst.w}px`);
+					this.#setStyle(o, img, "height", `${cmd.dst.h}px`);
+					this.#setStyle(o, img, "imageRendering", cmd.smoothing === false ? "pixelated" : void 0);
+					this.#setAttr(img, o, "dataAssetId", "data-asset-id", assetId);
+					const src = assetId !== void 0 ? this.#imageSrc(assetId) : void 0;
+					if (src !== void 0 && o.props["src"] !== src) {
+						img.src = src;
+						o.props["src"] = src;
 					}
-					stamp(img, i);
-					cursor.appendChild(img);
+					this.#stamp(o, img, id);
 					break;
 				}
 				case "pushGroup": {
-					const wrap = doc.createElement("div");
-					wrap.style.position = "absolute";
-					wrap.style.left = "0";
-					wrap.style.top = "0";
-					if (cmd.opacity !== 1) wrap.style.opacity = String(cmd.opacity);
+					const key = this.#keyFor(cursor, id, "pushGroup");
+					const o = this.#matchOrCreate(cursor, key, "pushGroup", () => {
+						const wrap = doc.createElement("div");
+						wrap.style.position = "absolute";
+						wrap.style.left = "0";
+						wrap.style.top = "0";
+						return {
+							op: "pushGroup",
+							el: wrap,
+							props: {}
+						};
+					});
+					const wrap = o.el;
+					this.#setStyle(o, wrap, "opacity", cmd.opacity !== 1 ? String(cmd.opacity) : void 0);
 					const blend = blendToCss(cmd.blend);
-					if (blend !== "normal") wrap.style.mixBlendMode = blend;
-					if (cmd.filters.length > 0) wrap.style.filter = filtersToCanvasFilter(cmd.filters);
+					this.#setStyle(o, wrap, "mixBlendMode", blend !== "normal" ? blend : void 0);
+					this.#setStyle(o, wrap, "filter", cmd.filters.length > 0 ? filtersToCanvasFilter(cmd.filters) : void 0);
 					if (cmd.shader !== void 0 && !this.#warnedShader) {
 						emitDevWarning("@glissade/backend-dom: a ShaderEffect (pushGroup.shader) has no DOM analogue — ignored (caps.shaders=false).");
 						this.#warnedShader = true;
 					}
-					stamp(wrap, i);
-					cursor.appendChild(wrap);
+					this.#stamp(o, wrap, id);
 					stack.push(cursor);
+					scopeStack.push(scope);
 					cursor = wrap;
+					scope = scope + "/" + key;
+					this.#enterCursor(cursor, scope);
 					break;
 				}
 				case "popGroup":
+					this.#pruneCursor(cursor);
 					cursor = stack.pop() ?? this.root;
+					scope = scopeStack.pop() ?? "";
 					break;
 			}
 		});
+		if (cursor !== this.root) {
+			if (!this.#warnedUnbalanced) {
+				emitDevWarning("@glissade/backend-dom: render() ended with an unbalanced cursor (a transform/clip with no enclosing save/restore) — the DisplayList is malformed; draining open cursors.");
+				this.#warnedUnbalanced = true;
+			}
+			while (cursor !== this.root) {
+				this.#pruneCursor(cursor);
+				cursor = stack.pop() ?? this.root;
+			}
+		}
+		this.#pruneCursor(this.root);
 	}
 	measureText(text, font) {
 		const size = font.size;
@@ -303,6 +404,154 @@ var DomBackend = class {
 		this.#images.clear();
 		this.#videos.clear();
 	}
+	/** Get-or-create this cursor's recon record; reset per-render scratch once per
+	* frame (the first time a reused cursor is entered this render). */
+	#enterCursor(cursor, _scope) {
+		let rec = this.#recon.get(cursor);
+		if (!rec) {
+			rec = {
+				children: /* @__PURE__ */ new Map(),
+				owns: /* @__PURE__ */ new Set(),
+				occ: /* @__PURE__ */ new Map(),
+				seen: /* @__PURE__ */ new Set(),
+				frame: -1,
+				anchor: null
+			};
+			this.#recon.set(cursor, rec);
+		}
+		if (rec.frame !== this.#frame) {
+			rec.frame = this.#frame;
+			rec.occ.clear();
+			rec.seen.clear();
+			rec.anchor = cursor.firstChild;
+			while (rec.anchor && !rec.owns.has(rec.anchor)) rec.anchor = rec.anchor.nextSibling;
+		}
+		return rec;
+	}
+	/** Sibling-scoped key under one cursor: `(id|∅) op occ`. occ disambiguates a
+	* node that emits the same op twice and id-less nodes positionally. */
+	#keyFor(cursor, id, op) {
+		const rec = this.#recon.get(cursor);
+		const base = (id ?? "∅") + " " + op;
+		const n = rec.occ.get(base) ?? 0;
+		rec.occ.set(base, n + 1);
+		return base + " " + n;
+	}
+	/** Reuse the owned element for `key` under `cursor`, or create it via the
+	* factory. Place it (move-on-reorder, foreign-safe). The SOLE creation site. */
+	#matchOrCreate(cursor, key, op, create) {
+		const rec = this.#recon.get(cursor);
+		rec.seen.add(key);
+		let el = rec.children.get(key);
+		let o;
+		if (!el) {
+			o = create();
+			el = o.el;
+			rec.children.set(key, el);
+			rec.owns.add(el);
+			if (o.aux) rec.owns.add(o.aux);
+			this.#owned.set(el, o);
+		} else {
+			o = this.#owned.get(el);
+			if (o.op !== op) {
+				if (o.aux) rec.owns.delete(o.aux);
+				rec.owns.delete(el);
+				o.aux?.remove();
+				el.remove();
+				rec.children.delete(key);
+				this.#owned.delete(el);
+				o = create();
+				el = o.el;
+				rec.children.set(key, el);
+				rec.owns.add(el);
+				if (o.aux) rec.owns.add(o.aux);
+				this.#owned.set(el, o);
+			}
+		}
+		if (o.aux) this.#place(cursor, rec, o.aux);
+		this.#place(cursor, rec, el);
+		return o;
+	}
+	/** Place `node` at the running anchor, moving it only if out of place; then
+	* advance the anchor past it and over any interleaved FOREIGN siblings. */
+	#place(cursor, rec, node) {
+		if (node !== rec.anchor) {
+			const ae = this.#doc.activeElement;
+			if (ae === null || node !== ae && !node.contains(ae)) cursor.insertBefore(node, rec.anchor);
+		}
+		rec.anchor = node.nextSibling;
+		while (rec.anchor && !rec.owns.has(rec.anchor)) rec.anchor = rec.anchor.nextSibling;
+	}
+	/** Remove owned children of `cursor` not seen this frame. Iterates the
+	* children Map ONLY — foreign nodes are not keys, so they are unreachable. */
+	#pruneCursor(cursor) {
+		const rec = this.#recon.get(cursor);
+		if (!rec) return;
+		for (const [k, el] of rec.children) if (!rec.seen.has(k)) {
+			const o = this.#owned.get(el);
+			if (o?.aux) rec.owns.delete(o.aux);
+			rec.owns.delete(el);
+			o?.aux?.remove();
+			el.remove();
+			rec.children.delete(k);
+			this.#owned.delete(el);
+		}
+	}
+	/** Write a style prop only when it changed; clear (to default) on undefined. */
+	#setStyle(o, target, prop, value) {
+		if (o.props[prop] === value) return;
+		const style = target.style;
+		style[prop] = value ?? "";
+		o.props[prop] = value;
+	}
+	/** Write an attribute only when its cached slot changed; remove on undefined. */
+	#setAttr(target, o, slot, name, value) {
+		if (o.props[slot] === value) return;
+		if (value === void 0) target.removeAttribute(name);
+		else target.setAttribute(name, value);
+		o.props[slot] = value;
+	}
+	/** Stamp `data-node-id` (guarded) on the element S2 stamped per op. */
+	#stamp(o, el, id) {
+		if (id === void 0) return;
+		this.#setAttr(el, o, "nodeId", "data-node-id", id);
+	}
+	/**
+	* Caret-preserving text write. RULE B (freeze): never touch the text while the
+	* div (or a descendant) is the focused contentEditable. RULE A (patch-only):
+	* write nothing when unchanged; otherwise mutate the SAME Text node's `.data`
+	* (least-destructive — never `textContent=` on a retained subtree, which would
+	* collapse the caret / drop a selection).
+	*/
+	#setText(div, o, text) {
+		if (this.#isEditing(div)) return;
+		if (o.props["text"] === text) return;
+		let tn = null;
+		for (let n = div.firstChild; n; n = n.nextSibling) if (n.nodeType === 3) {
+			tn = n;
+			break;
+		}
+		if (tn) tn.data = text;
+		else div.appendChild(this.#doc.createTextNode(text));
+		o.props["text"] = text;
+	}
+	/** The div (or a descendant) is the focused contentEditable host. Uses the
+	* computed `isContentEditable` (real browsers) with an attribute fallback
+	* (jsdom and other environments that don't compute it). */
+	#isEditing(div) {
+		if (!(div.isContentEditable || div.getAttribute("contenteditable") === "true")) return false;
+		const active = this.#doc.activeElement;
+		return active === div || active !== null && active !== this.#doc.body && div.contains(active);
+	}
+	/** Map a `StrokeStyle` onto an SVG `<path>`'s stroke-* attributes (guarded). */
+	#applyStroke(path, o, stroke) {
+		this.#setAttr(path, o, "strokeWidth", "stroke-width", String(stroke.width));
+		this.#setAttr(path, o, "strokeCap", "stroke-linecap", stroke.cap);
+		this.#setAttr(path, o, "strokeJoin", "stroke-linejoin", stroke.join);
+		this.#setAttr(path, o, "strokeMiter", "stroke-miterlimit", stroke.miterLimit !== void 0 ? String(stroke.miterLimit) : void 0);
+		this.#setAttr(path, o, "strokeDash", "stroke-dasharray", stroke.dash && stroke.dash.length > 0 ? stroke.dash.join(" ") : void 0);
+		this.#setAttr(path, o, "strokeDashOff", "stroke-dashoffset", stroke.dashOffset !== void 0 ? String(stroke.dashOffset) : void 0);
+	}
 	#ensureMeasureSpan() {
 		if (this.#measureSpan) return this.#measureSpan;
 		const span = this.#doc.createElement("span");
@@ -327,14 +576,21 @@ var DomBackend = class {
 		if (paint.kind === "mesh") return paint.bg ?? paint.points[0]?.color ?? "#000";
 		return paint.stops[0]?.color ?? "#000";
 	}
-	/** Resolve a `Paint` to an SVG fill/stroke value, appending any gradient def to
-	* `svg`'s `<defs>`. `mesh` degrades to a solid (CSS/SVG has no mesh gradient);
-	* a degraded paint stamps `data-approx="true"` on `el` so an editor can badge
-	* the approximation (design-agent consumer ask). */
-	#resolvePaint(paint, svg, el) {
-		if (paint.kind === "color") return paint.color;
+	/** A signature of the gradient paint — a `<defs>` subtree is rebuilt only when
+	* this changes (kind / coords / stops), avoiding per-frame churn. */
+	#gradKey(paint) {
+		return `${paint.kind === "linear" ? `L|${paint.from ?? ""}|${paint.to ?? ""}` : `R|${paint.center ?? ""}|${paint.radius ?? ""}`}|${paint.stops.map((s) => `${s.offset}:${s.color}`).join(",")}`;
+	}
+	/** Resolve a `Paint` to an SVG fill/stroke value, building/refreshing the
+	* gradient `<defs>` on the owned svg (`o.el`) keyed by a deterministic def id.
+	* `mesh` degrades to a solid; a degraded paint stamps `data-approx="true"`. */
+	#resolvePaint(paint, o, scope, key) {
+		if (paint.kind === "color") {
+			this.#setAttr(o.path, o, "dataApprox", "data-approx", void 0);
+			return paint.color;
+		}
 		if (paint.kind === "mesh") {
-			el.setAttribute("data-approx", "true");
+			this.#setAttr(o.path, o, "dataApprox", "data-approx", "true");
 			if (!this.#warnedMesh) {
 				emitDevWarning("@glissade/backend-dom: mesh-gradient paint has no SVG analogue — degraded to a solid fill.");
 				this.#warnedMesh = true;
@@ -342,21 +598,32 @@ var DomBackend = class {
 			return this.#solid(paint);
 		}
 		if (paint.interpolation !== void 0 && paint.interpolation !== "linear") {
-			el.setAttribute("data-approx", "true");
+			this.#setAttr(o.path, o, "dataApprox", "data-approx", "true");
 			if (!this.#warnedGradientInterp) {
 				emitDevWarning(`@glissade/backend-dom: gradient interpolation '${paint.interpolation}' has no SVG analogue — degraded to linear stops.`);
 				this.#warnedGradientInterp = true;
 			}
+		} else this.#setAttr(o.path, o, "dataApprox", "data-approx", void 0);
+		const svg = o.el;
+		const defId = o.defId ?? (o.defId = "gsgrad_" + hashKey(scope + " " + key));
+		const sig = this.#gradKey(paint);
+		if (o.gradKey !== sig) {
+			o.gradKey = sig;
+			this.#buildGradient(svg, defId, paint);
 		}
+		return `url(#${defId})`;
+	}
+	/** (Re)build the gradient `<defs>` subtree for `defId` on `svg`. */
+	#buildGradient(svg, defId, paint) {
 		const doc = this.#doc;
-		const id = `gsgrad${this.#defCounter++}`;
 		let defs = svg.querySelector("defs");
 		if (!defs) {
 			defs = doc.createElementNS(SVG_NS, "defs");
 			svg.insertBefore(defs, svg.firstChild);
 		}
+		for (const g of Array.from(defs.children)) if (g.getAttribute("id") === defId) g.remove();
 		const grad = doc.createElementNS(SVG_NS, paint.kind === "radial" ? "radialGradient" : "linearGradient");
-		grad.setAttribute("id", id);
+		grad.setAttribute("id", defId);
 		if (paint.kind === "linear") {
 			if (paint.from && paint.to) {
 				grad.setAttribute("gradientUnits", "userSpaceOnUse");
@@ -378,17 +645,7 @@ var DomBackend = class {
 			grad.appendChild(s);
 		}
 		defs.appendChild(grad);
-		return `url(#${id})`;
 	}
 };
-/** Map a `StrokeStyle` onto an SVG `<path>`'s stroke-* attributes 1:1. */
-function applyStroke(path, stroke) {
-	path.setAttribute("stroke-width", String(stroke.width));
-	if (stroke.cap) path.setAttribute("stroke-linecap", stroke.cap);
-	if (stroke.join) path.setAttribute("stroke-linejoin", stroke.join);
-	if (stroke.miterLimit !== void 0) path.setAttribute("stroke-miterlimit", String(stroke.miterLimit));
-	if (stroke.dash && stroke.dash.length > 0) path.setAttribute("stroke-dasharray", stroke.dash.join(" "));
-	if (stroke.dashOffset !== void 0) path.setAttribute("stroke-dashoffset", String(stroke.dashOffset));
-}
 //#endregion
 export { DomBackend };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/backend-dom",
-  "version": "0.21.0-pre.0",
+  "version": "0.21.0-pre.2",
   "description": "glissade DOM render backend: DisplayList -> HTML/SVG elements. A preview / non-parity realtime tier (accessibility, selectable text, CSS-native embedding) — NOT a Skia-export twin.",
   "license": "Apache-2.0",
   "engines": {
@@ -18,8 +18,8 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/scene": "0.21.0-pre.0",
-    "@glissade/core": "0.21.0-pre.0"
+    "@glissade/core": "0.21.0-pre.2",
+    "@glissade/scene": "0.21.0-pre.2"
   },
   "repository": {
     "type": "git",