@anvpx/motion-scenes 0.0.0-stage → 0.1.1

package/dist/shared/fit-text.js

@@ -0,0 +1,82 @@
+import { textWidth } from "./measure.js";
+const STEP_PX = 2;
+const DEFAULT_MIN_LAST = 0.35;
+const buildTable = (words, k, fontPx) => {
+    const n = words.length;
+    const w = (a, b) => textWidth(words.slice(a, b).join(" "), fontPx);
+    const best = Array.from({ length: k + 1 }, () => Array(n + 1).fill(Infinity));
+    const cut = Array.from({ length: k + 1 }, () => Array(n + 1).fill(0));
+    best[0][0] = 0;
+    for (let j = 1; j <= k; j++) {
+        for (let i = j; i <= n; i++) {
+            for (let c = j - 1; c < i; c++) {
+                const cost = Math.max(best[j - 1][c], w(c, i));
+                if (cost < best[j][i]) {
+                    best[j][i] = cost;
+                    cut[j][i] = c;
+                }
+            }
+        }
+    }
+    return { best, cut };
+};
+/** Split into exactly `k` lines minimising the widest line (ties: earliest cuts). */
+const balanced = (words, k, fontPx) => {
+    const { cut } = buildTable(words, k, fontPx);
+    const lines = [];
+    let end = words.length;
+    for (let j = k; j >= 1; j--) {
+        const start = cut[j][end];
+        lines.unshift(words.slice(start, end).join(" "));
+        end = start;
+    }
+    return lines;
+};
+const lastLineOk = (lines, fontPx, minLast) => {
+    if (lines.length < 2)
+        return true;
+    const widths = lines.map((line) => textWidth(line, fontPx));
+    return (widths.at(-1) ?? 0) >= minLast * Math.max(...widths);
+};
+const validate = (opts) => {
+    const { boxWidth, maxFont, minFont, maxLines } = opts;
+    if (!(boxWidth > 0))
+        throw new RangeError(`fitText: boxWidth must be > 0, got ${boxWidth}`);
+    if (!(minFont > 0) || maxFont < minFont)
+        throw new RangeError(`fitText: font range must satisfy 0 < minFont <= maxFont, got ${minFont}..${maxFont}`);
+    if (!Number.isInteger(maxLines) || maxLines < 1)
+        throw new RangeError(`fitText: maxLines must be an integer >= 1, got ${maxLines}`);
+};
+/** First line count (fewest lines) at `px` that fits the box with a non-stub last line. */
+const wrapAt = (words, px, opts) => {
+    const minLast = opts.minLastLine ?? DEFAULT_MIN_LAST;
+    const most = Math.min(opts.maxLines, Math.max(words.length, 1));
+    for (let k = 1; k <= most; k++) {
+        const lines = words.length === 0 ? [""] : balanced(words, k, px);
+        const widest = Math.max(...lines.map((line) => textWidth(line, px)));
+        if (widest <= opts.boxWidth && lastLineOk(lines, px, minLast))
+            return lines;
+    }
+    return undefined;
+};
+/**
+ * Largest font in [minFont, maxFont] whose balanced wrap fits the box in at most `maxLines`
+ * lines, never breaking a word and never leaving a stub last line. When nothing fits, returns the
+ * single-line text at `minFont` with `fits: false` and the offending words.
+ */
+export const fitText = (text, opts) => {
+    validate(opts);
+    const words = text.split(/\s+/).filter(Boolean);
+    const overlongAt = (px) => words.filter((word) => textWidth(word, px) > opts.boxWidth);
+    for (let px = opts.maxFont; px >= opts.minFont; px -= STEP_PX) {
+        const lines = overlongAt(px).length === 0 ? wrapAt(words, px, opts) : undefined;
+        if (lines !== undefined)
+            return { lines, fontPx: px, fits: true, overlong: [] };
+    }
+    return {
+        lines: [words.join(" ")],
+        fontPx: opts.minFont,
+        fits: false,
+        overlong: overlongAt(opts.minFont),
+    };
+};

package/dist/shared/format.d.ts

@@ -0,0 +1,24 @@
+export type FmtOpts = {
+    /**
+     * "$", "€", "£", "¥" prefix; anything else is appended ("%", " km")
+     */
+    unit?: string;
+    /**
+     * fixed decimals (default 0; 1 when compact above 1000)
+     */
+    decimals?: number;
+    /**
+     * show "+" for positive values
+     */
+    sign?: boolean;
+    /**
+     * K / M / B / T suffix
+     */
+    compact?: boolean;
+};
+/**
+ * @param {number} value
+ * @param {FmtOpts} [opts]
+ * @returns {string}
+ */
+export declare const fmt: (value: number, opts?: FmtOpts) => string;

package/dist/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/shared/frame.d.ts

@@ -0,0 +1,14 @@
+import type { EmitContext } from "@anvpx/motion-schema";
+export type Frame = "landscape" | "portrait" | "square";
+export declare const frameOf: (ctx: Pick<EmitContext, "width" | "height">) => Frame;
+export interface FrameRules {
+    /** Portrait and square. */
+    readonly tall?: string;
+    readonly portrait?: string;
+    readonly square?: string;
+}
+/**
+ * Emit-time layout by frame aspect. Rules are written against `#scene-root`; landscape frames get
+ * no extra CSS, so existing 16:9 output stays byte-identical.
+ */
+export declare const frameCss: (ctx: Pick<EmitContext, "width" | "height">, root: string, rules: FrameRules) => string;

package/dist/shared/frame.js

@@ -0,0 +1,21 @@
+/** Height over width above which a frame is portrait; near 1 is square. */
+const PORTRAIT_RATIO = 1.2;
+const SQUARE_RATIO = 0.85;
+export const frameOf = (ctx) => {
+    const ratio = ctx.height / ctx.width;
+    if (ratio > PORTRAIT_RATIO)
+        return "portrait";
+    return ratio >= SQUARE_RATIO ? "square" : "landscape";
+};
+/**
+ * Emit-time layout by frame aspect. Rules are written against `#scene-root`; landscape frames get
+ * no extra CSS, so existing 16:9 output stays byte-identical.
+ */
+export const frameCss = (ctx, root, rules) => {
+    const frame = frameOf(ctx);
+    if (frame === "landscape")
+        return "";
+    const parts = [rules.tall, frame === "portrait" ? rules.portrait : rules.square];
+    const css = parts.filter((part) => part !== undefined).join("\n");
+    return css === "" ? "" : `\n/* frame: ${frame} */\n${css.replaceAll("#scene-root", root)}\n`;
+};

package/dist/shared/icon-search.d.ts

@@ -0,0 +1,9 @@
+/** Names of icons whose name, keyword tags or group contain every query token (alphabetical). */
+export declare const searchIconNames: (query: string) => string[];
+/** Icon names of a group (`business`, `data`, ...) or carrying a keyword tag; alphabetical. */
+export declare const listIcons: (tag: string) => string[];
+/** Each curated group with how many icons it holds. */
+export declare const iconGroups: () => {
+    group: string;
+    count: number;
+}[];

package/dist/shared/icon-search.js

@@ -0,0 +1,26 @@
+import { ICON_GROUPS, ICONS } from "@anvpx/motion-assets";
+const groupsOf = new Map();
+for (const [group, names] of Object.entries(ICON_GROUPS)) {
+    for (const name of names)
+        groupsOf.set(name, [...(groupsOf.get(name) ?? []), group]);
+}
+const words = (name, tags) => [name, ...tags, ...(groupsOf.get(name) ?? [])].join(" ").toLowerCase();
+/** Names of icons whose name, keyword tags or group contain every query token (alphabetical). */
+export const searchIconNames = (query) => {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    return ICONS.filter(({ name, tags }) => {
+        const hay = words(name, tags);
+        return tokens.every((token) => hay.includes(token));
+    })
+        .map(({ name }) => name)
+        .sort();
+};
+/** Icon names of a group (`business`, `data`, ...) or carrying a keyword tag; alphabetical. */
+export const listIcons = (tag) => {
+    const wanted = tag.toLowerCase();
+    return ICONS.filter(({ name, tags }) => (groupsOf.get(name) ?? []).includes(wanted) || tags.some((t) => t.toLowerCase() === wanted))
+        .map(({ name }) => name)
+        .sort();
+};
+/** Each curated group with how many icons it holds. */
+export const iconGroups = () => Object.entries(ICON_GROUPS).map(([group, names]) => ({ group, count: names.length }));

package/dist/shared/icon.d.ts

@@ -0,0 +1,15 @@
+export { iconLedgerRows, LUCIDE_LICENCE_TEXT } from "@anvpx/motion-assets";
+export interface SceneIconOptions {
+    /** Config pointer of the offending prop, e.g. `props.items[2].icon`. */
+    readonly at: string;
+    readonly size?: number;
+}
+/** Runs `run` and returns its value with the distinct, sorted names of the icons it drew. */
+export declare const collectIcons: <T>(run: () => T) => {
+    readonly value: T;
+    readonly icons: string[];
+};
+/** Schema-time check: a message with 3 suggestions for an unknown icon name, else undefined. */
+export declare const iconProblem: (name: string) => string | undefined;
+/** Vendored Lucide icon as a `currentColor` SVG; unknown names throw a config error with 3 suggestions. */
+export declare const sceneIcon: (name: string, opts: SceneIconOptions) => string;

package/dist/shared/icon.js

@@ -0,0 +1,28 @@
+import { iconNameError, iconSvg } from "@anvpx/motion-assets";
+export { iconLedgerRows, LUCIDE_LICENCE_TEXT } from "@anvpx/motion-assets";
+/** Inline HTML svg needs no namespace; dropping it keeps fragments free of external urls. */
+const XMLNS = ' xmlns="http://www.w3.org/2000/svg"';
+/** One frame per active `collectIcons` run; `sceneIcon` reports to the innermost. */
+const collecting = [];
+/** Runs `run` and returns its value with the distinct, sorted names of the icons it drew. */
+export const collectIcons = (run) => {
+    const used = new Set();
+    collecting.push(used);
+    try {
+        const value = run();
+        return { value, icons: [...used].sort() };
+    }
+    finally {
+        collecting.pop();
+    }
+};
+/** Schema-time check: a message with 3 suggestions for an unknown icon name, else undefined. */
+export const iconProblem = (name) => iconNameError(name);
+/** Vendored Lucide icon as a `currentColor` SVG; unknown names throw a config error with 3 suggestions. */
+export const sceneIcon = (name, opts) => {
+    const problem = iconNameError(name);
+    if (problem !== undefined)
+        throw new Error(`config error at ${opts.at}: ${problem}`);
+    collecting.at(-1)?.add(name);
+    return iconSvg(name, opts.size).replace(XMLNS, "");
+};

package/dist/shared/index.d.ts

@@ -0,0 +1,11 @@
+export type { FitTextOptions, FittedText } from "./fit-text.ts";
+export { fitText } from "./fit-text.ts";
+export { fmt } from "./format.js";
+export type { Frame, FrameRules } from "./frame.ts";
+export { frameCss, frameOf } from "./frame.ts";
+export type { SceneIconOptions } from "./icon.ts";
+export { collectIcons, iconLedgerRows, LUCIDE_LICENCE_TEXT, sceneIcon } from "./icon.ts";
+export type { AccentSegment } from "./markup.ts";
+export { accentHtml, accentSegments, esc, stripAccent } from "./markup.ts";
+export { textWidth } from "./measure.ts";
+export { clamp, countUp, drawOn, lerp, progress, revealProgress, revealTimings, scale, staggerDuration, staggerStart, wipe, } from "./motion.js";

package/dist/shared/index.js

@@ -0,0 +1,7 @@
+export { fitText } from "./fit-text.js";
+export { fmt } from "./format.js";
+export { frameCss, frameOf } from "./frame.js";
+export { collectIcons, iconLedgerRows, LUCIDE_LICENCE_TEXT, sceneIcon } from "./icon.js";
+export { accentHtml, accentSegments, esc, stripAccent } from "./markup.js";
+export { textWidth } from "./measure.js";
+export { clamp, countUp, drawOn, lerp, progress, revealProgress, revealTimings, scale, staggerDuration, staggerStart, wipe, } from "./motion.js";

package/dist/shared/markup.d.ts

@@ -0,0 +1,12 @@
+/** HTML-escape text for element content and attribute values. */
+export declare const esc: (text: string) => string;
+export interface AccentSegment {
+    readonly text: string;
+    readonly accent: boolean;
+}
+/** Splits `[x]` accent markup into segments; unmatched or empty brackets stay literal. */
+export declare const accentSegments: (text: string) => AccentSegment[];
+/** Plain text of accent markup (brackets removed). */
+export declare const stripAccent: (text: string) => string;
+/** Escaped HTML for accent markup: the only tags emitted are `<span class="accent">`. */
+export declare const accentHtml: (text: string) => string;

package/dist/shared/markup.js

@@ -0,0 +1,43 @@
+const ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** HTML-escape text for element content and attribute values. */
+export const esc = (text) => text.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+/** Splits `[x]` accent markup into segments; unmatched or empty brackets stay literal. */
+export const accentSegments = (text) => {
+    const segments = [];
+    let plain = "";
+    const flush = () => {
+        if (plain !== "")
+            segments.push({ text: plain, accent: false });
+        plain = "";
+    };
+    let i = 0;
+    while (i < text.length) {
+        const close = text[i] === "[" ? text.indexOf("]", i + 1) : -1;
+        const inner = close > i + 1 ? text.slice(i + 1, close) : "";
+        if (inner !== "" && !inner.includes("[")) {
+            flush();
+            segments.push({ text: inner, accent: true });
+            i = close + 1;
+        }
+        else {
+            plain += text[i];
+            i++;
+        }
+    }
+    flush();
+    return segments;
+};
+/** Plain text of accent markup (brackets removed). */
+export const stripAccent = (text) => accentSegments(text)
+    .map((s) => s.text)
+    .join("");
+/** Escaped HTML for accent markup: the only tags emitted are `<span class="accent">`. */
+export const accentHtml = (text) => accentSegments(text)
+    .map((s) => (s.accent ? `<span class="accent">${esc(s.text)}</span>` : esc(s.text)))
+    .join("");

package/dist/shared/measure.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic text-width estimate for the bold sans (Inter) used by scene text.
+ * No font is loaded: glyph classes carry a width in em, generous enough that real text never
+ * ends up wider than the estimate.
+ */
+/** Estimated width in px of `text` set at `fontPx`. */
+export declare const textWidth: (text: string, fontPx: number) => number;

package/dist/shared/measure.js

@@ -0,0 +1,34 @@
+/**
+ * Deterministic text-width estimate for the bold sans (Inter) used by scene text.
+ * No font is loaded: glyph classes carry a width in em, generous enough that real text never
+ * ends up wider than the estimate.
+ */
+const SPACE_EM = 0.28;
+const UPPER_EM = 0.72;
+const DIGIT_EM = 0.62;
+const LOWER_EM = 0.6;
+const OTHER_EM = 0.8;
+/** Glyphs whose width differs from their class (narrow, slim and wide letters, punctuation). */
+const SPECIAL = [
+    [" ", SPACE_EM],
+    ["iljI.,:;'|!`", 0.32],
+    ["frt()[]{}/\\-", 0.42],
+    ["mw", 0.9],
+    ["MW@%&", 1],
+];
+const SPECIAL_EM = new Map(SPECIAL.flatMap(([chars, em]) => [...chars].map((c) => [c, em])));
+const classEm = (char) => {
+    if (/[A-Z]/.test(char))
+        return UPPER_EM;
+    if (/[0-9]/.test(char))
+        return DIGIT_EM;
+    return /[a-z]/.test(char) ? LOWER_EM : OTHER_EM;
+};
+const glyphEm = (char) => SPECIAL_EM.get(char) ?? classEm(char);
+/** Estimated width in px of `text` set at `fontPx`. */
+export const textWidth = (text, fontPx) => {
+    let em = 0;
+    for (const char of text)
+        em += glyphEm(char);
+    return Math.ceil(em * fontPx);
+};

package/dist/shared/motion.d.ts

@@ -0,0 +1,94 @@
+/** Smallest / largest fraction of an item's duration shared with the next item in a stagger. */
+export declare const MIN_OVERLAP = 0.05;
+export declare const MAX_OVERLAP = 0.9;
+/**
+ * @param {number} v
+ * @param {number} lo
+ * @param {number} hi
+ * @returns {number}
+ */
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+/**
+ * @param {number} a
+ * @param {number} b
+ * @param {number} p
+ * @returns {number}
+ */
+export declare const lerp: (a: number, b: number, p: number) => number;
+/** 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 declare const scale: (v: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+/** 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 declare const progress: (t: number, start: number, end: number) => number;
+/**
+ * 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 declare const staggerDuration: (n: number, span: number, overlap: number) => number;
+/**
+ * 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 declare const staggerStart: (i: number, n: number, span: number, overlap: number) => number;
+/**
+ * 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 declare const countUp: (t: number, value: number, opts?: {
+    from?: number;
+    start?: number;
+    dur?: number;
+}) => number;
+/** Stroke-dashoffset that draws a path of length `len` on as `p` goes 0..1.
+ * @param {number} len
+ * @param {number} p
+ * @returns {number}
+ */
+export declare const drawOn: (len: number, p: number) => number;
+/** Left-to-right clip-path reveal; `p` 0..1.
+ * @param {number} p
+ * @returns {string}
+ */
+export declare const wipe: (p: number) => string;
+/**
+ * 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 declare const revealTimings: (n: number, span: number, overlap?: number) => {
+    start: number;
+    end: number;
+}[];
+/**
+ * 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 declare const revealProgress: (n: number, t: number, span: number, overlap?: number) => number[];

package/dist/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/source-hash.d.ts

@@ -0,0 +1,4 @@
+/** sha256 over sorted relative paths and LF-normalised contents of the shipped source files. */
+export declare const hashSourceTree: (dir: string) => string;
+/** Fingerprint of every scene, shared module and runtime file: edits invalidate build caches. */
+export declare const sceneSourceHash: () => string;

package/dist/source-hash.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const SOURCE_FILE = /\.(?:ts|js|css)$/;
+const NOT_SHIPPED = /\.test\.ts$|^test-fixtures\.ts$|^__snapshots__$/;
+const listFiles = (dir, prefix = "") => readdirSync(dir, { withFileTypes: true })
+    .filter((item) => !NOT_SHIPPED.test(item.name))
+    .flatMap((item) => item.isDirectory()
+    ? listFiles(`${dir}/${item.name}`, `${prefix}${item.name}/`)
+    : SOURCE_FILE.test(item.name)
+        ? [`${prefix}${item.name}`]
+        : []);
+/** sha256 over sorted relative paths and LF-normalised contents of the shipped source files. */
+export const hashSourceTree = (dir) => {
+    const hash = createHash("sha256");
+    for (const file of listFiles(dir).sort()) {
+        hash.update(`${file}\0${readFileSync(`${dir}/${file}`, "utf8").replaceAll("\r\n", "\n")}\0`);
+    }
+    return hash.digest("hex");
+};
+let memo;
+/** Fingerprint of every scene, shared module and runtime file: edits invalidate build caches. */
+export const sceneSourceHash = () => {
+    memo ??= hashSourceTree(fileURLToPath(new URL("./", import.meta.url)));
+    return memo;
+};

package/dist/test-fixtures.d.ts

@@ -0,0 +1,9 @@
+import { type EmitContext, type SceneEntry } from "@anvpx/motion-schema";
+import type { ZodType } from "zod";
+export declare const emitContext: (overrides?: Partial<EmitContext>) => EmitContext;
+export declare const entryOf: (type: string, props: Record<string, unknown>, extra?: Partial<SceneEntry>) => SceneEntry;
+/** Issues as `<json-pointer>: <message>` lines. */
+export declare const issuesOf: (schema: ZodType, value: unknown) => string[];
+export declare const words: (count: number) => string;
+/** Markup and quotes that must never reach the fragment unescaped. */
+export declare const HOSTILE = "<script>alert(\"x\")</script>";