@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/.out/demo/shared/format.js

@@ -0,0 +1,59 @@
+// @ts-check
+// Locale-free, deterministic number formatting for tabular numerals (no Intl, no toLocaleString).
+const MINUS = "−";
+const TIERS = ["", "K", "M", "B", "T"];
+/**
+ * @typedef {object} FmtOpts
+ * @property {string} [unit] "$", "€", "£", "¥" prefix; anything else is appended ("%", " km")
+ * @property {number} [decimals] fixed decimals (default 0; 1 when compact above 1000)
+ * @property {boolean} [sign] show "+" for positive values
+ * @property {boolean} [compact] K / M / B / T suffix
+ */
+/** @param {string} digits */
+const group = (digits) => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/**
+ * @param {number} abs
+ * @param {number} decimals
+ * @returns {string}
+ */
+const fixed = (abs, decimals) => {
+    const [int = "0", frac] = abs.toFixed(decimals).split(".");
+    return frac === undefined ? group(int) : `${group(int)}.${frac}`;
+};
+/**
+ * @param {number} abs
+ * @param {number | undefined} decimals
+ * @returns {string}
+ */
+const compactBody = (abs, decimals) => {
+    let tier = 0;
+    let scaled = abs;
+    while (scaled >= 1000 && tier < TIERS.length - 1) {
+        scaled /= 1000;
+        tier++;
+    }
+    const d = decimals ?? (tier === 0 ? 0 : 1);
+    // rounding can reach 1000 of this tier (999.95K -> 1000.0K): promote once
+    if (tier < TIERS.length - 1 && Number(scaled.toFixed(d)) >= 1000) {
+        scaled /= 1000;
+        tier++;
+    }
+    return `${fixed(scaled, d)}${TIERS[tier]}`;
+};
+/** @param {string} unit */
+const isPrefix = (unit) => /^[$€£¥]/.test(unit);
+/**
+ * @param {number} value
+ * @param {FmtOpts} [opts]
+ * @returns {string}
+ */
+export const fmt = (value, opts = {}) => {
+    if (!Number.isFinite(value))
+        throw new RangeError(`fmt: value must be finite, got ${value}`);
+    const { unit = "", decimals, sign = false, compact = false } = opts;
+    const abs = Math.abs(value);
+    const body = compact ? compactBody(abs, decimals) : fixed(abs, decimals ?? 0);
+    const zero = Number(body.replace(/[^0-9.]/g, "")) === 0;
+    const mark = zero ? "" : value < 0 ? MINUS : sign ? "+" : "";
+    return isPrefix(unit) ? `${mark}${unit}${body}` : `${mark}${body}${unit}`;
+};

package/dist/.out/demo/shared/motion.js

@@ -0,0 +1,117 @@
+// @ts-check
+// Pure motion helpers shared by scenes. No DOM, no clock, no state: the same inputs always give
+// the same outputs. One implementation serves emit time (TS) and the browser seek runtime.
+import { clamp01, ease } from "../runtime/easing.js";
+/** Smallest / largest fraction of an item's duration shared with the next item in a stagger. */
+export const MIN_OVERLAP = 0.05;
+export const MAX_OVERLAP = 0.9;
+/**
+ * @param {number} v
+ * @param {number} lo
+ * @param {number} hi
+ * @returns {number}
+ */
+export const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/**
+ * @param {number} a
+ * @param {number} b
+ * @param {number} p
+ * @returns {number}
+ */
+export const lerp = (a, b, p) => a + (b - a) * p;
+/** Linear map of `v` from [inMin, inMax] to [outMin, outMax], clamped to the input range.
+ * @param {number} v
+ * @param {number} inMin
+ * @param {number} inMax
+ * @param {number} outMin
+ * @param {number} outMax
+ * @returns {number}
+ */
+export const scale = (v, inMin, inMax, outMin, outMax) => lerp(outMin, outMax, inMax === inMin ? (v >= inMax ? 1 : 0) : clamp01((v - inMin) / (inMax - inMin)));
+/** Monotone 0..1 progress of `t` through [start, end]; a zero-length window is a step.
+ * @param {number} t
+ * @param {number} start
+ * @param {number} end
+ * @returns {number}
+ */
+export const progress = (t, start, end) => end > start ? clamp01((t - start) / (end - start)) : t >= start ? 1 : 0;
+/**
+ * @param {number} n
+ * @param {number} span
+ * @returns {void}
+ */
+const assertStagger = (n, span) => {
+    if (!Number.isInteger(n) || n < 1)
+        throw new RangeError(`stagger: n must be an integer >= 1, got ${n}`);
+    if (!(span > 0) || !Number.isFinite(span))
+        throw new RangeError(`stagger: span must be > 0, got ${span}`);
+};
+/** @param {number} overlap */
+const overlapOf = (overlap) => clamp(Number.isFinite(overlap) ? overlap : 0, MIN_OVERLAP, MAX_OVERLAP);
+/**
+ * Duration of each item when `n` items share `span` seconds and overlap by `overlap` (a fraction of
+ * the item duration, clamped to [0.05, 0.9]). The last item ends exactly at `span`.
+ * @param {number} n
+ * @param {number} span
+ * @param {number} overlap
+ * @returns {number}
+ */
+export const staggerDuration = (n, span, overlap) => {
+    assertStagger(n, span);
+    return span / (1 + (n - 1) * (1 - overlapOf(overlap)));
+};
+/**
+ * Start time of item `i` (0-based). Offset between items is always smaller than an item's duration.
+ * @param {number} i
+ * @param {number} n
+ * @param {number} span
+ * @param {number} overlap
+ * @returns {number}
+ */
+export const staggerStart = (i, n, span, overlap) => i * staggerDuration(n, span, overlap) * (1 - overlapOf(overlap));
+/**
+ * Count from `from` (default 0) to `value`, easing out; exact at the end.
+ * @param {number} t
+ * @param {number} value
+ * @param {{ from?: number, start?: number, dur?: number }} [opts]
+ * @returns {number}
+ */
+export const countUp = (t, value, opts = {}) => {
+    const { from = 0, start = 0, dur = 1 } = opts;
+    const p = progress(t, start, start + dur);
+    return p >= 1 ? value : lerp(from, value, ease("out", p));
+};
+/** Stroke-dashoffset that draws a path of length `len` on as `p` goes 0..1.
+ * @param {number} len
+ * @param {number} p
+ * @returns {number}
+ */
+export const drawOn = (len, p) => len * (1 - clamp01(p));
+/** Left-to-right clip-path reveal; `p` 0..1.
+ * @param {number} p
+ * @returns {string}
+ */
+export const wipe = (p) => `inset(0 ${Math.round((1 - clamp01(p)) * 100000) / 1000}% 0 0)`;
+/**
+ * Word-by-word timings: `n` words spread over `span` seconds with `overlap` between neighbours.
+ * @param {number} n
+ * @param {number} span
+ * @param {number} [overlap]
+ * @returns {{ start: number, end: number }[]}
+ */
+export const revealTimings = (n, span, overlap = 0.5) => {
+    const dur = staggerDuration(n, span, overlap);
+    return Array.from({ length: n }, (_, i) => {
+        const start = staggerStart(i, n, span, overlap);
+        return { start, end: i === n - 1 ? span : start + dur };
+    });
+};
+/**
+ * Eased 0..1 progress of each of `n` words at time `t`.
+ * @param {number} n
+ * @param {number} t
+ * @param {number} span
+ * @param {number} [overlap]
+ * @returns {number[]}
+ */
+export const revealProgress = (n, t, span, overlap = 0.5) => revealTimings(n, span, overlap).map(({ start, end }) => ease("out", progress(t, start, end)));

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

@@ -0,0 +1,95 @@
+// 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";
+import { createScene as scene5 } from "./scenes/presenter/scene.js";
+import { createScene as scene6 } from "./scenes/chapter-signals/scene.js";
+import { createScene as scene7 } from "./scenes/mark/scene.js";
+import { createScene as scene8 } from "./scenes/tick/scene.js";
+import { createScene as scene9 } from "./scenes/flow-progress/scene.js";
+const FACTORIES = [scene0, scene1, scene2, scene3, scene4, scene5, scene6, scene7, scene8, scene9];
+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"}},{"clipId":"clip-presenter","start":1.5,"duration":3,"overlap":0,"final":false,"config":{"ease":"out"}},{"clipId":"clip-chapter-signals","start":5,"duration":4,"overlap":0,"final":false,"config":{"ease":"out"}},{"clipId":"clip-mark","start":14.5,"duration":6,"overlap":0,"final":false,"config":{"ease":"out"}},{"clipId":"clip-tick","start":15.5,"duration":3,"overlap":0,"final":false,"config":{"ease":"out"}},{"clipId":"clip-flow-progress","start":20,"duration":8,"overlap":0,"final":false,"config":{"ease":"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-overlays/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-overlays/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-overlays/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-overlays/scenes/chapter-signals/scene.js

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