domotion-svg 0.29.0 → 0.30.1

package/FEATURES.md

@@ -5,6 +5,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 ## Rendering Features
 
 ### Text
+
 - [x] **text-basic**: Plain text rendering (font-size, font-family, color)
 - [x] **text-bold**: Bold/weight text
 - [x] **text-center**: Centered text (text-align: center)
@@ -18,6 +19,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **text-font-stretch-underline**: CSS `font-stretch` end to end — condensed/expanded cut selection for declared families (Blink's trait-based style matcher), the `wdth` variation axis on the macOS `system-ui` face and variable webfonts, and decoration metrics resolved on the same width-matched face as the glyphs
 
 ### Backgrounds & Colors
+
 - [x] **bg-solid**: Solid background colors
 - [x] **bg-transparent**: Semi-transparent backgrounds (rgba)
 - [x] **bg-nested**: Nested backgrounds (child on top of parent)
@@ -26,12 +28,14 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [ ] **bg-dark-mode** (DM-455, doc 29): Dark-mode capture support — caller-chosen `colorScheme`, dark form-control palette, scheme-aware transparent-root fallback
 
 ### Borders
+
 - [x] **border-solid**: Solid borders with color
 - [x] **border-radius**: Rounded corners
 - [x] **border-radius-pill**: Fully rounded (pill shape)
 - [x] **inline-box-decoration-break**: wrapped inline backgrounds / borders paint per line-fragment (`slice` + `clone`); first/last fragment own the start/end edges in slice mode, every fragment paints a full box in clone mode
 
 ### Layout
+
 - [x] **layout-flex-row**: Horizontal flex layout with gap
 - [x] **layout-flex-col**: Vertical flex layout
 - [x] **layout-flex-center**: Centered content (justify-content/align-items)
@@ -43,6 +47,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **animated-projective-frame-state** (DM-2359/DM-2356/DM-2492/DM-2493, docs 186/189): `animationTimeMs` exactly pauses document timelines before all capture prepasses and exposes the CDP quad, composed 3D state, residual, and selected atomic raster owner without a fitted 2D approximation. Same-frame used-preserve facts select Blink's direct-parent rendering-context root; a strict 25-family/four-profile native three-OS DPR-1/2 gate rejects larger crops, warnings, restoration drift, incomplete evidence, and nine ownership mutations.
 
 ### Components
+
 - [x] **comp-button**: Button with background, border, padding, text
 - [x] **comp-badge**: Small badge with colored background and text
 - [x] **comp-card**: Card with background, border, radius, content
@@ -54,17 +59,21 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [ ] **comp-nav**: Navigation bar with logo and links
 
 ### SVG
+
 - [x] **svg-inline**: Inline SVG elements are cloned as self-contained vectors; CSS-only clip/mask effects preserve native fill-box, stroke-box, and view-box resolution (DM-2328)
 - [x] **clip-path-url-reference-ownership** (DM-2362, docs 39/130): bare same-document/external URL clips preserve HTML border/object-bounding-box and SVG forced-fill ownership; Blink-invalid URL-plus-box declarations stay inactive, including stale captured trees and nested frames.
 
 ### Masks
+
 - [x] **mask-contain-cover-arbitrary-position** (DM-2379, doc 20): URL masks capture Chromium-decoded intrinsic ratios and emit concrete Blink-fitted rectangles for percentage, length, and calc positions; zoom/DPR, physical writing axes, multilayer, and slice/clone fragment controls reject the retired SVG Min/Mid/Max buckets.
 
 ### Text effects
+
 - [x] **text-bg-clip-gradient** (DM-462): `background-clip: text` + `-webkit-text-fill-color: transparent` — gradient fills the glyph shapes via SVG `<mask>` over the bg-color rect
 - [x] **pseudo-filter-functions** (DM-2367, doc 38): generated empty/text/image paint supports blur, drop-shadow, brightness, contrast, grayscale, hue-rotate, invert, opacity, saturate, sepia, and ordered lists through Chromium's native SVG CSS-filter pipeline; identity/none, transform, clip, stack slot, zoom, DPR, and filter-stripped mutation controls are browser-gated.
 
 ### Replaced elements (rasterized as static snapshot — DM-457)
+
 - [x] **replaced-canvas-shape**: `<canvas>` with drawn shapes — bitmap survives via `page.screenshot`
 - [x] **replaced-video-poster**: `<video poster=…>` paused — poster image captured
 - [x] **replaced-canvas-overlay**: `<canvas>` under a positioned `<div z-index:10>` overlay — overlay does NOT bleed into the canvas snapshot
@@ -79,11 +88,13 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **snapshot-isolation-pseudo-overlay** (DM-458, `tests/snapshot-isolation.tsx`): canvas covered by a sibling's `::after` pseudo overlay. Inspection-style — decodes the captured snapshot's PNG data URI and asserts no overlay-color pixels leaked through. Catches regressions in the hide-everything-else stylesheet that a comparison-style fixture wouldn't.
 
 ### Showcase Integration Tests
+
 - [x] **showcase-typography**: Full-page layout with headings, badges, code blocks, inline code, status text
 - [x] **showcase-cards**: Card list with badges, buttons, metadata
 - [x] **showcase-forms**: Publish form with labels, inputs, pre block, button
 
 ### Composed Parity Integration Tests
+
 - [x] **composed-multilingual-flex-grid**: Platform fallback and bidi isolation inside flex/grid messaging UI, with neutral-wrapper and node-split relations
 - [x] **composed-responsive-fragmented-controls**: Native controls inside responsive multicol layout with equivalent grid syntax
 - [x] **composed-gradient-mask-clip-stacking**: Gradients, masks, and clips under explicit stacking ownership and reversed DOM order
@@ -97,6 +108,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 Tests are defined in `tests/features.ts` (26 feature tests) and `tests/showcase.ts` (3 integration tests). Both use the shared runner in `tests/runner.ts`.
 
 For each test case:
+
 1. Define an HTML snippet (feature tests) or full-page HTML (showcase tests) exercising the feature
 2. Render the HTML in Playwright (Chromium) and capture as PNG ("expected")
 3. Capture the DOM via `captureElementTree` on the Playwright page

package/README.md

@@ -14,7 +14,7 @@
 
 **Domotion turns real HTML/CSS into one self-contained, animated SVG** — an accurate reproduction of the rendered page, with optional animation and simulated interaction built in. It embeds the exact captured glyph data and positioning, so playback never falls back to a viewer's system fonts; the output scales crisply at any size and embeds anywhere with a plain `<img>`, no external assets.
 
-Beyond raw capture it ships a **template library** that turns a few flags into a polished animated SVG, **terminal-session capture** (a recording → an animated terminal), **scroll capture** (a long page replayed as one self-contained scrolling SVG), multi-frame **animation** with parameterized and custom transitions, overlays, and simulated interaction, **scene storyboarding** (sequence distinct scenes end-to-end), **brand kits** and **social-format presets** (reel / square / portrait / landscape), **device-chrome** framing, **nested compositing** (animated layers inside animated layers), one-command **SVG → MP4/WebM**, and a fidelity **review** tool.
+Beyond raw capture it ships **Domotion Studio**, a local visual workspace for authoring and reviewing versioned projects; a **template library** that turns a few flags into a polished animated SVG; **terminal-session capture** (a recording → an animated terminal); **scroll capture** (a long page replayed as one self-contained scrolling SVG); multi-frame **animation** with parameterized and custom transitions, overlays, and simulated interaction; **scene storyboarding** (sequence distinct scenes end-to-end); **brand kits** and **social-format presets** (reel / square / portrait / landscape); **device-chrome** framing; **nested compositing** (animated layers inside animated layers); one-command **SVG → MP4/WebM**; and fidelity **review** tools.
 
 <p align="center">
   <img src="examples/output/hero-product-demo.svg" alt="An analytics dashboard assembling itself inside a browser window — KPI cards rise in, a bar chart grows with its peak highlighted, a search query types itself, and a nav item is clicked — all in one self-contained animated SVG" width="760">
@@ -65,6 +65,8 @@ predictable. For a zero-install trial, run
   [animation guide](https://brianwestphal.github.io/domotion/usage/animate/).
 - **Generate a polished asset from flags:** use `domotion template`; browse the
   [template guide](https://brianwestphal.github.io/domotion/usage/templates/).
+- **Author and review a versioned project visually:** use `domotion-studio`; see
+  the [Studio guide](https://brianwestphal.github.io/domotion/usage/studio/).
 
 The [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/)
 walks through the first capture and animation end to end.
@@ -97,6 +99,12 @@ never become idle.
 
 Same-origin `<iframe>` content is recursed into the capture as native SVG rather than flattened to a screenshot; opt into cross-origin frames you trust with `--cross-origin-frames "<hosts>"`.
 
+Text defaults to self-contained, pixel-faithful embedded fonts. For inline SVG,
+`--real-text` adds a paintless authored-text layer for search, selection, copy,
+and assistive technology. `--text-mode system-font` instead paints authored
+`<text>` using the viewer's installed fonts; it can be smaller, but it is not
+pixel-faithful and should be used only when those fonts are guaranteed.
+
 For a multi-frame animated SVG, write a JSON config and run:
 
 ```bash
@@ -126,6 +134,24 @@ domotion template kinetic-text --text "Ship it" --variant pop --by char -o title
 
 Built-ins (14): **lower-third** (broadcast banner) · **kinetic-text** (animated typography) · **chart** (column / bar / line / pie / donut) · **chat** (message thread) · **subscribe** (follow pop-up) · **background-loop** (seamless looping background) · **device-mockup** (wrap a page in a phone / browser / window bezel) · and a **creative-template pack** of full-bleed text/number cards: **title-card**, **quote**, **caption**, **cta**, **counter**, **stat**, **compare**. Every template adapts to a `--format` social preset (reel / square / portrait / landscape) and a `--brand` kit (palette / type / logo). Third-party templates are npm packages named `domotion-template-<name>`.
 
+### Domotion Studio — visual project authoring
+
+Domotion Studio is a local, browser-based workspace for building and reviewing
+versioned Domotion projects. It provides story and scene authoring, a detailed
+multitrack timeline, embedded playback and review annotations, real-interaction
+import, and generation/review hooks while keeping project files as portable,
+validated JSON inside an explicitly scoped workspace.
+
+```bash
+# Open a workspace, or pass an existing Studio project JSON file.
+domotion-studio --workspace ./demo-project
+domotion-studio ./demo-project/product-tour.json
+```
+
+Studio opens locally by default. In automation, pass `--no-open` and use the
+printed loopback URL. Run `domotion-studio --help` or read the
+[Studio guide](https://brianwestphal.github.io/domotion/usage/studio/).
+
 ### Terminal sessions
 
 Turn a recorded terminal session into a self-contained animated SVG — real text, real color, native SVG (no raster frames). Record with [asciinema](https://asciinema.org), then convert:
@@ -186,7 +212,7 @@ writes the final `actual.svg`, one shared HAR, and an `expected.png` plus
 `captured-tree.json` for each composed frame. Use `--debug-dir <path>` to choose
 the bundle location.
 
-For an *animated* SVG, the package also ships `svg-scrubber` — a local video-style bench to play / pause / scrub / mark an in-out range, export the current frame as PNG, export the range as MP4, or trim it to a new self-contained animated SVG. Add `--review` to file a focused issue against a moment in the timeline: it writes an importable `.ticket` (frame time, range, and drawn regions) the same way `svg-review` builds a report for a still.
+For an _animated_ SVG, the package also ships `svg-scrubber` — a local video-style bench to play / pause / scrub / mark an in-out range, export the current frame as PNG, export the range as MP4, or trim it to a new self-contained animated SVG. Add `--review` to file a focused issue against a moment in the timeline: it writes an importable `.ticket` (frame time, range, and drawn regions) the same way `svg-review` builds a report for a still.
 
 ### Scripting API
 
@@ -238,7 +264,7 @@ npm run demos:examples  # run the bundled example demo scripts
 - `FEATURES.md` — per-feature support checklist with links to test fixtures.
 - `docs/` — requirements docs covering rendering fidelity, supported CSS features, and known caveats.
 - [`llms.txt`](llms.txt) — a concise, self-contained guide for **AI agents using Domotion as a tool** (Claude, Cursor, etc.): the CLIs, config schema, template library, API, gotchas, and a required rendered-pixel/video review gate before an SVG is handed back. Point your agent at it.
-- `CLAUDE.md` — guidance for AI assistants working *on this repo's* source (different audience from `llms.txt`).
+- `CLAUDE.md` — guidance for AI assistants working _on this repo's_ source (different audience from `llms.txt`).
 
 ## License
 

package/assets/fonts/fixture/README.md

@@ -24,10 +24,10 @@ Chrome's layout, `registerWebfont` for Domotion's outlines).
 
 ## Provenance
 
-| File | Upstream | License |
-|---|---|---|
-| `DomotionFixtureMono-Regular.ttf` | [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) Regular | SIL OFL 1.1 — `LICENSE-jetbrains-mono.txt` |
-| `DomotionFixtureSerif-Regular.ttf` | [IBM Plex Serif](https://github.com/IBM/plex) Regular | SIL OFL 1.1 — `LICENSE-ibm-plex-serif.txt` |
+| File                               | Upstream                                                             | License                                    |
+| ---------------------------------- | -------------------------------------------------------------------- | ------------------------------------------ |
+| `DomotionFixtureMono-Regular.ttf`  | [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) Regular | SIL OFL 1.1 — `LICENSE-jetbrains-mono.txt` |
+| `DomotionFixtureSerif-Regular.ttf` | [IBM Plex Serif](https://github.com/IBM/plex) Regular                | SIL OFL 1.1 — `LICENSE-ibm-plex-serif.txt` |
 
 Both are unmodified apart from being subsetted to the characters the fixtures
 paint. The OFL permits redistribution of modified copies under a reserved-name

package/dist/animation/caret-metrics.js

@@ -90,7 +90,13 @@ export function caretShapeRect(inp) {
         case "block":
             return { x: leftOf(cellW), y: boxTop, width: cellW, height: boxHeight, opacity: BLOCK_CARET_ALPHA };
         case "underscore":
-            return { x: leftOf(cellW), y: inp.baselineY, width: cellW, height: underscoreCaretThicknessPx(inp.fontSize), opacity: 1 };
+            return {
+                x: leftOf(cellW),
+                y: inp.baselineY,
+                width: cellW,
+                height: underscoreCaretThicknessPx(inp.fontSize),
+                opacity: 1,
+            };
         case "bar":
         default: {
             const barW = inp.barWidthPx ?? DEFAULT_CARET_WIDTH_PX;
@@ -148,9 +154,7 @@ export function firstLineBaseline(m) {
     const descentPx = fontBox > 0 ? Math.round(m.fontDescentPx) : m.fontSize * 0.25;
     const textBoxHeight = ascentPx + descentPx;
     const lineH = m.lineHeightPx || fontBox || m.fontSize * 1.2;
-    const lineTop = m.centerInContentBox
-        ? m.contentTop + Math.max(0, (m.contentHeight - lineH) / 2)
-        : m.contentTop;
+    const lineTop = m.centerInContentBox ? m.contentTop + Math.max(0, (m.contentHeight - lineH) / 2) : m.contentTop;
     const boxTop = lineTop + Math.floor((lineH - textBoxHeight) / 2);
     return { baselineY: boxTop + ascentPx, ascentPx, descentPx };
 }

package/dist/animation/caret-track.js

@@ -39,7 +39,7 @@
  * (docs/100, Primitive 1), which owns the glyphs and can interleave layers.
  */
 import { caretShapeRect, BLOCK_CARET_ALPHA, DEFAULT_CARET_WIDTH_PX } from "./caret-metrics.js";
-import { resolveCaretPoint, resolveRangeRects, findAddressedElement } from "./text-address.js";
+import { resolveCaretPoint, resolveRangeRects, findAddressedElement, } from "./text-address.js";
 import { renderTextAsPath } from "../render/text-to-path.js";
 import { withRenderTextMode } from "../render/font-resolution.js";
 /** The standard caret blink period (ms) — the terminal cursor's 1.06 s cycle. */
@@ -169,7 +169,13 @@ function resolveCoveredGlyph(roots, target, charOffset) {
     for (const run of runs) {
         for (const ch of run.text) {
             if (remaining === 0) {
-                return { char: ch, fontFamily: run.fontFamily, fontWeight: run.fontWeight, fontStyle: run.fontStyle, fontSize: run.fontSize };
+                return {
+                    char: ch,
+                    fontFamily: run.fontFamily,
+                    fontWeight: run.fontWeight,
+                    fontStyle: run.fontStyle,
+                    fontSize: run.fontSize,
+                };
             }
             remaining--;
         }
@@ -330,8 +336,12 @@ function invertedCaretMarkup(track, uid, kf, totalDurationMs, totalSec) {
             // The glyph is repainted at the CELL's left edge, which is the caret x
             // for an LTR insertion point and `x − cellWidth` for an RTL one.
             renderTextAsPath(cg.char, g.x, g.y, {
-                fontSize: cg.fontSize, fontFamily: cg.fontFamily, fontWeight: cg.fontWeight,
-                fill: glyphInk, fontStyle: cg.fontStyle, ascentOverride: wp.point.ascentPx,
+                fontSize: cg.fontSize,
+                fontFamily: cg.fontFamily,
+                fontWeight: cg.fontWeight,
+                fill: glyphInk,
+                fontStyle: cg.fontStyle,
+                ascentOverride: wp.point.ascentPx,
             }));
             glyphMarkup = gm;
         }
@@ -410,7 +420,7 @@ function selectionMarkup(sel, si, uid, kf, totalDurationMs, totalSec) {
         // Sweep anchor: the rect's leading edge in reading order. `edges` are the
         // successive trailing edges, so the swept extent is their distance from it.
         const rtl = rect.rtl === true;
-        const anchor = vertical ? rect.y : (rtl ? rect.x + rect.width : rect.x);
+        const anchor = vertical ? rect.y : rtl ? rect.x + rect.width : rect.x;
         const sweptTo = (edge) => (rtl && !vertical ? anchor - edge : edge - anchor);
         const stops = [`0%{${prop}:0.01px}`];
         if (startMs > 0)
@@ -448,9 +458,7 @@ function selectionMarkup(sel, si, uid, kf, totalDurationMs, totalSec) {
         const place = rtl && !vertical
             ? `x="0" y="${num(rect.y)}" transform="translate(${num(anchor)},0) scale(-1,1)"`
             : `x="${num(rect.x)}" y="${num(rect.y)}"`;
-        const size = vertical
-            ? `width="${num(rect.width)}" height="0.01"`
-            : `width="0.01" height="${num(rect.height)}"`;
+        const size = vertical ? `width="${num(rect.width)}" height="0.01"` : `width="0.01" height="${num(rect.height)}"`;
         parts.push(`    <rect class="tt-sel" ${place} ${size} fill="${sel.color}" style="animation:${name} ${totalSec.toFixed(2)}s ${timing} infinite"/>`);
         sweptBefore += rect.edges.length;
     }

package/dist/animation/composite.js

@@ -55,10 +55,13 @@ function innerOf(svg) {
 function resolveClipOriginPx(origin, base, size) {
     switch (origin) {
         case "left":
-        case "top": return base;
+        case "top":
+            return base;
         case "right":
-        case "bottom": return base + size;
-        case "center": return base + size / 2;
+        case "bottom":
+            return base + size;
+        case "center":
+            return base + size / 2;
     }
     const pct = /^([-\d.]+)%$/.exec(origin);
     if (pct != null)
@@ -71,11 +74,16 @@ function resolveClipOriginPx(origin, base, size) {
 /** Render a non-clip layer-animation endpoint to its CSS value (transform string / opacity). */
 function renderAnimValue(property, v) {
     switch (property) {
-        case "scale": return `scale(${v})`;
-        case "translateX": return `translateX(${typeof v === "number" ? `${v}px` : v})`;
-        case "translateY": return `translateY(${typeof v === "number" ? `${v}px` : v})`;
-        case "opacity": return `${v}`;
-        case "transform": return `${v}`;
+        case "scale":
+            return `scale(${v})`;
+        case "translateX":
+            return `translateX(${typeof v === "number" ? `${v}px` : v})`;
+        case "translateY":
+            return `translateY(${typeof v === "number" ? `${v}px` : v})`;
+        case "opacity":
+            return `${v}`;
+        case "transform":
+            return `${v}`;
     }
 }
 /**
@@ -100,9 +108,9 @@ export function composeAnimatedLayers(layers, opts) {
     });
     // Resolve each layer's geometry + intrinsic size first so we can size the master.
     const resolved = layers.map((layer, i) => {
-        const intrinsic = (layer.contentWidth != null && layer.contentHeight != null)
+        const intrinsic = layer.contentWidth != null && layer.contentHeight != null
             ? { w: layer.contentWidth, h: layer.contentHeight }
-            : parseSvgIntrinsicSize(layer.svg) ?? { w: 0, h: 0 };
+            : (parseSvgIntrinsicSize(layer.svg) ?? { w: 0, h: 0 });
         const w = layer.width ?? intrinsic.w;
         const h = layer.height ?? intrinsic.h;
         const x = layer.x ?? 0;
@@ -140,8 +148,11 @@ export function composeAnimatedLayers(layers, opts) {
         // 2. …then re-anchor its internal timeline to its own start within the master.
         if (r.period > 0) {
             content = offsetEmbeddedAnimatedSvgTimeline(content, {
-                periodMs: r.period, startMs: r.start, masterMs: master,
-                mode: r.mode, windowMs: r.windowMs,
+                periodMs: r.period,
+                startMs: r.start,
+                masterMs: master,
+                mode: r.mode,
+                windowMs: r.windowMs,
             });
         }
         // 3. Strip the outer wrapper and re-nest at the layer's box (a nested <svg>

package/dist/animation/compressed-run.d.ts

@@ -117,6 +117,17 @@ export interface CompressedRunOptions {
     /** Paint a root background rect first (e.g. the captured
      *  `styles.rootBgComputed`). Omit for a transparent run. */
     background?: string;
+    /**
+     * DM-6SQXGF: append the paintless real-text layer (doc 260) to the run. A
+     * compressed run flattens N states into ONE emission (shared content once,
+     * step-end birth/shift/recolor tracks) — there are no per-frame visibility
+     * groups to gate per-state text, and the glyph births use `opacity` (still
+     * find-in-page-visible). So the run emits ONE layer from the FINAL state's
+     * tree (the completed content — a stable deduplicated story flow), and the
+     * visible chrome+glyph runs are `aria-hidden` while it owns semantics.
+     * Intermediate typing prefixes are deliberately not exposed. Default off.
+     */
+    realText?: boolean;
     /** Emit the auto-caret track derived from the per-state edit points
      *  (docs/101 machinery). Default false — the config surface decides
      *  defaults later. */

package/dist/animation/compressed-run.js

@@ -105,9 +105,10 @@
 import { elementTreeToSvgInner } from "../render/element-tree-to-svg.js";
 import { paintOrderHitSequence } from "../render/paint-order.js";
 import { clearEmbeddedFonts, clearGlyphDefs, getEmbeddedFontFaceCss } from "../render/index.js";
+import { renderRealTextLayer, withRealTextLayerVisualSemantics } from "../render/real-text-layer.js";
 import { IDENTITY_TEXT_AFFINE, prepareAffineTextPaint, textAffineEquals } from "../render/text-affine.js";
 import { alignLineGlyphs } from "./glyph-align.js";
-import { textTrackMarkup, CARET_BLINK_MS, DEFAULT_SELECTION_COLOR } from "./caret-track.js";
+import { textTrackMarkup, CARET_BLINK_MS, DEFAULT_SELECTION_COLOR, } from "./caret-track.js";
 import { DEFAULT_CARET_WIDTH_PX } from "./caret-metrics.js";
 import { resolveRangeRects } from "./text-address.js";
 // ── Small helpers ───────────────────────────────────────────────────────────
@@ -156,8 +157,10 @@ function paintsBox(el) {
     if (s.backgroundImage != null && s.backgroundImage !== "none" && s.backgroundImage !== "")
         return true;
     const side = (w, st) => num(w) > 0 && st !== "none" && st != null;
-    if (side(s.borderTopWidth, s.borderTopStyle) || side(s.borderRightWidth, s.borderRightStyle)
-        || side(s.borderBottomWidth, s.borderBottomStyle) || side(s.borderLeftWidth, s.borderLeftStyle))
+    if (side(s.borderTopWidth, s.borderTopStyle) ||
+        side(s.borderRightWidth, s.borderRightStyle) ||
+        side(s.borderBottomWidth, s.borderBottomStyle) ||
+        side(s.borderLeftWidth, s.borderLeftStyle))
         return true;
     if (s.boxShadow != null && s.boxShadow !== "none" && s.boxShadow !== "")
         return true;
@@ -165,7 +168,23 @@ function paintsBox(el) {
         return true;
     if (el.elementRaster != null)
         return true;
-    const REPLACED = new Set(["img", "canvas", "video", "svg", "iframe", "embed", "object", "picture", "input", "textarea", "select", "button", "progress", "meter", "hr"]);
+    const REPLACED = new Set([
+        "img",
+        "canvas",
+        "video",
+        "svg",
+        "iframe",
+        "embed",
+        "object",
+        "picture",
+        "input",
+        "textarea",
+        "select",
+        "button",
+        "progress",
+        "meter",
+        "hr",
+    ]);
     return REPLACED.has(el.tag);
 }
 function maxBorderRadius(el) {
@@ -212,8 +231,7 @@ function segmentEligible(seg) {
     // they proved inert: no PNG was materialized and the ordinary glyph remains
     // the sole paint. Only a real overlay or the zero-area ::first-letter
     // suppression marker changes rendering and must stay in the chrome layer.
-    if (seg.rasterGlyphs?.some((glyph) => glyph.dataUri != null
-        || (glyph.suppressGlyph === true && glyph.rect.width === 0 && glyph.rect.height === 0)))
+    if (seg.rasterGlyphs?.some((glyph) => glyph.dataUri != null || (glyph.suppressGlyph === true && glyph.rect.width === 0 && glyph.rect.height === 0)))
         return false;
     if (seg.dottedCircleMarks != null && seg.dottedCircleMarks.length > 0)
         return false;
@@ -237,8 +255,7 @@ function textPlaneForCompression(el) {
     // The compressor emits absolute glyph coordinates and its own translation
     // tracks. A non-identity residual would need matrix-aware track composition;
     // keep that text in the byte-safe chrome flipbook until such support exists.
-    if (prepared.residualMatrix != null
-        && !textAffineEquals(prepared.residualMatrix, IDENTITY_TEXT_AFFINE))
+    if (prepared.residualMatrix != null && !textAffineEquals(prepared.residualMatrix, IDENTITY_TEXT_AFFINE))
         return null;
     return prepared.element;
 }
@@ -269,9 +286,10 @@ function elementTextEligible(el, textEl, ctx) {
             return false;
         for (const clip of ctx.clips) {
             const inset = clip.inset;
-            if (seg.x < clip.x + inset - 0.5 || seg.y < clip.y + inset - 0.5
-                || seg.x + seg.width > clip.x + clip.w - inset + 0.5
-                || seg.y + seg.height > clip.y + clip.h - inset + 0.5)
+            if (seg.x < clip.x + inset - 0.5 ||
+                seg.y < clip.y + inset - 0.5 ||
+                seg.x + seg.width > clip.x + clip.w - inset + 0.5 ||
+                seg.y + seg.height > clip.y + clip.h - inset + 0.5)
                 return false;
         }
     }
@@ -499,16 +517,26 @@ function extractState(tree, regionRootIds, demoted) {
                 for (const ch of seg.text) {
                     const x = xs[u];
                     const nextU = u + ch.length;
-                    let advance = nextU < seg.text.length ? xs[nextU] - x : (seg.width > 0 ? seg.x + seg.width - x : 0);
+                    let advance = nextU < seg.text.length ? xs[nextU] - x : seg.width > 0 ? seg.x + seg.width - x : 0;
                     if (!(advance > 0))
                         advance = fontSize * 0.6;
                     const isWs = WS_RE.test(ch);
                     glyphs.push({
-                        ch, x, advance,
-                        lineKey: lineKeyOf(ctx.region, seg.y), region: ctx.region, segY: seg.y, segHeight: seg.height,
-                        fill: isWs ? "" : fillResolved, isWs, styleKey,
-                        fontSize, ascent, descent,
-                        srcEl: textEl, srcSeg: seg,
+                        ch,
+                        x,
+                        advance,
+                        lineKey: lineKeyOf(ctx.region, seg.y),
+                        region: ctx.region,
+                        segY: seg.y,
+                        segHeight: seg.height,
+                        fill: isWs ? "" : fillResolved,
+                        isWs,
+                        styleKey,
+                        fontSize,
+                        ascent,
+                        descent,
+                        srcEl: textEl,
+                        srcSeg: seg,
                     });
                     u = nextU;
                 }
@@ -590,10 +618,20 @@ function lineSignature(items) {
 function pairBuckets(live, next) {
     const result = [];
     const liveArr = [...live.entries()]
-        .map(([k, glyphs]) => ({ k, glyphs, y: liveBucketY(glyphs), sig: lineSignature(glyphs.map((t) => ({ ch: t.rec.ch, styleKey: t.rec.styleKey, x: t.xs[t.xs.length - 1] }))) }))
+        .map(([k, glyphs]) => ({
+        k,
+        glyphs,
+        y: liveBucketY(glyphs),
+        sig: lineSignature(glyphs.map((t) => ({ ch: t.rec.ch, styleKey: t.rec.styleKey, x: t.xs[t.xs.length - 1] }))),
+    }))
         .sort((a, b) => a.y - b.y);
     const nextArr = [...next.entries()]
-        .map(([k, recs]) => ({ k, recs, y: recs[0].segY, sig: lineSignature(recs.map((g) => ({ ch: g.ch, styleKey: g.styleKey, x: g.x }))) }))
+        .map(([k, recs]) => ({
+        k,
+        recs,
+        y: recs[0].segY,
+        sig: lineSignature(recs.map((g) => ({ ch: g.ch, styleKey: g.styleKey, x: g.x }))),
+    }))
         .sort((a, b) => a.y - b.y);
     const usedLive = new Set();
     const usedNext = new Set();
@@ -734,7 +772,12 @@ function threadGlyphs(perState, stateCount) {
             const prevList = pairing.prev.slice().sort((a, b) => a.xs[a.xs.length - 1] - b.xs[b.xs.length - 1]);
             const nextList = pairing.next;
             totalNext += nextList.length;
-            const prevSeq = prevList.map((t) => ({ ch: t.rec.ch, x: t.xs[t.xs.length - 1], fill: t.fills[t.fills.length - 1], styleKey: t.rec.styleKey }));
+            const prevSeq = prevList.map((t) => ({
+                ch: t.rec.ch,
+                x: t.xs[t.xs.length - 1],
+                fill: t.fills[t.fills.length - 1],
+                styleKey: t.rec.styleKey,
+            }));
             const nextSeq = nextList.map((g) => ({ ch: g.ch, x: g.x, fill: g.fill, styleKey: g.styleKey }));
             const align = alignLineGlyphs(prevSeq, nextSeq);
             const survivors = [];
@@ -803,7 +846,15 @@ function threadGlyphs(perState, stateCount) {
                     for (const g of placeBirths)
                         if (g.x > last.x)
                             last = g;
-                    edits.push({ state: s, x: last.x + last.advance, lineTop: last.segY, ascent: last.ascent, descent: last.descent, fontSize: last.fontSize, cellWidth: last.advance });
+                    edits.push({
+                        state: s,
+                        x: last.x + last.advance,
+                        lineTop: last.segY,
+                        ascent: last.ascent,
+                        descent: last.descent,
+                        fontSize: last.fontSize,
+                        cellWidth: last.advance,
+                    });
                 }
                 else {
                     let first = placeDeaths[0];
@@ -811,7 +862,15 @@ function threadGlyphs(perState, stateCount) {
                         if (t.xs[t.xs.length - 1] < first.xs[first.xs.length - 1])
                             first = t;
                     const r = first.rec;
-                    edits.push({ state: s, x: first.xs[first.xs.length - 1], lineTop: r.segY, ascent: r.ascent, descent: r.descent, fontSize: r.fontSize, cellWidth: r.advance });
+                    edits.push({
+                        state: s,
+                        x: first.xs[first.xs.length - 1],
+                        lineTop: r.segY,
+                        ascent: r.ascent,
+                        descent: r.descent,
+                        fontSize: r.fontSize,
+                        cellWidth: r.advance,
+                    });
                 }
             }
         }
@@ -863,7 +922,18 @@ function buildGlyphGroups(threaded, uid) {
         const dxTl = t.xs.map((x) => round2(x - t.xs[0])).join(",");
         const dyTl = t.ys.map((y) => round2(y - t.ys[0])).join(",");
         const fillTl = t.fills.join("~");
-        const key = [t.birth, t.death, t.rec.lineKey, t.rec.styleKey, round2(t.rec.segY), round2(t.rec.segHeight), round2(t.rec.ascent), dxTl, dyTl, fillTl].join("§");
+        const key = [
+            t.birth,
+            t.death,
+            t.rec.lineKey,
+            t.rec.styleKey,
+            round2(t.rec.segY),
+            round2(t.rec.segHeight),
+            round2(t.rec.ascent),
+            dxTl,
+            dyTl,
+            fillTl,
+        ].join("§");
         const arr = byKey.get(key);
         if (arr != null)
             arr.push(t);
@@ -947,7 +1017,7 @@ function groupElement(group) {
     // output is byte-identical.
     if (el.textTop != null) {
         const firstSegY = first.rec.srcEl.textSegments?.[0]?.y ?? first.ys[0];
-        el.textTop += (first.ys[0] - firstSegY) + dyTotal;
+        el.textTop += first.ys[0] - firstSegY + dyTotal;
     }
     return el;
 }
@@ -955,7 +1025,15 @@ const shallowKeyCache = new WeakMap();
 function shallowKeyOf(el) {
     let k = shallowKeyCache.get(el);
     if (k == null) {
-        k = fnv(JSON.stringify({ ...el, children: undefined, animId: undefined, animatedProperties: undefined, magicKey: undefined, cullClass: undefined, displayNone: undefined }));
+        k = fnv(JSON.stringify({
+            ...el,
+            children: undefined,
+            animId: undefined,
+            animatedProperties: undefined,
+            magicKey: undefined,
+            cullClass: undefined,
+            displayNone: undefined,
+        }));
         shallowKeyCache.set(el, k);
     }
     return k;
@@ -1348,8 +1426,22 @@ export function composeCompressedRun(states, opts) {
     // Render the two layers through the production pipeline. Chrome first
     // (below), glyphs above — the occlusion guard demoted anything a later
     // box-painting element overlaps, so this flattening is paint-safe.
-    const chromeInner = elementTreeToSvgInner(chromeTree, width, height, `${uid}c-`, true, 2, false);
-    const glyphInner = glyphEls.length > 0 ? elementTreeToSvgInner(glyphEls, width, height, `${uid}g-`, true, 2, false) : "";
+    // DM-6SQXGF: when the run owns a real-text layer, render the two VISIBLE
+    // layers inside `withRealTextLayerVisualSemantics` so their glyph runs emit
+    // `aria-hidden="true"` (the paintless layer owns the readable flow). The two
+    // renders pass `includeRealTextLayer=false` — the run emits ONE layer from the
+    // final state below, not one per layer.
+    let chromeInner = "";
+    let glyphInner = "";
+    const renderVisibleLayers = () => {
+        chromeInner = elementTreeToSvgInner(chromeTree, width, height, `${uid}c-`, true, 2, false);
+        glyphInner = glyphEls.length > 0 ? elementTreeToSvgInner(glyphEls, width, height, `${uid}g-`, true, 2, false) : "";
+    };
+    if (opts.realText === true)
+        withRealTextLayerVisualSemantics(renderVisibleLayers);
+    else
+        renderVisibleLayers();
+    const realTextLayer = opts.realText === true ? renderRealTextLayer(structuredClone(states[stateCount - 1].tree)) : "";
     // Behind-glyph selection: docs/101 selection rects resolved against each
     // selection's appear-state captured tree, emitted into the chrome↔glyph gap
     // (below `glyphInner`), so the highlight paints BEHIND the glyph ink — true
@@ -1377,8 +1469,13 @@ export function composeCompressedRun(states, opts) {
                     : {}),
             };
             const track = {
-                shape: "bar", color: "#111111", barWidthPx: DEFAULT_CARET_WIDTH_PX,
-                blinkMs: CARET_BLINK_MS, waypoints: [], hides: [], selections: [sel],
+                shape: "bar",
+                color: "#111111",
+                barWidthPx: DEFAULT_CARET_WIDTH_PX,
+                blinkMs: CARET_BLINK_MS,
+                waypoints: [],
+                hides: [],
+                selections: [sel],
             };
             parts.push(textTrackMarkup(track, totalMs, 100 + i));
         }
@@ -1398,8 +1495,12 @@ export function composeCompressedRun(states, opts) {
             selections: [],
         };
         const pointOf = (e) => ({
-            x: e.x, baselineY: e.lineTop + e.ascent, ascentPx: e.ascent, descentPx: e.descent,
-            fontSize: e.fontSize, cellWidthPx: e.cellWidth,
+            x: e.x,
+            baselineY: e.lineTop + e.ascent,
+            ascentPx: e.ascent,
+            descentPx: e.descent,
+            fontSize: e.fontSize,
+            cellWidthPx: e.cellWidth,
         });
         // Parked at the first upcoming edit point from t=0 (reads as "about to
         // type here"), then stepping to each edit's after-position at its boundary.
@@ -1413,8 +1514,8 @@ export function composeCompressedRun(states, opts) {
     const trackCss = css.css();
     const styleCss = `${fontFaceCss !== "" ? fontFaceCss + "\n" : ""}${trackCss}`;
     const bgRect = opts.background != null ? `<rect width="${width}" height="${height}" fill="${esc(opts.background)}"/>` : "";
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`
-        + `<style>${styleCss}</style>${bgRect}${chromeInner}${selectionMarkup}${glyphInner}${caretMarkup}</svg>`;
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+        `<style>${styleCss}</style>${bgRect}${chromeInner}${selectionMarkup}${glyphInner}${caretMarkup}${realTextLayer}</svg>`;
     const pairingStats = {
         states: stateCount,
         glyphs: plan.thread.totalNext,