@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/lint/index.d.ts

@@ -0,0 +1,25 @@
+import { flowEdgeLabelRule, flowTextSizeRule, flowWordBreakRule } from "./flow.ts";
+import { hookFirstRule } from "./hook-first.ts";
+import { linearEaseRule } from "./linear-ease.ts";
+import { longHoldRule } from "./long-hold.ts";
+import { minHoldRule } from "./min-hold.ts";
+import { flatMotionRule, holdAfterAccentRule, transitionEaseMismatchRule, unsupportedMotionRule } from "./motion-craft.ts";
+import { narrationPaceRule } from "./narration-pace.ts";
+import { overlayFitRule, overlayStackRule, overlayTargetRule } from "./overlays.ts";
+import { readingTimeRule } from "./reading-time.ts";
+import { safeZone9x16Rule } from "./safe-zone-9x16.ts";
+import { textFloorRule } from "./text-floor.ts";
+import { transitionImplementedRule } from "./transition-implemented.ts";
+import { transitionLengthRule } from "./transition-length.ts";
+import { duplicatedEmphasisRule, lineLengthRule, offGridSpacingRule, typeDensityRule } from "./type-grid.ts";
+import type { LintInput, LintResult, LintRule } from "./types.ts";
+import { wordsOnScreenRule } from "./words-on-screen.ts";
+export type { LintFinding, LintInput, LintResult, LintRule, PlatformMarginLookup, PlatformMargins, } from "./types.ts";
+export { duplicatedEmphasisRule, flatMotionRule, flowEdgeLabelRule, flowTextSizeRule, flowWordBreakRule, holdAfterAccentRule, hookFirstRule, linearEaseRule, lineLengthRule, longHoldRule, minHoldRule, narrationPaceRule, offGridSpacingRule, overlayFitRule, overlayStackRule, overlayTargetRule, readingTimeRule, safeZone9x16Rule, textFloorRule, transitionEaseMismatchRule, transitionImplementedRule, transitionLengthRule, typeDensityRule, unsupportedMotionRule, wordsOnScreenRule, };
+/**
+ * All rules, in report order. Contrast lives in theme tokens.
+ * Craft rules (motion-craft, type-grid) run after the timing and layout
+ * gates so their pointers stay stable when earlier rules change.
+ */
+export declare const LINT_RULES: readonly LintRule[];
+export declare const lintStoryboard: (input: LintInput) => LintResult;

package/dist/lint/index.js

@@ -0,0 +1,55 @@
+import { flowEdgeLabelRule, flowTextSizeRule, flowWordBreakRule } from "./flow.js";
+import { hookFirstRule } from "./hook-first.js";
+import { linearEaseRule } from "./linear-ease.js";
+import { longHoldRule } from "./long-hold.js";
+import { minHoldRule } from "./min-hold.js";
+import { flatMotionRule, holdAfterAccentRule, transitionEaseMismatchRule, unsupportedMotionRule, } from "./motion-craft.js";
+import { narrationPaceRule } from "./narration-pace.js";
+import { overlayFitRule, overlayStackRule, overlayTargetRule } from "./overlays.js";
+import { readingTimeRule } from "./reading-time.js";
+import { safeZone9x16Rule } from "./safe-zone-9x16.js";
+import { textFloorRule } from "./text-floor.js";
+import { transitionImplementedRule } from "./transition-implemented.js";
+import { transitionLengthRule } from "./transition-length.js";
+import { duplicatedEmphasisRule, lineLengthRule, offGridSpacingRule, typeDensityRule, } from "./type-grid.js";
+import { wordsOnScreenRule } from "./words-on-screen.js";
+export { duplicatedEmphasisRule, flatMotionRule, flowEdgeLabelRule, flowTextSizeRule, flowWordBreakRule, holdAfterAccentRule, hookFirstRule, linearEaseRule, lineLengthRule, longHoldRule, minHoldRule, narrationPaceRule, offGridSpacingRule, overlayFitRule, overlayStackRule, overlayTargetRule, readingTimeRule, safeZone9x16Rule, textFloorRule, transitionEaseMismatchRule, transitionImplementedRule, transitionLengthRule, typeDensityRule, unsupportedMotionRule, wordsOnScreenRule, };
+/**
+ * All rules, in report order. Contrast lives in theme tokens.
+ * Craft rules (motion-craft, type-grid) run after the timing and layout
+ * gates so their pointers stay stable when earlier rules change.
+ */
+export const LINT_RULES = [
+    minHoldRule,
+    readingTimeRule,
+    transitionLengthRule,
+    transitionImplementedRule,
+    overlayTargetRule,
+    overlayFitRule,
+    overlayStackRule,
+    flowWordBreakRule,
+    flowEdgeLabelRule,
+    flowTextSizeRule,
+    textFloorRule,
+    wordsOnScreenRule,
+    longHoldRule,
+    linearEaseRule,
+    narrationPaceRule,
+    hookFirstRule,
+    safeZone9x16Rule,
+    flatMotionRule,
+    unsupportedMotionRule,
+    transitionEaseMismatchRule,
+    holdAfterAccentRule,
+    typeDensityRule,
+    lineLengthRule,
+    offGridSpacingRule,
+    duplicatedEmphasisRule,
+];
+export const lintStoryboard = (input) => {
+    const findings = LINT_RULES.flatMap((rule) => rule(input));
+    return {
+        errors: findings.filter((finding) => finding.severity === "error"),
+        warnings: findings.filter((finding) => finding.severity === "warning"),
+    };
+};

package/dist/lint/layout-estimate.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedTheme } from "@anvpx/motion-schema";
+/**
+ * Deterministic height estimates of portrait scene content, in px. No browser: the numbers mirror each
+ * scene's CSS (padding, gaps, line-heights, size classes) and wrap text with the shared glyph-width
+ * estimate (generous, so lines wrap early). Expect roughly +-20 % against a real render; the lint rule
+ * built on it only warns.
+ */
+export interface Metrics {
+    /** Width of the scene content box in px (frame minus side padding). */
+    readonly width: number;
+    readonly theme: ResolvedTheme;
+}
+type Props = Readonly<Record<string, unknown>>;
+/** Content height in px of a base scene, or undefined for a type with no estimate. */
+export declare const estimateContentHeight: (type: string, props: Props, m: Metrics) => number | undefined;
+/** Height of the bottom-pinned progress overlay (label above a thin track). */
+export declare const progressHeight: (props: Props, m: Metrics) => number;
+export {};

package/dist/lint/layout-estimate.js

@@ -0,0 +1,165 @@
+import { textWidth } from "@anvpx/motion-scenes";
+const BORDER = 4;
+const RULE = 8;
+const text = (value) => (typeof value === "string" ? value : "");
+const list = (value) => (Array.isArray(value) ? value : []);
+const size = (m, step) => m.theme.fontSizes[step] ?? 0;
+const space = (m, step) => m.theme.spacing[step] ?? 0;
+const largestWithin = (m, steps, maxPx) => steps.find((step) => size(m, step) <= maxPx) ?? steps[steps.length - 1] ?? "md";
+/** Greedy wrap: number of lines of `value` at `px` inside `boxWidth` (a word is never split). */
+const lineCount = (value, px, boxWidth) => {
+    const words = value.replace(/[[\]]/g, "").split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return 0;
+    let lines = 1;
+    let current = "";
+    for (const word of words) {
+        const next = current === "" ? word : `${current} ${word}`;
+        if (current !== "" && textWidth(next, px) > boxWidth) {
+            lines += 1;
+            current = word;
+        }
+        else
+            current = next;
+    }
+    return lines;
+};
+const block = (value, px, boxWidth, lineHeight) => lineCount(value, px, boxWidth) * px * lineHeight;
+const heading = (m, title, gap) => title === ""
+    ? 0
+    : block(title, size(m, "title"), m.width, 1.04) + RULE + space(m, gap) + space(m, "xl");
+const callout = (props, m) => {
+    const plain = text(props.text).replace(/[[\]]/g, "");
+    const kind = text(props.kind) || "statement";
+    const [big, mid] = kind === "formula" ? [16, 40] : [28, 70];
+    const step = plain.length <= big ? "display" : plain.length <= mid ? "title" : "xl";
+    const inner = m.width - 2 * space(m, "xxl") - BORDER;
+    const note = text(props.note);
+    const noteH = note === "" ? 0 : space(m, "lg") + block(note, size(m, "md"), inner * 0.9, 1.3);
+    const head = Math.max(80, size(m, "md"));
+    return (2 * space(m, "xl") +
+        BORDER +
+        head +
+        space(m, "lg") +
+        block(plain, size(m, step), inner, 1.12) +
+        space(m, "lg") +
+        RULE +
+        noteH);
+};
+const BIG_MAX_ITEMS = 3;
+const BIG_MAX_CHARS = 84;
+const MANY_ITEMS = 5;
+const densityOf = (items) => {
+    if (items.length >= MANY_ITEMS)
+        return "many";
+    const chars = items.reduce((sum, item) => sum + item.length, 0);
+    return items.length <= BIG_MAX_ITEMS && chars <= BIG_MAX_CHARS ? "big" : "regular";
+};
+/** Row metrics per list density, mirroring the bullets CSS. */
+const rowSpec = (m, density) => {
+    if (density === "many") {
+        const step = largestWithin(m, ["lg", "md"], 52);
+        return {
+            px: size(m, step),
+            mark: 64,
+            padV: space(m, "md"),
+            padL: space(m, "md"),
+            padR: space(m, "lg"),
+            lh: 1.15,
+            gap: space(m, "md"),
+        };
+    }
+    if (density === "big") {
+        const step = largestWithin(m, ["xl", "lg", "md"], 80);
+        return {
+            px: size(m, step),
+            mark: 88,
+            padV: space(m, "xl"),
+            padL: space(m, "lg"),
+            padR: space(m, "xl"),
+            lh: 1.15,
+            gap: space(m, "xl"),
+        };
+    }
+    return {
+        px: size(m, "lg"),
+        mark: 88,
+        padV: space(m, "lg"),
+        padL: space(m, "lg"),
+        padR: space(m, "xl"),
+        lh: 1.25,
+        gap: space(m, "lg"),
+    };
+};
+const bullets = (props, m) => {
+    const items = list(props.items).map(text);
+    const spec = rowSpec(m, densityOf(items));
+    const textBox = m.width - spec.mark - space(m, "lg") - spec.padL - spec.padR - BORDER;
+    const row = (item) => Math.max(spec.mark, block(item, spec.px, textBox, spec.lh)) + 2 * spec.padV + BORDER;
+    const rows = items.reduce((sum, item) => sum + row(item), 0) + spec.gap * Math.max(items.length - 1, 0);
+    return heading(m, text(props.title), "lg") + rows;
+};
+const statHeroStep = (value) => value.length <= 4 ? "hero" : value.length <= 7 ? "heroMd" : "heroSm";
+const stat = (props, m) => {
+    const value = String(props.value ?? "");
+    const hero = size(m, statHeroStep(value)) * 0.9;
+    const label = text(props.label);
+    const labelH = label === "" ? 0 : space(m, "lg") + block(label, size(m, "lg"), m.width, 1.25);
+    const delta = text(props.delta) === "" ? 0 : space(m, "lg") + size(m, "md") * 1.2 + 2 * space(m, "sm");
+    const context = text(props.context);
+    const contextH = context === ""
+        ? 0
+        : 2 * space(m, "lg") + 2 + block(context, size(m, "md"), Math.min(m.width, 1000), 1.2);
+    return hero + labelH + delta + contextH;
+};
+const iconGrid = (props, m) => {
+    const items = list(props.items).map((item) => (item ?? {}));
+    const count = items.length;
+    const given = typeof props.cols === "number" ? props.cols : undefined;
+    const cols = given ?? (count <= 4 ? Math.max(2, count) : count <= 6 ? 3 : 4);
+    const gap = space(m, "xl");
+    const cardW = (m.width - (cols - 1) * gap) / cols;
+    const labelPx = size(m, cols === 4 && count > 4 ? "md" : "lg");
+    const inner = cardW - 2 * space(m, "xl") - BORDER;
+    const cardH = (item) => {
+        const detail = text(item.detail);
+        const detailH = detail === "" ? 0 : space(m, "md") + block(detail, size(m, "sm"), inner, 1.3);
+        return (2 * space(m, "xl") +
+            BORDER +
+            112 +
+            space(m, "sm") +
+            space(m, "md") +
+            block(text(item.label), labelPx, inner, 1.12) +
+            detailH);
+    };
+    const rows = Math.ceil(count / cols);
+    let grid = 0;
+    for (let row = 0; row < rows; row++) {
+        grid += Math.max(...items.slice(row * cols, (row + 1) * cols).map(cardH));
+    }
+    const head = text(props.title) === "" ? 0 : heading(m, text(props.title), "md") - space(m, "xl");
+    return head + (head === 0 ? 0 : space(m, "xl")) + grid + gap * Math.max(rows - 1, 0);
+};
+const outro = (props, m) => {
+    const inner = Math.min(m.width, 1400);
+    const lines = list(props.lines).map(text);
+    const credits = list(props.credits).length;
+    const gap = space(m, "lg");
+    const main = block(text(props.title), size(m, "title"), inner, 1.08) +
+        gap +
+        RULE +
+        lines.reduce((sum, line) => sum + gap + block(line, size(m, "lg"), inner, 1.3), 0);
+    const creditRows = credits === 0 ? 0 : space(m, "lg") + 2 + size(m, "sm") * 1.2;
+    return main + creditRows;
+};
+const ESTIMATORS = {
+    callout,
+    bullets,
+    stat,
+    "icon-grid": iconGrid,
+    outro,
+};
+/** Content height in px of a base scene, or undefined for a type with no estimate. */
+export const estimateContentHeight = (type, props, m) => ESTIMATORS[type]?.(props, m);
+/** Height of the bottom-pinned progress overlay (label above a thin track). */
+export const progressHeight = (props, m) => space(m, "md") + (text(props.label) === "" ? 0 : size(m, "sm") * 1.2 + space(m, "sm"));

package/dist/lint/linear-ease.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "./types.ts";
+export declare const linearEaseRule: LintRule;

package/dist/lint/linear-ease.js

@@ -0,0 +1,14 @@
+/** Scenes where linear motion is the point (progress, time, draw-on). */
+const EXEMPT_TYPES = new Set(["progress", "countdown", "chart"]);
+export const linearEaseRule = ({ storyboard }) => storyboard.scenes.flatMap((scene, index) => {
+    if (scene.ease !== "linear" || EXEMPT_TYPES.has(scene.type))
+        return [];
+    return [
+        {
+            severity: "warning",
+            path: `/scenes/${index}/ease`,
+            message: `scene "${scene.id}" uses linear ease; entrances feel robotic`,
+            suggestion: 'use ease "out" or "spring-soft"',
+        },
+    ];
+});

package/dist/lint/long-hold.d.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "./types.ts";
+/** A scene at or under this length never reads as frozen. */
+export declare const MAX_STATIC_HOLD_SECONDS = 5;
+/** Still time allowed after the last element has finished entering. */
+export declare const MAX_SETTLED_SECONDS = 4;
+/** Seconds from scene start until its last animated element has settled. */
+export declare const settleSeconds: (type: string, props: Record<string, unknown>, fps: number, words?: number) => number;
+/** Dead air: a long, un-narrated, camera-still scene whose content settled long before it ends. */
+export declare const longHoldRule: LintRule;

package/dist/lint/long-hold.js

@@ -0,0 +1,52 @@
+/** A scene at or under this length never reads as frozen. */
+export const MAX_STATIC_HOLD_SECONDS = 5;
+/** Still time allowed after the last element has finished entering. */
+export const MAX_SETTLED_SECONDS = 4;
+/**
+ * Per-type estimate of the reveal span, mirroring the scene runtime (its entrance timeline):
+ * the first entrance starts at `baseDelay`, each further element follows after `staggerFrames`,
+ * the last one takes `ENTRANCE_SECONDS` to land; `stat` also counts up for `COUNT_SECONDS`.
+ * Types not listed reveal as one element. Staged elements are the array props below.
+ * Reading counts as change too: the viewer is busy until the words are read at a calm pace.
+ */
+const READING_WORDS_PER_SECOND = 2.5;
+const BASE_DELAY = 0.2;
+const ENTRANCE_SECONDS = 0.6;
+const COUNT_SECONDS = 1.4;
+const DEFAULT_STAGGER_FRAMES = 5;
+const STAGGER_FRAMES = { flow: 6 };
+const STAGED_KEYS = ["items", "nodes", "edges", "steps"];
+const stagedCount = (props) => STAGED_KEYS.reduce((sum, key) => {
+    const value = props[key];
+    return sum + (Array.isArray(value) ? value.length : 0);
+}, 0);
+/** Seconds from scene start until its last animated element has settled. */
+export const settleSeconds = (type, props, fps, words = 0) => {
+    const reading = words / READING_WORDS_PER_SECOND;
+    if (type === "stat")
+        return Math.max(reading, BASE_DELAY + COUNT_SECONDS);
+    const stagger = (STAGGER_FRAMES[type] ?? DEFAULT_STAGGER_FRAMES) / fps;
+    const gaps = Math.max(stagedCount(props) - 1, 0);
+    return Math.max(reading, BASE_DELAY + gaps * stagger + ENTRANCE_SECONDS);
+};
+/** Dead air: a long, un-narrated, camera-still scene whose content settled long before it ends. */
+export const longHoldRule = ({ storyboard, timeline, words }) => timeline.scenes.flatMap((timed) => {
+    const scene = storyboard.scenes[timed.index];
+    if (scene === undefined)
+        return [];
+    const moving = scene.move !== undefined && scene.move !== "static";
+    const narrated = (scene.narration ?? "").trim() !== "";
+    if (moving || narrated || timed.duration <= MAX_STATIC_HOLD_SECONDS)
+        return [];
+    const settled = settleSeconds(scene.type, scene.props, storyboard.meta.fps, words[timed.index] ?? 0);
+    if (timed.duration - settled <= MAX_SETTLED_SECONDS)
+        return [];
+    return [
+        {
+            severity: "warning",
+            path: `/scenes/${timed.index}/duration`,
+            message: `scene "${scene.id}" holds ${timed.duration}s with no change; still for ${(timed.duration - settled).toFixed(1)}s after its content settles (max ${MAX_SETTLED_SECONDS}s)`,
+            suggestion: "split the scene, add a move, add narration, or shorten the duration",
+        },
+    ];
+});

package/dist/lint/min-hold.d.ts

@@ -0,0 +1,4 @@
+import type { LintRule } from "./types.ts";
+export declare const MIN_HOLD_SECONDS = 2;
+/** Every scene stays on screen for at least 2 s (PLAN 5b timing). */
+export declare const minHoldRule: LintRule;

package/dist/lint/min-hold.js

@@ -0,0 +1,10 @@
+export const MIN_HOLD_SECONDS = 2;
+/** Every scene stays on screen for at least 2 s (PLAN 5b timing). */
+export const minHoldRule = ({ timeline }) => timeline.scenes
+    .filter((scene) => scene.duration < MIN_HOLD_SECONDS)
+    .map((scene) => ({
+    severity: "error",
+    path: `/scenes/${scene.index}/duration`,
+    message: `hold ${scene.duration}s is under ${MIN_HOLD_SECONDS}s`,
+    suggestion: `use duration >= ${MIN_HOLD_SECONDS}`,
+}));

package/dist/lint/motion-craft.d.ts

@@ -0,0 +1,18 @@
+import type { LintRule } from "./types.ts";
+/**
+ * Three static base scenes in a row read as flat. Overlays never advance the
+ * timeline so they reset the run instead of extending it.
+ */
+export declare const flatMotionRule: LintRule;
+/** A move outside the schema enum has no renderer and must fail closed. */
+export declare const unsupportedMotionRule: LintRule;
+/**
+ * A hard cut with a spring ease snaps: the picture jumps while the motion
+ * eases. Blended transitions (crossfade, push, wipe, zoom-through) own their
+ * ease and stay silent, as does the first scene (no incoming transition).
+ */
+export declare const transitionEaseMismatchRule: LintRule;
+/** Accented copy needs room to land: 2 s holds under-read the emphasis. */
+export declare const MIN_ACCENT_HOLD_SECONDS = 3;
+export declare const MIN_HOLD_FLOOR_SECONDS = 2;
+export declare const holdAfterAccentRule: LintRule;

package/dist/lint/motion-craft.js

@@ -0,0 +1,112 @@
+import { MOVES } from "@anvpx/motion-schema";
+/** Moves the renderer understands (schema enum); anything else falls back and must error. */
+const ALLOWED_MOVES = new Set(MOVES);
+/** Ease values that imply a soft landing; pairing them with a hard cut reads as a snap. */
+const SPRING_EASES = new Set(["spring-soft", "spring-snappy"]);
+/** `[...]` accent markup; unmatched or empty brackets stay literal (mirrors scenes markup). */
+const ACCENT_RE = /\[([^[\]]+)\]/;
+const isAccentValue = (value) => {
+    if (typeof value === "string")
+        return ACCENT_RE.test(value);
+    if (!Array.isArray(value))
+        return false;
+    return value.some((item) => typeof item === "string" && ACCENT_RE.test(item));
+};
+const hasAccentText = (props) => Object.entries(props).some(([key, value]) => key !== "caption" && isAccentValue(value));
+const isCopyValue = (value) => {
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (typeof value === "number")
+        return true;
+    if (!Array.isArray(value))
+        return false;
+    return value.some((item) => isCopyValue(item));
+};
+const hasCopyText = (props) => Object.entries(props).some(([key, value]) => key !== "caption" && isCopyValue(value));
+const isStaticMove = (move) => move === undefined || move === "static";
+/**
+ * Three static base scenes in a row read as flat. Overlays never advance the
+ * timeline so they reset the run instead of extending it.
+ */
+export const flatMotionRule = ({ storyboard }) => {
+    const findings = [];
+    let run = 0;
+    storyboard.scenes.forEach((scene, index) => {
+        if (scene.layer === "overlay" || !isStaticMove(scene.move)) {
+            run = 0;
+            return;
+        }
+        run += 1;
+        if (run >= 3) {
+            findings.push({
+                severity: "warning",
+                path: `/scenes/${index}/move`,
+                message: `scene "${scene.id}" is the third flat static scene in a row`,
+                suggestion: "add a move (push-in, pan-l, orbit) or split the beat",
+            });
+        }
+    });
+    return findings;
+};
+/** A move outside the schema enum has no renderer and must fail closed. */
+export const unsupportedMotionRule = ({ storyboard }) => storyboard.scenes.flatMap((scene, index) => {
+    if (scene.layer === "overlay")
+        return [];
+    const move = scene.move;
+    if (move === undefined || ALLOWED_MOVES.has(move))
+        return [];
+    return [
+        {
+            severity: "error",
+            path: `/scenes/${index}/move`,
+            message: `move "${move}" is not implemented`,
+            suggestion: `use one of: ${MOVES.join("|")}`,
+        },
+    ];
+});
+/**
+ * A hard cut with a spring ease snaps: the picture jumps while the motion
+ * eases. Blended transitions (crossfade, push, wipe, zoom-through) own their
+ * ease and stay silent, as does the first scene (no incoming transition).
+ */
+export const transitionEaseMismatchRule = ({ storyboard }) => storyboard.scenes.flatMap((scene, index) => {
+    if (index === 0 || scene.layer === "overlay")
+        return [];
+    if (scene.transition !== "cut")
+        return [];
+    const ease = scene.ease;
+    if (ease === undefined || !SPRING_EASES.has(ease))
+        return [];
+    return [
+        {
+            severity: "warning",
+            path: `/scenes/${index}/ease`,
+            message: `cut paired with spring ease "${ease}" snaps on the cut`,
+            suggestion: 'use ease "out" or "in-out" for cuts',
+        },
+    ];
+});
+/** Accented copy needs room to land: 2 s holds under-read the emphasis. */
+export const MIN_ACCENT_HOLD_SECONDS = 3;
+export const MIN_HOLD_FLOOR_SECONDS = 2;
+const accentHoldFinding = (id, index, duration, props) => {
+    if (!hasCopyText(props) || !hasAccentText(props))
+        return [];
+    return [
+        {
+            severity: "warning",
+            path: `/scenes/${index}/duration`,
+            message: `scene "${id}" has accent markup but holds ${duration}s; accents need >= ${MIN_ACCENT_HOLD_SECONDS}s`,
+            suggestion: `use duration >= ${MIN_ACCENT_HOLD_SECONDS} or drop the accent`,
+        },
+    ];
+};
+export const holdAfterAccentRule = ({ storyboard, timeline }) => timeline.scenes.flatMap((timed) => {
+    const scene = storyboard.scenes[timed.index];
+    if (scene === undefined || scene.layer === "overlay")
+        return [];
+    // min-hold owns durations under 2 s; longer holds already breathe.
+    if (timed.duration < MIN_HOLD_FLOOR_SECONDS || timed.duration >= MIN_ACCENT_HOLD_SECONDS)
+        return [];
+    return accentHoldFinding(scene.id, timed.index, timed.duration, scene.props);
+});

package/dist/lint/narration-pace.d.ts

@@ -0,0 +1,6 @@
+import type { LintRule } from "./types.ts";
+/** Words per second bounds (target ~2.2, 130 wpm). */
+export declare const MAX_NARRATION_WPS = 3;
+export declare const MIN_NARRATION_WPS = 1.2;
+/** Only scenes with narration are checked. */
+export declare const narrationPaceRule: LintRule;

package/dist/lint/narration-pace.js

@@ -0,0 +1,35 @@
+/** Words per second bounds (target ~2.2, 130 wpm). */
+export const MAX_NARRATION_WPS = 3;
+export const MIN_NARRATION_WPS = 1.2;
+const wordCount = (text) => text.split(/\s+/).filter(Boolean).length;
+/** Only scenes with narration are checked. */
+export const narrationPaceRule = ({ storyboard, timeline }) => timeline.scenes.flatMap((timed) => {
+    const narration = storyboard.scenes[timed.index]?.narration;
+    const count = narration === undefined ? 0 : wordCount(narration);
+    if (count === 0 || timed.duration <= 0)
+        return [];
+    const rate = count / timed.duration;
+    const path = `/scenes/${timed.index}/narration`;
+    const said = `narration ${count} words in ${timed.duration}s is ${rate.toFixed(1)} words/s`;
+    if (rate > MAX_NARRATION_WPS) {
+        return [
+            {
+                severity: "warning",
+                path,
+                message: `${said}; max ${MAX_NARRATION_WPS}`,
+                suggestion: `set duration >= ${Math.ceil(count / MAX_NARRATION_WPS)} or cut narration`,
+            },
+        ];
+    }
+    if (rate < MIN_NARRATION_WPS) {
+        return [
+            {
+                severity: "warning",
+                path,
+                message: `${said}; min ${MIN_NARRATION_WPS}`,
+                suggestion: `set duration <= ${Math.floor(count / MIN_NARRATION_WPS)} or add narration`,
+            },
+        ];
+    }
+    return [];
+});

package/dist/lint/overlays.d.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "./types.ts";
+/** More simultaneous overlays than this cover too much of the picture. */
+export declare const MAX_SIMULTANEOUS_OVERLAYS = 2;
+/** `over` must name an existing base scene (not an overlay, not itself). */
+export declare const overlayTargetRule: LintRule;
+/** An overlay must end no later than the base scene it covers. */
+export declare const overlayFitRule: LintRule;
+/** Warns when 3+ overlays are visible at once. */
+export declare const overlayStackRule: LintRule;

package/dist/lint/overlays.js

@@ -0,0 +1,64 @@
+/** Float slack when comparing absolute seconds. */
+const EPSILON = 1e-6;
+/** More simultaneous overlays than this cover too much of the picture. */
+export const MAX_SIMULTANEOUS_OVERLAYS = 2;
+const baseIds = (storyboardScenes) => new Set(storyboardScenes.filter((scene) => scene.layer !== "overlay").map((scene) => scene.id));
+/** `over` must name an existing base scene (not an overlay, not itself). */
+export const overlayTargetRule = ({ storyboard, timeline }) => {
+    const bases = baseIds(storyboard.scenes);
+    const ids = new Set(storyboard.scenes.map((scene) => scene.id));
+    return timeline.overlays.flatMap((overlay) => {
+        if (bases.has(overlay.over))
+            return [];
+        const reason = ids.has(overlay.over)
+            ? `"${overlay.over}" is an overlay, not a base scene`
+            : `"${overlay.over}" is not a scene`;
+        return [
+            {
+                severity: "error",
+                path: `/scenes/${overlay.index}/over`,
+                message: `over ${reason}`,
+                suggestion: `use one of: ${[...bases].join("|")}`,
+            },
+        ];
+    });
+};
+/** An overlay must end no later than the base scene it covers. */
+export const overlayFitRule = ({ timeline }) => timeline.overlays.flatMap((overlay) => {
+    const base = timeline.scenes.find((scene) => scene.id === overlay.over);
+    if (!base)
+        return [];
+    const baseEnd = Math.round((base.start + base.duration) * 1000) / 1000;
+    if (overlay.end <= baseEnd + EPSILON)
+        return [];
+    const room = Math.round((baseEnd - overlay.start) * 1000) / 1000;
+    return [
+        {
+            severity: "error",
+            path: `/scenes/${overlay.index}/duration`,
+            message: `ends at ${overlay.end}s, after "${base.id}" ends at ${baseEnd}s`,
+            suggestion: room > 0
+                ? `use duration <= ${room} or a smaller offset`
+                : `use an offset < ${Math.round((baseEnd - base.start) * 1000) / 1000}`,
+        },
+    ];
+});
+const crowded = (overlays) => {
+    const byStart = [...overlays].sort((a, b) => a.start - b.start || a.index - b.index);
+    const flagged = [];
+    let active = [];
+    for (const overlay of byStart) {
+        active = active.filter((other) => other.end > overlay.start + EPSILON);
+        active.push(overlay);
+        if (active.length > MAX_SIMULTANEOUS_OVERLAYS)
+            flagged.push(overlay);
+    }
+    return flagged.sort((a, b) => a.index - b.index);
+};
+/** Warns when 3+ overlays are visible at once. */
+export const overlayStackRule = ({ timeline }) => crowded(timeline.overlays).map((overlay) => ({
+    severity: "warning",
+    path: `/scenes/${overlay.index}/offset`,
+    message: `more than ${MAX_SIMULTANEOUS_OVERLAYS} overlays visible at ${overlay.start}s`,
+    suggestion: "stagger the overlays or drop one",
+}));

package/dist/lint/reading-time.d.ts

@@ -0,0 +1,5 @@
+import type { LintRule } from "./types.ts";
+/** 180 words per minute maximum. */
+export declare const WORDS_PER_SECOND = 3;
+/** At least one reading-second per 3 on-screen words. */
+export declare const readingTimeRule: LintRule;

package/dist/lint/reading-time.js

@@ -0,0 +1,17 @@
+/** 180 words per minute maximum. */
+export const WORDS_PER_SECOND = 3;
+/** At least one reading-second per 3 on-screen words. */
+export const readingTimeRule = ({ timeline, words }) => timeline.scenes.flatMap((scene) => {
+    const count = words[scene.index] ?? 0;
+    const needed = Math.ceil(count / WORDS_PER_SECOND);
+    if (scene.duration >= needed)
+        return [];
+    return [
+        {
+            severity: "error",
+            path: `/scenes/${scene.index}/duration`,
+            message: `${count} words need >= ${needed}s to read (max 180 wpm); duration is ${scene.duration}s`,
+            suggestion: `set duration >= ${needed} or cut text`,
+        },
+    ];
+});

package/dist/lint/safe-zone-9x16.d.ts

@@ -0,0 +1,11 @@
+import type { LintRule } from "./types.ts";
+/**
+ * Platform-tagged 9:16 frames: warns when the estimated content block of a base scene (or the progress
+ * overlay) reaches into the platform's `safe{top,bottom,side}` margins.
+ *
+ * Estimate, not a measurement: heights come from `layout-estimate.ts` (scene CSS + a generous glyph-width
+ * model, roughly +-20 %), content is assumed vertically centred in the padded frame as the scenes lay it
+ * out, and the `bug` overlay and scene types without an estimator are not checked. Always a warning: the
+ * numbers in the platform data are unverified approximations.
+ */
+export declare const safeZone9x16Rule: LintRule;