domotion-svg 0.28.2 → 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
 
@@ -200,7 +226,16 @@ const page = await browser.newPage();
 await page.setContent(`<div style="padding:20px;color:white;background:#0d1117">Hello</div>`);
 
 const tree = await captureElementTree(page, "body", { x: 0, y: 0, width: 800, height: 200 });
-const svg = elementTreeToSvg(tree, 800, 200);
+const svg = elementTreeToSvg(tree, 800, 200, {
+  // Optional: searchable/selectable text when this SVG is embedded inline.
+  // This cannot expose text through <img src="…">.
+  realTextLayer: true,
+  // Optional: how text is emitted. Default "embedded-font" is self-contained
+  // and pixel-faithful. "system-font" instead emits authored <text> painted
+  // by the VIEWER's installed fonts — smaller output, but not pixel-faithful
+  // and only correct where the fonts are present (CLI: --text-mode system-font).
+  // renderTextMode: "system-font",
+});
 
 console.log(svg);
 await browser.close();
@@ -229,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. */