domotion-svg 0.23.0 → 0.27.0

package/FEATURES.md

@@ -21,7 +21,8 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **bg-solid**: Solid background colors
 - [x] **bg-transparent**: Semi-transparent backgrounds (rgba)
 - [x] **bg-nested**: Nested backgrounds (child on top of parent)
-- [x] **bg-conic-gradient** (DM-547, doc 28): `conic-gradient` / `repeating-conic-gradient` background layers via pattern-raster pre-pass — covers `bg-conic-smooth`, `bg-conic-checkerboard`, `bg-conic-from-at`, `bg-conic-multilayer` fixtures
+- [x] **bg-conic-gradient** (DM-547, DM-2327, doc 28): `conic-gradient` / `repeating-conic-gradient` background layers via Chromium-painted pattern tiles — covers smooth, checkerboard, from/at, multilayer, and advanced-color effective-zoom fixtures; CPU rasterization is helper-absent best effort only
+- [x] **bg-legacy-webkit-gradient** (DM-2528, doc 223): exact deprecated linear endpoints and two-circle radial geometry, including unitless effective zoom, physical writing-mode axes, stable-sort-before-clamp stop domains, and unchanged modern/repeating routes
 - [ ] **bg-dark-mode** (DM-455, doc 29): Dark-mode capture support — caller-chosen `colorScheme`, dark form-control palette, scheme-aware transparent-root fallback
 
 ### Borders
@@ -38,6 +39,8 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [ ] **layout-absolute**: Absolute positioning
 - [x] **layout-padding**: Padding affecting content position
 - [x] **float-paint-order-context-wide** (doc 01 § Stacking): a stacking context paints in CSS 2.1 Appendix E phases — every in-flow block's background + border (step 3), then every non-positioned float (step 4), then all inline content (step 5). So a float paints above a later block sibling's background and below the text of every paragraph in the context, and an `inline-block` / flex item keeps its own floats (it paints atomically).
+- [x] **perspective-fixed-containing-block-ownership** (DM-2385, doc 06): computed `perspective` creates a real stacking context and fixed-position containing block; asymmetric `perspective-origin` is captured as resolved pixels but has no ownership effect by itself. Computed `transform-style: preserve-3d` still traps fixed descendants when `overflow:hidden` flattens its used 3D style, while `perspective:none` remains the viewport-fixed negative control.
+- [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
@@ -46,14 +49,20 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **comp-card-badge**: Card with inline badge (flex row with mixed components)
 - [x] **comp-input**: Form input with border and placeholder-style text
 - [x] **comp-input-value**: Native `<input>` element with value attribute
+- [x] **native-control-decoration-split** (DM-2455, doc 171): styled select/temporal/search/number hosts and value text remain structural while exact Chromium menulist-arrow and closed-shadow picker/cancel/spin layers are isolated into fail-closed transparent overlays; base-select remains fully vector.
 - [x] **comp-code-block**: Code block with monospace, background, border
 - [ ] **comp-nav**: Navigation bar with logo and links
 
 ### SVG
-- [ ] **svg-inline**: Inline SVG elements (icons) positioned correctly
+- [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`
@@ -64,7 +73,9 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **iframe-recursion-bordered** (DM-1441): same-origin iframe recursion through a non-zero border + padding on the iframe — inner document's origin lands at the iframe **content box** and the inner subtree clips to it.
 - [x] **iframe-canvas-bg-fill** (DM-1448): recursed iframe **taller than its content** — the inner document's propagated canvas background (html-bg-or-else-body-bg) fills the whole inner viewport, so the strip below the content paints the canvas color instead of showing through to the outer page.
 - [x] **iframe-inner-clip-mask** (DM-1446): recursed iframe whose inner content uses `clip-path: url(#id)` + `mask-image: url(#id)` defined in the **iframe's own** `<defs>` — fragment refs resolve against `el.ownerDocument`, so the `<clipPath>`/`<mask>` defs hoist and paint (clipped circle + masked square-with-hole, 0.00%). (Inner `element(#id)` paint refs are frame-aware — DM-1447 — though CSS `element()` itself is unsupported in Chromium / dormant, DM-1450; tall-iframe canvas-bg fill shipped in DM-1448.)
+- [x] **multi-layer-fragment-mask** (DM-2520): ordered local SVG mask layers keep per-layer TreeScope, units/region, mode, composite, and consumer zoom across duplicate outer/iframe ids; two-/three-layer add/intersect/subtract/exclude output is raw-RGBA exact to Chromium at DPR 1/2, with destructive scope/operator/mode/zoom controls.
 - [x] **cross-origin iframe recursion** (DM-1442): `--cross-origin-frames "*"|host[:port],…` (config: `captureCrossOriginFrames`) recurses **allowlisted** cross-origin frames into native SVG by launching Chromium with web security disabled; non-allowlisted frames stay raster. Default off + a stderr security warning (disabling web security disables CORS). Unit + e2e tested (`tests/cross-origin-iframe-recursion.e2e.test.ts`). See [docs/81](docs/81-iframe-recursion.md).
+- [x] **cross-origin frame scroll ownership** (DM-2537): each scroll anchor carries a fresh Chromium `FrameId` graph, parent-relative allowlist/reachability decisions, exact frame-local scrollbar owners and raw RTL/vertical offsets; denied ancestors leak no descendant state and composition destructively rejects stale/omitted/wrong-frame authority. See [docs/217](docs/217-cross-origin-frame-scroll-ownership.md).
 - [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
@@ -72,6 +83,15 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [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
+- [x] **composed-svg-effects-translation**: Inline SVG filter/clip/marker effects under translation covariance
+- [x] **composed-zoom-transform-scale**: Effective zoom, nested transforms, and scale-normalized geometry
+- [x] **composed-same-origin-iframe**: Native same-origin recursion containing fallback, bidi, gradient, mask, and clip decisions
+- [x] **composed-dynamic-replaced-freeze**: Transformed canvas pixels frozen at capture under an independently stacked vector overlay
+
 ## Testing Approach
 
 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`.

package/README.md

@@ -12,7 +12,7 @@
   <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.
+**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.
 
@@ -38,41 +38,51 @@ Actively developed, with a broad shipped surface — capture, multi-frame animat
 
 ## Platform support
 
-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.
+Domotion runs on **macOS, Linux, and Windows**, and all three are calibrated. It renders text by extracting the glyphs Chromium selected on the platform you run it on (CoreText on macOS, fontconfig on Linux, DirectWrite on Windows), then embeds those glyphs instead of asking the viewer's machine to perform font fallback. macOS is held to pixel-exact parity; Linux and Windows match Chromium's glyph selection and metrics within a documented native-hinting margin. Linux fidelity is a required CI check; Windows has first-class native validation and release checks, with its slower broad suites dispatched on demand.
 
 Issues, fixes, and platform feedback are welcome on [GitHub](https://github.com/brianwestphal/domotion).
 
-## Install
+## Quick start
 
 ```bash
 npm install domotion-svg
+npx domotion capture https://example.com -o example.svg
 ```
 
-That's it — Domotion auto-installs Playwright's Chromium binary on first use
-(via `npx playwright install chromium`). On CI you may want to pre-install it
-yourself to keep the first job's runtime down.
+Open `example.svg` in a browser. You should see a self-contained, scalable
+capture of the page with no external fonts, images, or scripts.
 
-## Usage
+Domotion installs Playwright's Chromium binary on first use. CI jobs can run
+`npx playwright install chromium` ahead of time to keep capture runtime
+predictable. For a zero-install trial, run
+`npx -p domotion-svg domotion capture https://example.com -o example.svg`.
 
-The fastest way in is the `domotion` CLI — no TypeScript, no Playwright bring-up. Point it at a URL or HTML file:
+## Choose your task
 
-```bash
-# 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 one page:** use `domotion capture`; see the
+  [capture guide](https://brianwestphal.github.io/domotion/usage/capture/).
+- **Animate a product flow:** use `domotion animate`; follow the
+  [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/).
+
+The [Quick start](https://brianwestphal.github.io/domotion/start/quickstart/)
+walks through the first capture and animation end to end.
 
-# Capture a URL as SVG.
-domotion capture https://example.com -o example.svg
+## More capture inputs
 
-# Capture a local HTML file at a specific viewport, only the .hero region, optimized.
+After the first capture works, the same CLI accepts local files, stdin, element
+selection, custom viewports, optimization, and scrolling pages:
+
+```bash
+# Capture one element from a local file at a specific viewport.
 domotion capture ./demo.html \
   --width 1200 --height 600 \
   --selector ".hero" \
   --optimize \
   -o hero.svg
 
-# Capture HTML piped on stdin.
+# Capture HTML from stdin.
 cat demo.html | domotion capture - -o demo.svg
 
 # Capture a long page as one animated scrolling SVG (scrolls to the bottom over 8s).
@@ -85,15 +95,18 @@ into Playwright's stricter network-idle heuristic with `--network-idle`; it is
 off by default because analytics, long polling, and streaming requests may
 never become idle.
 
-Same-origin `<iframe>` content is recursed into the capture as native, selectable SVG rather than flattened to a screenshot; opt into cross-origin frames you trust with `--cross-origin-frames "<hosts>"`.
+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>"`.
 
-For a multi-frame animated SVG, write a small JSON config and run `domotion animate`:
+For a multi-frame animated SVG, write a JSON config and run:
 
 ```bash
 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 / shine / interact overlays that can anchor to an element's box (typing supports per-keystroke reveal, `kern`, caret shapes, and a high-fidelity `typeResample` mode), real interaction-state capture (`forceState` / `hoverReveal` / `hoverDetect` / `jsReveal`), 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.
+The config describes frames, timing, transitions, waits, overlays, and simulated
+interaction. See `domotion --help` for the full grammar and the
+[animation guide](https://brianwestphal.github.io/domotion/usage/animate/) for
+examples ranging from simple transitions to continuous interactive sessions.
 
 Transitions are not limited to fixed presets. Parameterized `push`, `reveal`,
 `zoom`, and `shine` forms control direction/angle, distance, origin, radius, and
@@ -164,6 +177,15 @@ 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 automation, pass `--no-open` (or set `DOMOTION_NO_OPEN=1`) and drive the
+printed local URL headlessly; Review and Scrubber otherwise open the system
+browser for interactive use.
+
+Animation runs have the same evidence path. `domotion animate demo.json --debug`
+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.
 
 ### Scripting API
@@ -186,6 +208,11 @@ await browser.close();
 
 For animated demos, capture multiple frames and pass them to `generateAnimatedSvg` (see `examples/`).
 
+Library callers can collect a reproduction entirely in memory with
+`captureElementTreeWithDebug()` and `assembleCaptureDebugBundle()`. The caller
+keeps ownership of the browser, files, and optional HAR lifecycle; see the
+[scripting API](https://brianwestphal.github.io/domotion/developer/api/).
+
 ## Scripts
 
 ```bash
@@ -201,7 +228,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, the config schema, the template library, the API, and the gotchas. Point your agent at it.
+- [`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`).
 
 ## License

package/dist/animation/animator.d.ts

@@ -1,178 +1,9 @@
 /**
- * SVG Animation Composer
+ * Stable public facade for animated SVG composition.
  *
- * Takes captured SVG frame content and composes them into a single
- * animated SVG with CSS keyframe transitions.
+ * The implementation lives in `svg-generator.ts`; timeline arithmetic is
+ * isolated in `frame-timeline.ts`. Keeping this facade preserves existing
+ * imports while preventing CLI/capture plumbing from becoming part of the SVG
+ * generator's ownership boundary.
  */
-import { type CursorAtResolver, type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
-import type { MagicMove } from "./magic-move.js";
-import type { AnimationOverlay, TypingOverlay, TapOverlay, SvgOverlay, BlinkOverlay, ShineOverlay, InteractOverlay, IntraFrameAnimation } from "./overlay-schema.js";
-import { type ResolvedTextTrack } from "./caret-track.js";
-import { type Transition } from "./transition-schema.js";
-export interface AnimationFrame {
-    /** SVG content for this frame (from dom-to-svg) */
-    svgContent: string;
-    /**
-     * Per-element viewBox-cull keyframes CSS (DM-603). The caller runs
-     * `cullElementsOutsideViewBox()` on the captured tree before `elementTreeToSvg()` — that
-     * mutates `displayNone` / `cullClass` on each element (which the renderer
-     * surfaces) and returns the keyframes blocks that map each window-derived
-     * `cull-<start>-<end>` class to its visible window. The animator splices
-     * this CSS into the scene-wide `<style>` block, deduping blocks whose class
-     * (= window) repeats across frames.
-     *
-     * When omitted, no culling happens — callers passing pre-rendered
-     * `svgContent` strings without the cull CSS get unchanged behavior.
-     */
-    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 the next frame. The type is derived from the canonical zod schema. */
-    transition?: Transition;
-    /**
-     * Magic-move bridge layer for this frame's transition to the next, built by
-     * the caller via `buildMagicMove(prevTree, nextTree, …)`. Present only when
-     * `transition.type === "magic-move"` and both frames' element trees were
-     * available; the animator shows it during the transition window (moved
-     * elements slide, added fade in, removed fade out) between the hard-cut prev
-     * and next frame blobs. When `transition.type` is `magic-move` but this is
-     * null, the animator falls back to `crossfade`.
-     */
-    magicMove?: MagicMove | null;
-    /** Overlays: typing, tap ripple */
-    overlays?: AnimationOverlay[];
-    /**
-     * Intra-frame property animations. Run during this frame's hold time.
-     * The CLI / `DemoRecorder` resolves selectors against the DOM at capture
-     * and sets `data-domotion-anim` on matching elements; this list is the
-     * post-resolution form referencing those ids. See `IntraFrameAnimation`.
-     */
-    animations?: IntraFrameAnimation[];
-}
-export type { TypingOverlay, TapOverlay, SvgOverlay, BlinkOverlay, ShineOverlay, InteractOverlay, AnimationOverlay, IntraFrameAnimation };
-export interface AnimationConfig {
-    width: number;
-    height: number;
-    frames: AnimationFrame[];
-    /** DM-1488: accessible name → `role="img"` + `<title>` on the root `<svg>`
-     *  (for inline-`<svg>` embedding). Omit to leave the output unchanged. */
-    title?: string;
-    /** DM-1488: accessible long description → `<desc>` on the root `<svg>`. */
-    desc?: string;
-    /**
-     * Markup (e.g. `<path id="g0" d="..."/>...`) hoisted into the top-level
-     * `<defs>`. Frames can reference these IDs via `<use href="#...">`. Use for
-     * glyph paths and other assets that repeat across frames — avoids duplicating
-     * them in every frame's local defs.
-     */
-    sharedDefs?: string;
-    /**
-     * DM-839: embedded-font `@font-face` rules collected once across all frames
-     * (the caller renders each frame with `includeEmbeddedFontCss=false` and
-     * passes the accumulated `getEmbeddedFontFaceCss()` here). Injected into the
-     * top-level `<style>` so the base64 font bytes appear once, not per frame.
-     */
-    fontFaceCss?: string;
-    /**
-     * Optional cursor / click overlay (DM-277). Renders a macOS-style cursor
-     * moving along the script timeline with QuickTime-style click pulses.
-     * Off by default; opt-in per animation. See `docs/13-cursor-overlay.md`.
-     */
-    cursorOverlay?: CursorOverlay;
-    /**
-     * Resolver for selector-based cursor move events. Required if any event
-     * uses `selector`; otherwise pass undefined / null.
-     */
-    resolveSelector?: SelectorResolver;
-    /**
-     * DM-1106: auto cursor-TYPE hit-tester — given a viewport point and frame
-     * index, returns the cursor keyword under it (the caller builds this from the
-     * per-frame captured trees via `cursorAtPoint`). When provided, the overlay
-     * paints the matching glyph per element and switches at boundary crossings;
-     * when omitted, the overlay paints the single arrow.
-     */
-    resolveCursorAt?: CursorAtResolver;
-    /**
-     * Caret + selection tracks (docs/101): declarative caret / selection
-     * rendering anchored to captured text, resolved caller-side against the
-     * frame's captured tree via `resolveTextTrack` (the magic-move precedent —
-     * built from the element trees, consumed here as resolved geometry). Layered
-     * above every frame group and below the cursor overlay. Times inside each
-     * track are ms on the animation's global timeline.
-     */
-    textTracks?: ResolvedTextTrack[];
-    /**
-     * Canvas background color painted behind every frame (a full-viewport
-     * `<rect>`). Mirrors the single-frame path's `transparentRootBgRect`
-     * (DM-554): pass the captured page's root background so animated output
-     * matches `capture` output. Omitted / `"transparent"` / `"rgba(0, 0, 0, 0)"`
-     * → no rect, i.e. a transparent SVG that composites over a host background.
-     */
-    background?: string;
-    /**
-     * DM-1148: whether the LAST frame fades out (over its transition window) to
-     * dissolve back into the loop's frame 0. Default `false` — the last frame
-     * HOLDS solid to 100% and the loop hard-cuts to frame 0, so a one-shot video
-     * ends on the final frame rather than fading to nothing. Set `true` to restore
-     * the cross-dissolve loop (e.g. for a seamless background-loop SVG). Only
-     * affects the crossfade path; cut transitions already hold-then-cut.
-     */
-    loopFade?: boolean;
-}
-/**
- * DM-1145: re-namespace element ids that COLLIDE across frames. A caller that
- * reuses identical `svgContent` for multiple frames — e.g. caching a captured
- * frame and replaying it for a long hold — emits the same baked-in ids in two
- * frame groups. Duplicate ids are invalid SVG: a `clip-path="url(#id)"` / filter
- * / `<use href="#id">` resolves to the FIRST match, which for the later frame
- * lives in an earlier (now `visibility:hidden`) frame group. Chromium renders
- * that fine during continuous playback, but CLIPS THE ELEMENT AWAY when the
- * timeline is SEEKED to that frame (paused + `currentTime` set) — exactly what
- * svg-to-video does, so the element vanishes in the rendered video although the
- * SVG looks fine when played. Rename each frame's colliding ids (and their
- * in-frame references) to a frame-unique form. ONLY collisions are touched, so
- * frames whose ids are already unique are emitted byte-for-byte unchanged.
- */
-export declare function dedupeFrameIds(frames: AnimationFrame[]): AnimationFrame[];
-/** A rectangular half-plane reveal sampled to a fixed vertex count so angled
- * wipe polygons remain CSS-interpolable on every supported engine. */
-export declare function linearWipeClip(f: number, width: number, height: number, angleDeg: number): string;
-/**
- * DM-1767 (docs/104): resolve an overlay's WINDOW END, in ms from frame start.
- *
- * Historically every overlay's window ended with its frame. `endAt` makes that
- * explicit and lets an overlay end EARLY — clamped to the frame's duration, so
- * it can still never leak past the cut into the next frame. Returns the frame's
- * own duration when the overlay declares nothing, which is why every existing
- * config emits byte-identical CSS.
- *
- * Exported for unit tests.
- */
-export declare function overlayWindowEndMs(overlay: AnimationOverlay, frameDurationMs: number): number;
-/**
- * Collapse repeated numeric offsets inside whole-layer CSS `@keyframes` blocks.
- * Later declarations win per property, matching CSS source-order cascading,
- * but each offset is emitted once so boundary behavior is engine-independent.
- * Blocks without repeated offsets remain byte-identical.
- */
-export declare function consolidateKeyframeOffsets(svg: string): string;
-export declare function generateAnimatedSvg(config: AnimationConfig): string;
-/**
- * DM-1767: each overlay kind's default `delay` — the ms after frame start at
- * which it begins when the author sets none. Published because SHIFTING an
- * overlay onto a different origin (a per-state overlay inside a compressed run
- * moving from "its own state's start" to "the collapsed run's start" —
- * docs/104) must add the offset to the EFFECTIVE delay; adding it to a bare
- * `delay ?? 0` would silently drop the kind's own lead-in and the overlay would
- * fire early relative to how it behaved as its own frame.
- */
-export declare const OVERLAY_DEFAULT_DELAY_MS: Record<AnimationOverlay["kind"], number>;
+export * from "./svg-generator.js";