@glissade/backend-dom 0.23.0-pre.1 → 0.23.0-pre.2

package/README.md

@@ -136,11 +136,38 @@ base bundle is absent or a different version (never a cryptic `undefined`).
 The backend only ever manages its **own root** subtree — your overlay/foreign DOM
 in the host element is left untouched.
 
-## Status: Stage S2 (forward render)
-
-Today this is a **forward renderer**: each `render()` rebuilds the tree. That is
-right for **playback preview, structural snapshots, and a11y reads**. The
-**retained-DOM reconciler** (reuse + patch the same element per `data-node-id`
-across frames — required so an in-progress inline-edit caret, selection, focus,
-and event listeners survive a re-render) is **Stage S3**, a follow-up. See
-`docs/design/dom-backend.md`.
+## Accessibility & theming (S4)
+
+The DOM tier exists for editing + a11y, so it keeps the **real text** readable by
+assistive tech and hides the decorative geometry:
+
+- **Shape `<svg>` islands and `<img>` elements are `aria-hidden`** — a screen
+  reader reads the Text divs (the meaningful content), not the paths.
+- **`ariaLabel`** names the whole graphic: the root gets `role="figure"` +
+  `aria-label` (a labeled region whose readable text stays exposed — unlike
+  `role="img"`, which would hide the text). Unset ⇒ a generic container.
+- **Focus order** is the host/editor's to manage — every node carries
+  `data-node-id`, so an editor decides which nodes are focusable (`tabindex`)
+  rather than the backend imposing a tab order on every shape.
+
+```js
+const backend = new DomBackend(stage, {
+  ariaLabel: 'Episode 1 cold open',
+  cssColorVars: true, // emit colors as var(--gs-c-…, color) for re-theming
+});
+```
+
+**CSS-variable theming** (`cssColorVars`): solid fills/text colors emit as
+`var(--gs-c-<ident>, <color>)`, so a host can re-theme (light/dark, brand) by
+overriding the `--gs-c-*` variables in CSS — the browser re-paints with **no
+re-render**. Off by default (literal colors; byte-stable for existing consumers).
+Gradient stops are not yet varied (a follow-up).
+
+## Stages
+
+S2 (forward render) + **S3** (the retained-DOM reconciler — reuse + patch per
+`data-node-id` so inline-edit caret / selection / focus / listeners survive a
+re-render) + the 0.22 structural hardening (shape-sized SVG islands, rounded-rect
+fill, movement-boundary reconcile, `onReflow` font re-wrap) + **S4** (a11y +
+CSS-native theming, above) have all shipped. The real-browser visual-smoke gate
+runs in the consumer canaries' standing harnesses. See `docs/design/dom-backend.md`.

package/dist/index.d.ts

@@ -13,6 +13,21 @@ interface DomBackendOptions {
    * draw loop. No-op where `document.fonts` is absent (e.g. jsdom).
    */
   onReflow?: () => void;
+  /**
+   * S4 a11y: an accessible name for the whole rendered graphic. When set, the
+   * root gets `role="figure"` + `aria-label` (a labeled region whose readable
+   * text stays in the a11y tree). Decorative geometry (the SVG shape islands +
+   * images) is always `aria-hidden`, so a screen reader reads the Text, not the
+   * paths. Unset ⇒ the root carries no role (a generic container).
+   */
+  ariaLabel?: string;
+  /**
+   * S4 theming: emit solid colors as CSS custom properties — `var(--gs-c-<ident>,
+   * <color>)` — so a host can re-theme (light/dark, brand) by overriding the
+   * `--gs-c-*` variables in CSS, **without a re-render** (the browser re-paints).
+   * Default off ⇒ literal colors (byte-stable for existing consumers).
+   */
+  cssColorVars?: boolean;
 }
 /**
  * A DOM/SVG `RenderBackend`. Construct with a host element (renders into it) or a

package/dist/index.js

@@ -158,6 +158,8 @@ var DomBackend = class {
 	#owned = /* @__PURE__ */ new WeakMap();
 	#ids = [];
 	#onReflow;
+	/** S4: wrap solid colors in `var(--gs-c-…, color)` so a host re-themes via CSS. */
+	#cssColorVars;
 	#measureSpan = null;
 	#warnedMeasure = false;
 	#warnedMesh = false;
@@ -172,8 +174,13 @@ var DomBackend = class {
 		this.root.setAttribute("data-gs-dom", "");
 		this.root.style.position = "relative";
 		this.root.style.overflow = "hidden";
+		if (opts.ariaLabel !== void 0) {
+			this.root.setAttribute("role", "figure");
+			this.root.setAttribute("aria-label", opts.ariaLabel);
+		}
 		if (this.#host) this.#host.appendChild(this.root);
 		this.#onReflow = opts.onReflow;
+		this.#cssColorVars = opts.cssColorVars ?? false;
 		this.#wireFontReflow();
 	}
 	/**
@@ -236,6 +243,7 @@ var DomBackend = class {
 			const svg = doc.createElementNS(SVG_NS, "svg");
 			svg.setAttribute("width", "0");
 			svg.setAttribute("height", "0");
+			svg.setAttribute("aria-hidden", "true");
 			svg.style.position = "absolute";
 			svg.style.left = "0";
 			svg.style.top = "0";
@@ -397,6 +405,8 @@ var DomBackend = class {
 						const img = doc.createElement("img");
 						img.style.position = "absolute";
 						img.style.objectFit = "fill";
+						img.setAttribute("alt", "");
+						img.setAttribute("aria-hidden", "true");
 						return {
 							op: "drawImage",
 							el: img,
@@ -716,9 +726,19 @@ var DomBackend = class {
 		if (a && typeof a === "object" && "src" in a && typeof a.src === "string") return a.src;
 	}
 	#solid(paint) {
-		if (paint.kind === "color") return paint.color;
-		if (paint.kind === "mesh") return paint.bg ?? paint.points[0]?.color ?? "#000";
-		return paint.stops[0]?.color ?? "#000";
+		const color = paint.kind === "color" ? paint.color : paint.kind === "mesh" ? paint.bg ?? paint.points[0]?.color ?? "#000" : paint.stops[0]?.color ?? "#000";
+		return this.#themeColor(color);
+	}
+	/**
+	* S4 theming: when `cssColorVars` is on, wrap a literal color in a CSS custom
+	* property `var(--gs-c-<ident>, <color>)` so a host re-themes by overriding the
+	* `--gs-c-*` vars in CSS — no re-render (the browser re-paints). Off ⇒ the
+	* literal color (byte-stable). The ident is the color with non-ident runs
+	* collapsed to '-' (`'#89b4fa'` → `89b4fa`, `'rgb(1,2,3)'` → `rgb-1-2-3`).
+	*/
+	#themeColor(color) {
+		if (!this.#cssColorVars) return color;
+		return `var(--gs-c-${color.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "")}, ${color})`;
 	}
 	/** A signature of the gradient paint — a `<defs>` subtree is rebuilt only when
 	* this changes (kind / coords / stops), avoiding per-frame churn. */
@@ -731,7 +751,7 @@ var DomBackend = class {
 	#resolvePaint(paint, o, scope, key) {
 		if (paint.kind === "color") {
 			this.#setAttr(o.path, o, "dataApprox", "data-approx", void 0);
-			return paint.color;
+			return this.#themeColor(paint.color);
 		}
 		if (paint.kind === "mesh") {
 			this.#setAttr(o.path, o, "dataApprox", "data-approx", "true");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/backend-dom",
-  "version": "0.23.0-pre.1",
+  "version": "0.23.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.23.0-pre.1",
-    "@glissade/core": "0.23.0-pre.1"
+    "@glissade/core": "0.23.0-pre.2",
+    "@glissade/scene": "0.23.0-pre.2"
   },
   "repository": {
     "type": "git",