domotion-svg 0.1.1

package/FEATURES.md

@@ -0,0 +1,102 @@
+# Domotion: Supported Features
+
+Each feature has a visual regression test that compares HTML-to-PNG with SVG-to-PNG.
+
+## 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)
+- [x] **text-right**: Right-aligned text
+- [x] **text-mono**: Monospace font rendering
+- [x] **text-multiline**: Multiple lines of text in a container
+- [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`)
+
+### 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)
+- [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
+- [ ] **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)
+
+### 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)
+- [ ] **layout-grid**: CSS Grid layout
+- [ ] **layout-absolute**: Absolute positioning
+- [x] **layout-padding**: Padding affecting content position
+
+### 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
+- [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] **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
+
+### 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
+
+### 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
+- [x] **replaced-canvas-fixed-overlay**: `<canvas>` under a sibling-positioned `<div>` painting on top — sibling does NOT bleed into the canvas snapshot
+- [x] **replaced-iframe-same-origin**: same-origin `<iframe>` (srcdoc) — iframe content paints into the snapshot
+- [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
+
+## 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`.
+
+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
+4. Convert the element tree to SVG via `elementTreeToSvg` using the selected text rendering mode
+5. Render the SVG in Playwright and capture as PNG ("actual")
+6. Compare pixel-by-pixel with per-channel tolerance (threshold 16, pass if < 8% total diff)
+7. Save expected, actual, and diff PNGs to `tests/output/` for visual inspection
+
+### Text Rendering Modes
+
+The runner accepts a `--mode` flag (or `TEXT_MODE` env var) to select the text rendering strategy:
+
+- **`css`** (default): SVG `<text>` with CSS font properties. Smallest output (~20KB). Best fidelity in Chromium (~0.6% diff). Cross-browser differences from font engine differences.
+- **`path`**: Fontkit converts text to `<path>` outlines using macOS system fonts (SFNS.ttf variable font). Glyph deduplication via `<defs>`/`<use>`. Identical across browsers but larger (~290KB).
+- **`font`**: Embedded woff2 `@font-face` with subsetted system fonts. Uses subset-font for character subsetting, wawoff2 for compression. Largest output (~550KB).
+
+### Running Tests
+
+```bash
+# Run all feature tests (default css mode)
+npx tsx tests/features.ts
+
+# Run a single feature test
+npx tsx tests/features.ts --only text-basic
+
+# Run with a specific text mode
+npx tsx tests/features.ts --mode path
+
+# Run showcase integration tests
+npx tsx tests/showcase.ts
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Westphal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Domotion
+
+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.
+
+## Why
+
+Animated demos for product marketing and documentation usually mean either:
+
+- A bundle of MP4s — heavy, hard to scale, no inline embedding.
+- A live iframe — slow, requires the source app to be online, breaks accessibility.
+- Hand-authored SVG animations — accurate but enormously time-consuming for anything beyond a couple of frames.
+
+Domotion captures real HTML/CSS as it renders in Chromium, then emits a single inline-embeddable SVG that replays the same pixels with CSS keyframe transitions. Author the demo as plain HTML/CSS in your real app, capture frames, and ship the result as a `<img src="demo.svg">` that loads lazily and scales without artifacts.
+
+## 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.
+
+## Install
+
+```bash
+npm install domotion-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.
+
+## Usage
+
+```ts
+import { captureElementTree, elementTreeToSvg, launchChromium, wrapSvg } from "domotion-svg";
+
+const browser = await launchChromium();
+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 = wrapSvg(elementTreeToSvg(tree, 800, 200), 800, 200);
+
+console.log(svg);
+await browser.close();
+```
+
+For animated demos, capture multiple frames and pass them to `generateAnimatedSvg` (see `examples/`).
+
+## Scripts
+
+```bash
+npm run build           # tsc → dist/
+npm test                # unit tests
+npm run demos:test      # feature visual-regression suite
+npm run demos:test:all  # features + showcase + html-test-suite
+npm run demos:review    # local server to compare expected/actual/diff PNGs
+npm run demos:examples  # run the bundled example demo scripts
+```
+
+## Documentation
+
+- `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.
+
+## License
+
+[MIT](LICENSE) © Brian Westphal

package/dist/animator.d.ts

@@ -0,0 +1,158 @@
+/**
+ * SVG Animation Composer
+ *
+ * Takes captured SVG frame content and composes them into a single
+ * animated SVG with CSS keyframe transitions.
+ */
+import { type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
+export interface AnimationFrame {
+    /** SVG content for this frame (from dom-to-svg) */
+    svgContent: string;
+    /** Duration this frame is shown (ms) */
+    duration: 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.
+         */
+        type: "crossfade" | "push-left" | "scroll" | "cut";
+        duration: number;
+    };
+    /** Overlays: typing, tap ripple */
+    overlays?: Overlay[];
+    /**
+     * 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 interface TypingOverlay {
+    kind: "typing";
+    text: string;
+    x: number;
+    y: number;
+    fontSize?: number;
+    color?: string;
+    /** Delay from frame start before typing begins (ms) */
+    delay?: number;
+    /** Speed per character (ms) */
+    speed?: number;
+    /** Background color to mask placeholder text */
+    bgColor?: string;
+    bgWidth?: number;
+    bgHeight?: number;
+}
+export interface TapOverlay {
+    kind: "tap";
+    x: number;
+    y: number;
+    /** Delay from frame start (ms) */
+    delay?: number;
+}
+/**
+ * Frame-local SVG overlay: composites a separately-captured SVG (inlined as
+ * markup, not referenced as `<image href>`) on top of the captured frame.
+ * Used for picture-in-picture effects like sliding a phone-framed preview
+ * into the corner of a terminal demo.
+ *
+ * The overlay is positioned at (x, y), clipped to (width, height), and
+ * gets its own `class="ov-<animId>"` wrapper so intra-frame animations
+ * (or `enter`/`exit` sugar) can target it without colliding with elements
+ * inside the embedded SVG.
+ */
+export interface SvgOverlay {
+    kind: "svg";
+    /**
+     * The SVG content to inline. The CLI resolves `src` paths from the
+     * config file's directory and namespaces the embedded SVG's ids before
+     * setting this field.
+     */
+    innerSvg: string;
+    /** Top-left corner in the captured frame's coordinate space. */
+    x: number;
+    y: number;
+    /** Render size — the embedded SVG's viewBox is preserved and scales to fit. */
+    width: number;
+    height: number;
+    /**
+     * Stable id used to key the overlay's wrapper class (`ov-<animId>`) so
+     * `enter`/`exit` / `animations` can target it. The CLI assigns this.
+     */
+    animId: string;
+    /** Slide-in entrance (DM-211). Sugar over `animations`. */
+    enter?: {
+        from: "top" | "bottom" | "left" | "right";
+        duration: number;
+        easing?: string;
+        delay?: number;
+    };
+    /** Slide-out exit (DM-211). */
+    exit?: {
+        from: "top" | "bottom" | "left" | "right";
+        duration: number;
+        easing?: string;
+        delay?: number;
+    };
+}
+export type Overlay = TypingOverlay | TapOverlay | SvgOverlay;
+/**
+ * Animate a CSS property on captured elements that match a selector, while
+ * the frame is held on screen. The selector is resolved against the source
+ * DOM at capture time (see DM-209) and the matching elements get
+ * `class="anim-<id>"` on their rendered SVG groups.
+ *
+ * Resolution requires the consumer (CLI / `DemoRecorder`) to set
+ * `data-domotion-anim="<id>"` on matching DOM elements before capture; the
+ * `id` referenced here must be the same id set on the DOM.
+ */
+export interface IntraFrameAnimation {
+    /** Anim id — must match the `data-domotion-anim` value set on the DOM pre-capture. */
+    animId: string;
+    /**
+     * CSS property to animate. `clipPath` takes raw CSS `clip-path` values
+     * (e.g. `"inset(0 100% 0 0)"` -> `"inset(0 0 0 0)"`) and is the right
+     * choice for left-to-right reveals like typing-into-captured-text. When
+     * the captured element is wrapped in a `<g class="anim-<id>">`, the
+     * keyframes apply `clip-path` to that wrapper.
+     */
+    property: "width" | "height" | "opacity" | "transform" | "translateX" | "translateY" | "clipPath";
+    /** Start value (CSS string, e.g. `"0%"`, `"240px"`, `"0.3"`). */
+    from: string;
+    /** End value (same syntax as `from`). */
+    to: string;
+    /** Duration in ms. Must be ≤ the parent frame's `duration`. */
+    duration: number;
+    /** CSS easing string. Default `linear`. */
+    easing?: string;
+    /** Ms after the frame becomes visible before animation starts. Default 0. */
+    delay?: number;
+}
+export interface AnimationConfig {
+    width: number;
+    height: number;
+    frames: AnimationFrame[];
+    /**
+     * 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;
+    /**
+     * 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;
+}
+export declare function generateAnimatedSvg(config: AnimationConfig): string;