domotion-svg 0.14.0 → 0.16.0

package/README.md

@@ -2,7 +2,25 @@
   <img src="examples/output/domotion-word-demo.svg" alt="Domotion — an animated wordmark cycling through twenty neon-retro typographic variants of the word domotion" width="600">
 </p>
 
-DOM-to-animated-SVG renderer. Captures HTML/CSS rendered in headless Chromium and converts the captured tree into a self-contained SVG with optional CSS animations — pixel-faithful to what Chromium painted, scales crisply at any size, and embeds without external assets.
+<p align="center">
+  <strong><a href="https://brianwestphal.github.io/domotion/">🌐 Website &amp; docs</a></strong>
+  &nbsp;·&nbsp;
+  <a href="https://brianwestphal.github.io/domotion/showcase/">Showcase</a>
+  &nbsp;·&nbsp;
+  <a href="https://brianwestphal.github.io/domotion/start/quickstart/">Quick start</a>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/brianwestphal/domotion">GitHub</a>
+</p>
+
+**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. Text is emitted as real glyph paths, so it looks identical across browsers; 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), multi-frame **animation** with transitions, overlays, and simulated interaction, **device-chrome** framing, **nested compositing** (animated layers inside animated layers), one-command **SVG → MP4/WebM**, and a fidelity **review** tool.
+
+<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">
+</p>
+
+<p align="center"><sub>A real UI captured and brought to life — one self-contained SVG. <a href="https://brianwestphal.github.io/domotion/showcase/">More demos →</a></sub></p>
 
 ## Why
 
@@ -16,15 +34,13 @@ Domotion captures real HTML/CSS as it renders in Chromium, then emits a single i
 
 ## Status
 
-Early — extracted in 2026-04 from the slicekit project where it had been incubating as `tools/svg-demo-gen`. APIs may still shift while the project's external surface stabilizes.
+Actively developed, with a broad shipped surface — capture, multi-frame animation (transitions, overlays, simulated interaction), the template library, terminal capture, nested compositing, and the video/image exports — exercised by an extensive visual-regression suite. The CLIs and the animate-config schema are stable in practice.
 
 ## Platform support
 
-Domotion ships as a normal npm package and is **designed** to work on macOS, Linux, and Windows — the captured SVG is meant to be pixel-faithful to Chromium on whichever platform the capture is running on (CoreText fallback on macOS, fontconfig on Linux, DirectWrite on Windows).
+Domotion runs on **macOS, Linux, and Windows**, and all three are calibrated. It renders text by extracting real system-font glyph outlines and matching how the browser falls back between fonts on the platform you run it on (CoreText on macOS, fontconfig on Linux, DirectWrite on Windows). macOS is held to pixel-exact parity; Linux and Windows match the browser's glyph selection and metrics within a small native-hinting margin (the residual is unhinted-outline-vs-native-raster rasterization, not missing calibration), and both are gated by visual-regression CI.
 
-**Today it's only actively tested and calibrated on macOS.** Linux and Windows are roadmap items: cross-platform system-font path discovery, per-platform fallback-font chains calibrated against the host Chromium, optional bundled fallback fonts when no local match resolves, and CI coverage on both platforms. The package will install and run on Linux/Windows, but text rendering won't yet match the host Chromium as faithfully as it does on macOS.
-
-If you'd like to help with cross-platform support — testing on Linux or Windows, reporting issues you hit, or sending fixes — please open an issue or PR on [GitHub](https://github.com/brianwestphal/domotion). Bug reports against macOS are also welcome.
+Issues, fixes, and platform feedback are welcome on [GitHub](https://github.com/brianwestphal/domotion).
 
 ## Install
 
@@ -41,8 +57,10 @@ yourself to keep the first job's runtime down.
 The fastest way in is the `domotion` CLI — no TypeScript, no Playwright bring-up. Point it at a URL or HTML file:
 
 ```bash
-# Zero-install: run the published CLI straight from npm.
-npx domotion-svg capture https://example.com -o example.svg
+# Zero-install: run the published CLI straight from npm. The package name is
+# domotion-svg; -p installs it and `domotion` selects the bin (the package ships
+# several bins, so the bin must be named explicitly).
+npx -p domotion-svg domotion capture https://example.com -o example.svg
 
 # Capture a URL as SVG.
 domotion capture https://example.com -o example.svg
@@ -66,6 +84,31 @@ domotion animate ./demo.json
 
 The config describes each frame (input, duration, transition) plus a declarative surface for interaction demos: continuous-session frames that carry client-side state across steps (omit `input` / set `"continue": true`), DOM-mutation and interaction actions, richer readiness waits (`waitForText` / `waitForGone` / `waitForCount`), typing / tap / svg / blink overlays that can anchor to an element's box, an on-screen `cursor` (explicit or `"auto"`), `vars` + `${}` interpolation, and a small `evaluate` escape hatch. See `domotion --help` for the full grammar and the [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/) for a walkthrough.
 
+### Templates — animated SVGs from a few flags
+
+The fastest way to a polished result without writing any HTML. Each built-in is a parameterized generator; pass a few flags and get a self-contained animated SVG. `domotion template list` shows them, `domotion template <name> --help` shows a template's parameters.
+
+```bash
+domotion template lower-third --title "Ada Lovelace" --subtitle "First Programmer" -o banner.svg
+domotion template chart --type donut --data "42,28,18,12" --labels "Search,Direct,Social,Email" -o chart.svg
+domotion template kinetic-text --text "Ship it" --variant pop --by char -o title.svg
+```
+
+Built-ins: **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). Third-party templates are npm packages named `domotion-template-<name>`.
+
+### 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:
+
+```bash
+asciinema rec demo.cast -c "npm test"
+domotion term --cast demo.cast -o demo.svg
+```
+
+### Compositing — animated layers inside animated layers
+
+`domotion composite` stacks layers — a `cast`, a `template`, or a pre-rendered `svg`, any of which may be animated — into one SVG, each placed and on its own timeline with its animation preserved. This is how you nest one animated thing inside another, e.g. a terminal window resizing on a desktop. See `domotion composite --help` and `examples/composite/`.
+
 ### Export to video
 
 The package also ships a standalone `svg-to-video` CLI that renders an animated SVG (a `domotion animate` output, or any CSS-/SMIL-animated SVG) to a video file. It steps the animation timeline frame by frame in Chromium for frame-accurate timing, then pipes the frames to **ffmpeg** (a required external dependency — install via `brew` / `apt` / `winget`).
@@ -80,6 +123,19 @@ svg-to-video demo.svg -o demo.webm --format vp9 --fps 60 --music bed.mp3
 
 Supports target size (`--width`/`--height`, aspect-preserving), `--fps`, `--format` / `--container`, supersampling (`--scale`), background music / foreground audio / captions, and a disk-space pre-flight. See `svg-to-video --help`.
 
+### Export to a still image
+
+To turn a single SVG into an image — to look at a render, embed a thumbnail, or hand off a flat asset — the package ships an `svg-to-image` CLI. The output format follows the `-o` extension: PNG / WebP / AVIF / TIFF (keep alpha for transparent SVGs), JPEG (`--quality`), or a single-page vector PDF. (WebP/AVIF/TIFF are transcoded with the bundled `sharp` — no extra install.)
+
+```bash
+svg-to-image card.svg -o card.png                 # PNG at the SVG's intrinsic size
+svg-to-image card.svg -o card@2x.png --scale 2    # crisp retina (2×) raster
+svg-to-image demo.svg -o frame.png --at 4000      # one frame of an animated SVG, at 4s
+svg-to-image poster.svg -o poster.pdf             # vector PDF
+```
+
+`--at <ms>` samples an animated SVG's timeline, `--width`/`--height` contain preserving aspect, `--scale` supersamples raster output. See `svg-to-image --help`.
+
 ### Reviewing a regression
 
 If a capture comes out looking different from how Chromium painted the source page, the package ships an `svg-review` CLI to help you file a focused bug report. Capture once with `--debug` to get a reproduction bundle (HAR + the Chromium screenshot of the source + the SVG we produced), then open the bundle in the local review UI:
@@ -91,6 +147,8 @@ svg-review --expected example.debug/expected.png --actual example.debug/actual.s
 
 The browser opens a single review card showing the expected / actual / diff PNGs. Arrow keys cycle through the three at full size; drag on any image to mark a problem region and caption it. The side panel builds a GitHub-issue-ready Markdown block as you go — copy it, then file the issue at <https://github.com/brianwestphal/domotion/issues/new> and attach `expected.png` + `actual.svg` so a maintainer can reproduce.
 
+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.
+
 ### Scripting API
 
 When you outgrow the CLI — custom interaction loops, programmatic frame composition, custom overlays — the same primitives are available as a library:
@@ -126,7 +184,8 @@ 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.
-- `CLAUDE.md` — guidance for AI assistants working in this repo.
+- [`llms.txt`](llms.txt) — a concise, self-contained guide for **AI agents using Domotion as a tool** (Claude, Cursor, etc.): the CLIs, the config schema, the template library, the API, and the gotchas. Point your agent at it.
+- `CLAUDE.md` — guidance for AI assistants working *on this repo's* source (different audience from `llms.txt`).
 
 ## License
 

package/dist/animation/animator.d.ts

@@ -24,6 +24,15 @@ export interface AnimationFrame {
     cullCss?: string;
     /** Duration this frame is shown (ms) */
     duration: number;
+    /**
+     * DM-1319: this frame's `svgContent` is itself a self-contained *animated* SVG
+     * (a `cast` / `template` frame) whose internal timeline should start when the
+     * frame becomes visible, not at the master-loop origin. Set to the embedded
+     * content's own play length (ms); the animator re-anchors its keyframes into
+     * the `[frameStart, frameStart + period]` window of the master loop (see
+     * `offsetEmbeddedAnimatedSvgTimeline`). Omit for ordinary captured frames.
+     */
+    embeddedAnimationPeriodMs?: number;
     /** Transition to next frame */
     transition?: {
         /**