domotion-svg 0.21.1 → 0.22.2

package/FEATURES.md

@@ -11,9 +11,11 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [x] **text-right**: Right-aligned text
 - [x] **text-mono**: Monospace font rendering
 - [x] **text-multiline**: Multiple lines of text in a container
+- [x] **lineheight-residual**: Baseline pixel-grid snap on fractional line-height baselines (18px × 1.6 → 28.796875px line boxes; Skia rounds glyph y to integer device pixels)
 - [x] **text-small**: Small/label text (11-12px)
 - [x] **text-inline-mixed**: Mixed inline content (prose with inline code spans)
 - [x] **text-pre-multiline**: Preformatted multiline text (`<pre>` with `white-space: pre`)
+- [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
@@ -35,6 +37,7 @@ Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-
 - [ ] **layout-grid**: CSS Grid layout
 - [ ] **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).
 
 ### Components
 - [x] **comp-button**: Button with background, border, padding, text

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. 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), **scroll capture** (a long page replayed as one self-contained scrolling SVG), multi-frame **animation** with 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 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.
 
 <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">
@@ -89,6 +89,12 @@ 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.
 
+Transitions are not limited to fixed presets. Parameterized `push`, `reveal`,
+`zoom`, and `shine` forms control direction/angle, distance, origin, radius, and
+highlight styling. A strict `custom` recipe can safely combine incoming/outgoing
+opacity, translate, scale, reveal clip, and shine channels—plus explicit reduced-
+motion and loop behavior—without accepting raw CSS or script.
+
 ### 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.

package/assets/fonts/fixture/LICENSE-ibm-plex-serif.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/fixture/LICENSE-jetbrains-mono.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/fixture/README.md

@@ -0,0 +1,39 @@
+# Deterministic fixture faces
+
+Subsetted fonts the frame-sequence compressor's e2e fixtures render with, so
+those fixtures paint the same glyph outlines on macOS, Linux, and Windows.
+
+They exist because the compressor e2e tests assert pixel parity between a
+compressed run and the uncompressed flipbook of the same state, bounded by the
+no-motion caps in `src/review/compare-pngs.ts`. Both images come from our own
+renderer, so the caps only absorb the sub-pixel phase difference the
+compressor's transform groups introduce — but the size of that drift depends on
+which outlines get rasterized. While the fixtures asked for host-dependent
+families (`Menlo`, `system-ui`, `Georgia`) the clean drift ceiling moved with
+the host (88 px largest strict region on macOS vs 829 px in the Linux
+container), overlapping a known compressor break at 3712 px, so no single cap
+could both pass a correct build and fail a broken one. Pinning the fixtures to
+these files collapses the ceiling to one number everywhere.
+
+Consumed through `tests/fixture-fonts.ts` — never referenced by path from a
+test. See that module for the two-halves usage contract (page `@font-face` for
+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` |
+
+Both are unmodified apart from being subsetted to the characters the fixtures
+paint. The OFL permits redistribution of modified copies under a reserved-name
+rule, which is why the outputs carry neutral `DomotionFixture*` names rather
+than the upstream family names.
+
+## Regenerating
+
+`tools/build-fixture-fonts.mjs` rebuilds both from the upstream originals (it
+prints the download URLs). The subset is deterministic — same inputs and the
+same harfbuzzjs version produce byte-identical output, so a re-run must leave
+`git status` clean unless an input or the charset actually changed.

package/dist/animation/animator.d.ts

@@ -7,6 +7,8 @@
 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;
@@ -14,9 +16,10 @@ export interface AnimationFrame {
      * 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 `cull-N` class
-     * to its visible window. The animator splices this CSS into the scene-wide
-     * `<style>` block.
+     * 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.
@@ -33,60 +36,8 @@ export interface AnimationFrame {
      * `offsetEmbeddedAnimatedSvgTimeline`). Omit for ordinary captured frames.
      */
     embeddedAnimationPeriodMs?: number;
-    /** Transition to next frame */
-    transition?: {
-        /**
-         * `crossfade` (default) overlaps fade-out and fade-in. `push-left` slides
-         * the outgoing frame off and the incoming frame in from the right.
-         * `scroll` keeps both visible during the transition. `cut` is instant —
-         * no fade, no slide. For `cut`, `duration` is ignored. `magic-move` blends
-         * shared elements between the two frames — matched elements slide from
-         * their old position to their new one while added/removed elements
-         * cross-fade (DM-898; see `docs/53-magic-move-transition.md`). It requires
-         * the per-frame `magicMove` bridge layer (built caller-side from the
-         * element trees); when that's absent it degrades to `crossfade`.
-         *
-         * DM-1524 adds the cross-engine-safe transition/effect expansion (docs/88):
-         * directional pushes `push-right` / `push-up` / `push-down` (the vertical/
-         * horizontal siblings of `push-left`; `push-up` is the alias of `scroll`'s
-         * motion), the `wipe` (linear left→right `clip-path` reveal) and `iris`
-         * (expanding-circle `clip-path` reveal) reveals, `zoom-in` / `zoom-out`
-         * (scale dolly under a crossfade), and `shine` (a crossfade with a swept
-         * gradient highlight over the handoff — the shared `buildShineSweep` helper).
-         *
-         * DM-1547 adds the radial / clock wipes (docs/88): `wipe-radial` (an
-         * expanding-circle reveal — the same geometry family as `iris`, kept as a
-         * named alias so the "radial wipe" vocabulary is complete, mirroring how
-         * `push-up` aliases `scroll`) and `wipe-clock` (an angular "clock hand" sweep
-         * that reveals the incoming frame around the center via an animated
-         * `clip-path: polygon()` with a fixed vertex count — NO animated conic mask,
-         * NO animated filter, so it composites identically on Blink / WebKit / Gecko).
-         *
-         * All express motion in `transform` / `clip-path` / `opacity` / gradients
-         * only — never an animated CSS `filter` (Chromium-only in `<img>`, docs/84).
-         */
-        type: "crossfade" | "push-left" | "scroll" | "cut" | "magic-move" | "push-right" | "push-up" | "push-down" | "wipe" | "iris" | "zoom-in" | "zoom-out" | "shine" | "wipe-radial" | "wipe-clock";
-        duration: number;
-        /**
-         * DM-1550: optional named easing (or a raw CSS easing string) for the
-         * `wipe` / `iris` clip-path reveal and the `zoom-in` / `zoom-out` scale
-         * dolly this transition drives into the NEXT frame. Resolved through the
-         * motion-preset vocabulary (`resolveEasingPreset`) so the sampled
-         * `spring-soft` / `spring-bouncy` `linear(...)` curves — and their visible
-         * overshoot — apply to the reveal / dolly. Ignored by the other transition
-         * types (their motion is fixed). Default: `linear`.
-         */
-        easing?: string;
-        /**
-         * DM-1585: `wipe-clock` only — where the clock hand STARTS, in degrees
-         * clockwise from 12 o'clock (default 0), and whether it sweeps
-         * counterclockwise (default clockwise). Lets a clock wipe open from, say, 3
-         * o'clock (`wipeStartAngle: 90`) or unwind anticlockwise
-         * (`wipeCounterclockwise: true`). Ignored by every other transition type.
-         */
-        wipeStartAngle?: number;
-        wipeCounterclockwise?: boolean;
-    };
+    /** 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
@@ -150,6 +101,15 @@ export interface AnimationConfig {
      * 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`
@@ -183,4 +143,36 @@ export interface AnimationConfig {
  * 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>;