@anvpx/motion-build 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+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

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @anvpx/motion-build
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Compiler: `storyboard.json` -> HyperFrames project. Depends only on `schema`, `themes`, `scenes`.
+
+```ts
+const result = buildProject({ storyboard, outDir, assetsDir?, ledger?, timing? });
+// { ok: true, outDir, files, manifest, licences, warnings } | { ok: false, errors }
+```
+
+## Pipeline
+
+validate (schema + each scene's `configSchema`) -> theme -> timing -> lint -> assets -> emit -> write.
+Output: `index.html` (root composition, CSP, theme vars, scenes inline in `.clip` wrappers),
+`boot.js` (the only file that knows `hf-seek`; initialises `window.__timelines`), `runtime/*`, `scenes/<id>/{fragment.html,style.css,scene.js}`,
+`assets/*`, `licences.json`, `LICENSE-lucide.txt` (when an icon is used), `manifest.json` (storyboard sha256, package + hyperframes versions, per-file sha256, used `icons`, no timestamps).
+Output is byte-deterministic. Fragments containing `<script` or `on*=` are rejected (`emit/fragment-guard.ts`). CSP keeps `script-src 'unsafe-inline'` (Constitution D1).
+
+## Incremental cache (`cacheDir`)
+
+`buildProject({ ..., cacheDir })` caches each scene's emitted files (`fragment.html`, `style.css`, `scene.js`) under
+`cacheDir`; `index.html`, `boot.js` and `manifest.json` are always regenerated, so output is byte-identical to an uncached
+build and `manifest.json` carries no cache data. Result gains `cache: { hits, misses }`. Key = sha256 of canonical JSON of
+scene entry (type, props, `over`), placement (fps, size, duration, start, total), theme hash, hashes of the assets the
+scene referenced, package versions, hyperframes pin and node major. Files are hex key names, written tmp + rename;
+a corrupt, tampered or unwritable entry is a miss, never an error. `clearCache(dir)` removes cache files only.
+Caveat: the key uses package versions, so after editing scene plugin code bump the version or run `mk build --clean-cache`.
+
+## Timing and lint
+
+Duration = `entry.duration` ?? `max(3, ceil(words/3 + 1.5))`; a voice `TimingManifest` overrides by scene id.
+`transition` is the transition INTO the scene (ignored on the first). `crossfade` overlaps the previous scene
+by 0.5 s; other values warn `transition X not implemented, using cut`.
+Lint errors block the build: hold >= 2 s, reading time (<= 180 wpm), transition <= 0.8 s. Words <= 40 are
+enforced by scene schemas. One rule per file in `src/lint/`. Flow layout rules (`src/lint/flow.ts`, from the scene's own layout): a word wider than its node (error, "would break mid-word"), an edge label overlapping a node or another label (error) or a crossing edge (warning), and node text that does not fit at 28 px (error: fewer nodes, shorter labels, or `direction: "tb"`).
+
+## Overlays
+
+`layer: "overlay"` entries (`over` = base scene id, `offset` seconds from its start, own `duration`) do not advance
+the base timeline. `resolveTimeline` returns `scenes` (base; the crossfade/overlap rule applies only to these) and
+`overlays` (absolute `start`/`end`). Overlay clips are emitted after all base clips in declared order (later = higher
+z-order), each with its own fragment/style/scene.js; `boot.js` shows one only inside its window. `manifest.json` gains
+`overlays: [{id, over, start, end}]` when any exist. Lint (`src/lint/overlays.ts`): `over` must be an existing base
+scene (error), overlay must end by the base scene end (error), 3+ simultaneous overlays (warning). Overlay-only scene
+types need `layer: "overlay"` and base types cannot be overlays (validate-full). Voice timing covers base scenes only.
+Fixture: `fixtures/demo-overlays.storyboard.json` (all five overlay scenes on the pricing demo).
+
+## Error contract
+
+Every error is `{ path, message, suggestion? }`; `path` is an RFC 6901 pointer, e.g.
+`/scenes/1/props/items/0: must not be empty`, `/scenes/0/type: unknown scene type "x" (use one of: ...)`.
+
+Assets: refs are relative to `assetsDir`; absolute paths, `..`, URLs and symlink escapes are rejected. Every
+referenced image needs a ledger row (licence, sourceUrl, sha256 matching the file; attribution when the licence needs it):
+without a `ledger` (CLI `--ledger <assets.json>`) or without that row the build fails with `no ledger row` and writes nothing.
+
+Licences: `licences.json` has one row per font file, per distinct inlined Lucide icon (`icons/svg/<name>.svg`; ISC, or
+ISC AND MIT for the Feather-derived icons) and per copied image (`assets/<ref>`), so it covers every font, icon and
+image in the output. Scenes report the icons they draw (also on a cache hit); `LICENSE-lucide.txt` is emitted whenever
+an icon is used.
+
+## Integration (real HyperFrames, not in the fast run)
+
+`pnpm test:integration` builds `fixtures/demo.storyboard.json` into `dist/.out/demo`, runs `hyperframes check`
+(exit 0), snapshots one frame per scene, renders a 15 fps draft twice and compares md5. A second case builds
+`demo-overlays`, checks it, snapshots overlay windows (must differ from the base-only build; a quiet frame must match)
+and verifies a 15 fps draft with `verifyMedia`.
+Needs Chrome: `npx hyperframes browser ensure`. Fonts are bundled offline (`@fontsource/inter` 5.3.0: `fonts/inter-latin-{400,600,700,800}.woff2`, `fonts.css`, `LICENSE.txt`, OFL-1.1 rows in `licences.json`); `boot.js` also waits on `document.fonts.ready`. No network at render time.
+Outputs live in `dist/.out/` (git-ignored; biome ignores `dist`, so generated files are not linted).

package/dist/.out/demo/boot.js

@@ -0,0 +1,90 @@
+// Emitted boot glue: the only file that knows the renderer's `hf-seek` event.
+import { createScene as scene0 } from "./scenes/intro/scene.js";
+import { createScene as scene1 } from "./scenes/signals/scene.js";
+import { createScene as scene2 } from "./scenes/count/scene.js";
+import { createScene as scene3 } from "./scenes/path/scene.js";
+import { createScene as scene4 } from "./scenes/outro/scene.js";
+const FACTORIES = [scene0, scene1, scene2, scene3, scene4];
+window.__timelines = window.__timelines || {};
+const CONFIG = {"fps":30,"scenes":[{"clipId":"clip-intro","start":0,"duration":5,"overlap":0,"final":false,"config":{"ease":"out","move":"push-in"}},{"clipId":"clip-signals","start":4.5,"duration":10,"overlap":0.5,"final":false,"config":{"ease":"out"}},{"clipId":"clip-count","start":14.5,"duration":6,"overlap":0,"final":false,"config":{"ease":"in-out"}},{"clipId":"clip-path","start":20,"duration":8,"overlap":0.5,"final":false,"config":{"ease":"out"}},{"clipId":"clip-outro","start":27.5,"duration":5,"overlap":0.5,"final":true,"config":{"ease":"out","move":"pull-out"}}]};
+
+const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
+
+const ease = (p) => 1 - (1 - p) ** 3;
+
+/** Eased progress 0..1 of a scene entering over its predecessor (1 when no overlap transition). */
+const transOf = (t, scene) =>
+  scene?.overlap > 0 && (scene.push || scene.wipe || scene.zoomThrough)
+    ? ease(clamp((t - scene.start) / scene.overlap, 0, 1))
+    : 1;
+
+/** Push progress 0..1 of a scene entering over its predecessor (1 when it is not a push). */
+const pushOf = (t, scene) => (scene?.push && scene.overlap > 0 ? transOf(t, scene) : 1);
+
+/** Pure function of global time `t`: local scene time, visibility and fade opacity. */
+const stateAt = (t, scene) => {
+  const end = scene.start + scene.duration;
+  const live = t >= scene.start && (t < end || (scene.final && t <= end));
+  const fade = scene.overlap > 0 ? clamp((t - scene.start) / scene.overlap, 0, 1) : 1;
+  return {
+    local: clamp(t - scene.start, 0, scene.duration),
+    visible: live,
+    opacity: live ? (scene.push || scene.wipe ? 1 : fade) : 0,
+  };
+};
+
+const mounts = CONFIG.scenes.map((scene, index) => {
+  const clip = document.getElementById(scene.clipId);
+  const ctx = { fps: CONFIG.fps, duration: scene.duration };
+  const runtime = FACTORIES[index](clip.firstElementChild, scene.config, ctx);
+  return { scene, clip, runtime };
+});
+
+const ready = Promise.all([document.fonts.ready, ...mounts.map((mount) => mount.runtime.ready)]);
+
+/** Horizontal offset in percent: an entering push scene starts one frame to the right, the one it replaces leaves to the left. */
+const offsetOf = (t, scene, next) => {
+  if (scene.push) return (1 - pushOf(t, scene)) * 100;
+  return next?.push ? -pushOf(t, next) * 100 : null;
+};
+
+/** Scale punch of a zoom-through: incoming shrinks 1.25 -> 1, outgoing grows 1 -> 1.12. */
+const ZOOM_IN_FROM = 1.25;
+const ZOOM_OUT_TO = 1.12;
+
+const scaleOf = (t, scene, next) => {
+  if (scene.zoomThrough) return ZOOM_IN_FROM - (ZOOM_IN_FROM - 1) * transOf(t, scene);
+  if (next?.zoomThrough) return 1 + (ZOOM_OUT_TO - 1) * transOf(t, next);
+  return null;
+};
+
+/** Directional reveal of a wipe: incoming clip opens left -> right. */
+const clipOf = (t, scene) => {
+  if (!scene.wipe) return null;
+  const p = transOf(t, scene);
+  if (p >= 1) return "";
+  return `inset(0 ${(1 - p) * 100}% 0 0)`;
+};
+
+const apply = (t) =>
+  mounts.map(({ scene, clip, runtime }, index) => {
+    const state = stateAt(t, scene);
+    clip.style.visibility = state.visible ? "visible" : "hidden";
+    clip.style.opacity = String(state.opacity);
+    const next = CONFIG.scenes[index + 1];
+    const offset = offsetOf(t, scene, next);
+    if (offset !== null) clip.style.transform = `translateX(${offset}%)`;
+    else {
+      const scale = scaleOf(t, scene, next);
+      if (scale !== null) clip.style.transform = `scale(${scale})`;
+    }
+    const clipPath = clipOf(t, scene);
+    if (clipPath !== null) clip.style.clipPath = clipPath;
+    return runtime.seek(state.local);
+  });
+
+window.addEventListener("hf-seek", (event) => {
+  event.detail.waitUntil(Promise.all([ready, ...apply(event.detail.time)]));
+});
+
+apply(0);

package/dist/.out/demo/runtime/easing.js

@@ -0,0 +1,45 @@
+// @ts-check
+// Pure easing functions: no DOM, no clock, no state.
+/** @typedef {(t: number) => number} EaseFn */
+/** Clamp to [0, 1]; non-finite input maps to 0.
+ * @param {number} t
+ * @returns {number}
+ */
+export const clamp01 = (t) => (t > 0 ? Math.min(t, 1) : 0);
+/** Normalised settle time of the closed-form spring response. */
+const SPRING_SPAN = 1;
+/**
+ * Closed-form underdamped spring step response, rescaled so f(1) = 1 exactly.
+ * @param {number} damping damping ratio, 0 < damping < 1
+ * @param {number} omega natural frequency over the normalised span
+ * @returns {EaseFn}
+ */
+const spring = (damping, omega) => {
+    const decay = damping * omega;
+    const damped = omega * Math.sqrt(1 - damping * damping);
+    /** @param {number} x */
+    const step = (x) => 1 - Math.exp(-decay * x) * (Math.cos(damped * x) + (decay / damped) * Math.sin(damped * x));
+    const settled = step(SPRING_SPAN);
+    return (t) => step(t * SPRING_SPAN) / settled;
+};
+/** @type {Readonly<Record<string, EaseFn>>} */
+const EASINGS = {
+    linear: (t) => t,
+    in: (t) => t * t * t,
+    out: (t) => 1 - (1 - t) ** 3,
+    "in-out": (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+    "spring-soft": spring(0.85, 9),
+    "spring-snappy": spring(0.6, 14),
+};
+export const EASE_NAMES = Object.keys(EASINGS);
+/**
+ * @param {string} name one of EASE_NAMES
+ * @param {number} t progress, clamped to [0, 1]
+ * @returns {number}
+ */
+export const ease = (name, t) => {
+    const fn = EASINGS[name];
+    if (!fn)
+        throw new Error(`unknown ease "${name}"; use one of: ${EASE_NAMES.join("|")}`);
+    return fn(clamp01(t));
+};

package/dist/.out/demo/runtime/mount.js

@@ -0,0 +1,153 @@
+// @ts-check
+// Thin DOM layer: seek(t) writes styles as a pure function of t.
+import { cameraScale, countScale, countText, countTrack, dimOpacity, driftOf, entranceState, entranceTrack, overlayEnvelope, sample, } from "./timeline.js";
+/** @typedef {{ ease?: string, move?: string, focus?: string }} SceneConfig */
+/** @typedef {{ fps?: number, duration?: number }} RuntimeContext */
+/** @typedef {import("./timeline.js").Plan} Plan */
+/** @typedef {{ seek(t: number): void, dispose(): void, ready: Promise<void> }} Runtime */
+/** @typedef {(root: HTMLElement, config: SceneConfig, ctx: RuntimeContext) => Runtime} CreateScene */
+/** @typedef {{ el: HTMLElement, text: string, track: import("./timeline.js").Track }} Counter */
+/** @typedef {{ el: HTMLElement | SVGElement, kind: string, keys: string, track: import("./timeline.js").Track }} Item */
+const DEFAULT_FPS = 30;
+/**
+ * Config and ctx win over the data-* attributes the emitter put on the root.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ */
+const readSettings = (root, config, ctx) => ({
+    ease: config.ease ?? root.dataset.ease ?? "out",
+    move: config.move ?? root.dataset.move ?? "static",
+    focus: config.focus ?? root.dataset.focus ?? "",
+    fps: ctx.fps ?? Number(root.dataset.fps ?? DEFAULT_FPS),
+    duration: ctx.duration ?? Number(root.dataset.duration ?? 0),
+});
+/**
+ * @param {HTMLElement} root
+ * @param {ReturnType<typeof readSettings>} settings
+ * @param {Plan} plan
+ * @returns {Item[]}
+ */
+const collectItems = (root, settings, plan) => Array.from(root.querySelectorAll("[data-anim]"), (node) => {
+    const el = /** @type {HTMLElement | SVGElement} */ (node);
+    const step = Number(el.dataset.step ?? 0);
+    return {
+        el,
+        kind: el.dataset.anim ?? "rise",
+        keys: el.dataset.focusKey ?? "",
+        track: entranceTrack(step, plan, settings.fps, settings.ease),
+    };
+});
+/**
+ * @param {Item} item
+ * @param {number} t
+ * @param {string} focus
+ * @param {number} rise
+ */
+const applyItem = (item, t, focus, rise) => {
+    const state = entranceState(item.kind, sample(item.track, t), rise);
+    item.el.style.opacity = String(state.opacity * dimOpacity(focus, item.keys));
+    if (item.kind === "rise")
+        item.el.style.transform = `translateY(${state.y}px)`;
+    if (item.kind === "draw")
+        item.el.style.strokeDashoffset = String(state.dash);
+    if (item.kind === "grow")
+        item.el.style.transform = `scaleX(${state.scale})`;
+};
+/** @param {Item} item */
+const clearItem = (item) => {
+    for (const name of ["opacity", "transform", "stroke-dashoffset"]) {
+        item.el.style.removeProperty(name);
+    }
+};
+/**
+ * Elements whose text counts up to the number they carry in data-count.
+ * @param {HTMLElement} root
+ * @param {ReturnType<typeof readSettings>} settings
+ * @param {Plan} plan
+ * @returns {Counter[]}
+ */
+const collectCounters = (root, settings, plan) => Array.from(root.querySelectorAll("[data-count]"), (node) => {
+    const el = /** @type {HTMLElement} */ (node);
+    const step = Number(el.dataset.step ?? 0);
+    return {
+        el,
+        text: el.dataset.count ?? "",
+        track: countTrack(step, plan, settings.fps, settings.ease, settings.duration),
+    };
+});
+/**
+ * @param {Counter} counter
+ * @param {number} t
+ */
+const applyCounter = (counter, t) => {
+    const progress = sample(counter.track, t);
+    counter.el.textContent = countText(counter.text, progress);
+    counter.el.style.transform = `scale(${countScale(progress)})`;
+};
+/**
+ * @param {HTMLElement} root
+ * @returns {Promise<void>}
+ */
+const fontsReady = (root) => root.ownerDocument.fonts?.ready.then(() => undefined) ?? Promise.resolve();
+/**
+ * Mounts every [data-anim] element of a scene fragment on one entrance timeline.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @returns {Runtime}
+ */
+export const mountTimeline = (root, config, ctx, plan) => {
+    const settings = readSettings(root, config, ctx);
+    const items = collectItems(root, settings, plan);
+    const counters = collectCounters(root, settings, plan);
+    /** @param {number} t */
+    const seek = (t) => {
+        for (const item of items)
+            applyItem(item, t, settings.focus, plan.rise);
+        for (const counter of counters)
+            applyCounter(counter, t);
+        root.style.setProperty("--drift", String(driftOf(t)));
+        root.style.transform = `scale(${cameraScale(settings.move, t, settings.duration)})`;
+    };
+    const dispose = () => {
+        for (const item of items)
+            clearItem(item);
+        for (const counter of counters) {
+            counter.el.textContent = counter.text;
+            counter.el.style.removeProperty("transform");
+        }
+        root.style.removeProperty("transform");
+        root.style.removeProperty("--drift");
+    };
+    seek(0);
+    return { seek, dispose, ready: fontsReady(root) };
+};
+/**
+ * An overlay: the entrance timeline plus an eased fade of the whole layer in and out of its
+ * time span. `hooks.update(t)` draws scene-specific state; `hooks.reset()` undoes it on dispose.
+ * @param {HTMLElement} root
+ * @param {SceneConfig} config
+ * @param {RuntimeContext} ctx
+ * @param {Plan} plan
+ * @param {{ update?: (t: number) => void, reset?: () => void }} [hooks]
+ * @returns {Runtime}
+ */
+export const mountOverlay = (root, config, ctx, plan, hooks = {}) => {
+    const settings = readSettings(root, config, ctx);
+    const inner = mountTimeline(root, config, ctx, plan);
+    /** @param {number} t */
+    const seek = (t) => {
+        inner.seek(t);
+        root.style.opacity = String(overlayEnvelope(t, settings.duration, settings.ease));
+        hooks.update?.(t);
+    };
+    const dispose = () => {
+        inner.dispose();
+        root.style.removeProperty("opacity");
+        hooks.reset?.();
+    };
+    seek(0);
+    return { seek, dispose, ready: inner.ready };
+};

package/dist/.out/demo/runtime/timeline.js

@@ -0,0 +1,199 @@
+// @ts-check
+// Pure timeline core: every value is a function of (inputs, t) only.
+import { clamp01, ease } from "./easing.js";
+/** @typedef {{ from: number, to: number, start: number, end: number, ease: string }} Track */
+/** @typedef {{ baseDelay: number, staggerFrames: number, rise: number }} Plan */
+/** @typedef {{ opacity: number, y: number, dash: number, scale: number }} EntranceState */
+export const ENTRANCE_SECONDS = 0.6;
+export const MIN_STAGGER_FRAMES = 3;
+export const MAX_STAGGER_FRAMES = 6;
+export const COUNT_SECONDS = 1.4;
+/** Share of the scene a count-up may take, and its ceiling in seconds. */
+export const COUNT_SHARE = 0.25;
+export const MAX_COUNT_SECONDS = 3;
+/** Opacity of a "rise" element at progress 0, so no scene opens on a blank frame. */
+export const RISE_FLOOR = 0.45;
+/** Size of a counting number at progress 0, relative to its final size. */
+export const COUNT_SCALE_FROM = 0.7;
+/** Fade-in and fade-out length of an overlay window, in seconds. */
+export const ENVELOPE_SECONDS = 0.4;
+/** Extra size of a countdown number at the start of each step. */
+export const PULSE_SCALE = 0.25;
+const PULSE_SHARE = 0.4;
+const DRIFT_RATE = 0.35;
+const GROUP_SIZE = /\B(?=(\d{3})+(?!\d))/g;
+const LEADING_NUMBER = /^(\D*?)(\d[\d,]*(?:\.\d+)?)(\D*)$/;
+const DIM_OPACITY = 0.3;
+const MOVE_DELTA = 0.04;
+/**
+ * Value of a single-segment track at time t (seconds).
+ * @param {Track} track
+ * @param {number} t
+ * @returns {number}
+ */
+export const sample = (track, t) => {
+    const span = track.end - track.start;
+    const progress = span > 0 ? clamp01((t - track.start) / span) : Number(t >= track.end);
+    return track.from + (track.to - track.from) * ease(track.ease, progress);
+};
+/**
+ * Stagger between consecutive steps, in seconds, from a frame count.
+ * @param {number} frames 3-6
+ * @param {number} fps
+ * @returns {number}
+ */
+export const staggerSeconds = (frames, fps) => {
+    if (frames < MIN_STAGGER_FRAMES || frames > MAX_STAGGER_FRAMES) {
+        throw new RangeError(`stagger must be ${MIN_STAGGER_FRAMES}-${MAX_STAGGER_FRAMES} frames`);
+    }
+    return frames / fps;
+};
+/**
+ * Progress track (0 -> 1) of the entrance of step `step`.
+ * @param {number} step
+ * @param {Plan} plan
+ * @param {number} fps
+ * @param {string} easing
+ * @returns {Track}
+ */
+export const entranceTrack = (step, plan, fps, easing) => {
+    const start = plan.baseDelay + step * staggerSeconds(plan.staggerFrames, fps);
+    return { from: 0, to: 1, start, end: start + ENTRANCE_SECONDS, ease: easing };
+};
+/**
+ * @param {string} kind
+ * @param {number} p
+ * @returns {number}
+ */
+const entranceOpacity = (kind, p) => {
+    if (kind === "draw")
+        return 1;
+    return kind === "rise" ? RISE_FLOOR + (1 - RISE_FLOOR) * clamp01(p) : clamp01(p);
+};
+/**
+ * Visual state of an element kind at entrance progress p.
+ * @param {string} kind rise | fade | draw | grow
+ * @param {number} p progress; may overshoot for springs
+ * @param {number} rise rise distance in px
+ * @returns {EntranceState}
+ */
+export const entranceState = (kind, p, rise) => ({
+    opacity: entranceOpacity(kind, p),
+    y: kind === "rise" ? (1 - p) * rise : 0,
+    dash: 1 - p,
+    scale: kind === "grow" ? clamp01(p) : 1,
+});
+/**
+ * Count-up length: COUNT_SECONDS, stretched to a quarter of a long scene (max MAX_COUNT_SECONDS).
+ * @param {number} duration scene seconds; 0 or unknown keeps COUNT_SECONDS
+ * @returns {number}
+ */
+export const countSeconds = (duration) => Math.min(MAX_COUNT_SECONDS, Math.max(COUNT_SECONDS, duration * COUNT_SHARE));
+/**
+ * Track of a count-up that starts with the entrance of `step`.
+ * @param {number} step
+ * @param {Plan} plan
+ * @param {number} fps
+ * @param {string} easing
+ * @param {number} [duration] scene seconds
+ * @returns {Track}
+ */
+export const countTrack = (step, plan, fps, easing, duration = 0) => {
+    const { start } = entranceTrack(step, plan, fps, easing);
+    return { from: 0, to: 1, start, end: start + countSeconds(duration), ease: easing };
+};
+/**
+ * Scale of a counting number at count progress p: grows from COUNT_SCALE_FROM to 1.
+ * @param {number} p
+ * @returns {number}
+ */
+export const countScale = (p) => COUNT_SCALE_FROM + (1 - COUNT_SCALE_FROM) * clamp01(p);
+/** @param {string} digits */
+const withGrouping = (digits) => digits.replace(GROUP_SIZE, ",");
+/**
+ * The first number of `text` scaled to progress p, keeping prefix, suffix, decimals and
+ * thousands separators; p >= 1 and text without one leading number return `text` verbatim.
+ * @param {string} text
+ * @param {number} p
+ * @returns {string}
+ */
+export const countText = (text, p) => {
+    const match = LEADING_NUMBER.exec(text);
+    if (!match || p >= 1)
+        return text;
+    const [, prefix = "", number = "", suffix = ""] = match;
+    const decimals = number.includes(".") ? number.length - number.indexOf(".") - 1 : 0;
+    const [whole = "", fraction] = (parseFloat(number.replaceAll(",", "")) * clamp01(p))
+        .toFixed(decimals)
+        .split(".");
+    const grouped = number.includes(",") ? withGrouping(whole) : whole;
+    return `${prefix}${fraction === undefined ? grouped : `${grouped}.${fraction}`}${suffix}`;
+};
+/**
+ * Slow background drift in [-1, 1]: one cycle every ~18 s.
+ * @param {number} t seconds
+ * @returns {number}
+ */
+export const driftOf = (t) => Math.sin(t * DRIFT_RATE);
+/**
+ * Root scale of the supported camera moves; other moves are applied by the build.
+ * @param {string} move
+ * @param {number} t
+ * @param {number} duration
+ * @returns {number}
+ */
+export const cameraScale = (move, t, duration) => {
+    const progress = duration > 0 ? clamp01(t / duration) : 0;
+    if (move === "push-in")
+        return 1 + MOVE_DELTA * progress;
+    if (move === "pull-out")
+        return 1 + MOVE_DELTA * (1 - progress);
+    return 1;
+};
+/**
+ * Opacity multiplier of `focus`: elements outside the focus dim.
+ * @param {string} focus focused key; empty means no focus
+ * @param {string} keys space-separated keys of the element; empty means never dim
+ * @returns {number}
+ */
+export const dimOpacity = (focus, keys) => !focus || !keys || keys.split(" ").includes(focus) ? 1 : DIM_OPACITY;
+/**
+ * Opacity of an overlay at local time t: eased fade in, hold, eased fade out.
+ * @param {number} t seconds from the start of the overlay window
+ * @param {number} duration window length in seconds
+ * @param {string} easing
+ * @returns {number}
+ */
+export const overlayEnvelope = (t, duration, easing) => {
+    const edge = Math.min(ENVELOPE_SECONDS, duration / 2);
+    if (!(edge > 0))
+        return 1;
+    return clamp01(Math.min(ease(easing, t / edge), ease(easing, (duration - t) / edge)));
+};
+/**
+ * Countdown value and pulse scale at local time t: one equal step per integer from -> to.
+ * @param {number} t
+ * @param {number} duration
+ * @param {number} from
+ * @param {number} to
+ * @returns {{ value: number, scale: number }}
+ */
+export const countdownState = (t, duration, from, to) => {
+    const steps = Math.abs(to - from) + 1;
+    const length = duration / steps;
+    const index = Math.min(steps - 1, Math.floor(clamp01(t / duration) * steps));
+    const local = length > 0 ? (t - index * length) / length : 1;
+    return {
+        value: from + Math.sign(to - from) * index,
+        scale: 1 + PULSE_SCALE * (1 - ease("out", local / PULSE_SHARE)),
+    };
+};
+/**
+ * Linear value from -> to across the duration (progress bars).
+ * @param {number} t
+ * @param {number} duration
+ * @param {number} from
+ * @param {number} to
+ * @returns {number}
+ */
+export const spanProgress = (t, duration, from, to) => from + (to - from) * (duration > 0 ? clamp01(t / duration) : 1);

package/dist/.out/demo/scenes/count/scene.js

@@ -0,0 +1,6 @@
+// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    return mountTimeline(root, config, ctx, { baseDelay: 0.2, staggerFrames: 4, rise: 56 });
+}

package/dist/.out/demo/scenes/intro/scene.js

@@ -0,0 +1,6 @@
+// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    return mountTimeline(root, config, ctx, { baseDelay: 0.3, staggerFrames: 6, rise: 48 });
+}

package/dist/.out/demo/scenes/outro/scene.js

@@ -0,0 +1,6 @@
+// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    return mountTimeline(root, config, ctx, { baseDelay: 0.3, staggerFrames: 6, rise: 32 });
+}

package/dist/.out/demo/scenes/path/scene.js

@@ -0,0 +1,6 @@
+// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    return mountTimeline(root, config, ctx, { baseDelay: 0.2, staggerFrames: 6, rise: 24 });
+}

package/dist/.out/demo/scenes/signals/scene.js

@@ -0,0 +1,6 @@
+// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+/** @type {import("../../runtime/mount.js").CreateScene} */
+export function createScene(root, config, ctx) {
+    return mountTimeline(root, config, ctx, { baseDelay: 0.2, staggerFrames: 5, rise: 32 });
+}