@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/doctor/format.js

@@ -0,0 +1,41 @@
+import { EXIT } from "../exit-codes.js";
+const STATUSES = ["ok", "usable", "missing", "unknown"];
+const STATUS_WIDTH = Math.max(...STATUSES.map((s) => s.length));
+const GAP = "  ";
+export function summarize(results) {
+    const counts = { ok: 0, usable: 0, missing: 0, unknown: 0 };
+    for (const r of results)
+        counts[r.status] += 1;
+    return counts;
+}
+/** 127 when a required tool is missing, else 2 when a required check is unknown, else 0. */
+export function exitCodeFor(results) {
+    const required = results.filter((r) => r.required);
+    if (required.some((r) => r.status === "missing"))
+        return EXIT.MISSING_TOOL;
+    if (required.some((r) => r.status === "unknown"))
+        return EXIT.USAGE;
+    return EXIT.OK;
+}
+function row(r, idWidth) {
+    const detail = [r.version, r.hint && r.status !== "ok" ? `-> ${r.hint}` : undefined]
+        .filter((part) => part !== undefined)
+        .join(GAP);
+    return [r.id.padEnd(idWidth), r.status.padEnd(STATUS_WIDTH), detail].join(GAP).trimEnd();
+}
+export function formatTable(results) {
+    const idWidth = Math.max(0, ...results.map((r) => r.id.length));
+    const { ok, usable, missing, unknown } = summarize(results);
+    const summary = `doctor: ${ok} ok, ${usable} usable, ${missing} missing, ${unknown} unknown`;
+    return `${[...results.map((r) => row(r, idWidth)), summary].join("\n")}\n`;
+}
+/** One compact line: [{id, status, version?, hint?}]. */
+export function formatJson(results) {
+    const rows = results.map(({ id, status, version, hint }) => ({
+        id,
+        status,
+        ...(version === undefined ? {} : { version }),
+        ...(hint === undefined ? {} : { hint }),
+    }));
+    return `${JSON.stringify(rows)}\n`;
+}

package/dist/doctor/heal.d.ts

@@ -0,0 +1,14 @@
+import type { Io } from "../types.ts";
+import type { CheckResult } from "./types.ts";
+/** Rows `mk doctor --fix` is allowed to touch. Everything else is hint-only. */
+export declare const SAFE_HEAL_IDS: readonly string[];
+export interface HealEntry {
+    id: string;
+    healed: boolean;
+    detail: string;
+}
+export declare function healSafeRows(results: readonly CheckResult[], io: Io): Promise<HealEntry[]>;
+/** `healed: a, b` plus `still missing: c` (second line only when needed). */
+export declare function formatHealLines(healed: readonly HealEntry[]): string;
+/** One compact line: {results: [...], healed: [{id, healed, detail}]}. */
+export declare function formatJsonWithHeal(results: readonly CheckResult[], healed: readonly HealEntry[]): string;

package/dist/doctor/heal.js

@@ -0,0 +1,71 @@
+/** Rows `mk doctor --fix` is allowed to touch. Everything else is hint-only. */
+export const SAFE_HEAL_IDS = [
+    "hyperframes",
+    "chrome-headless-shell",
+    "fonts",
+    "icons",
+    "templates",
+    "bin",
+    "catalog",
+];
+const SAFE = new Set(SAFE_HEAL_IDS);
+/**
+ * Attempt a safe heal for every non-ok safe row. Never destructive: no delete,
+ * no filesystem writes, no network beyond `npx hyperframes browser ensure` for
+ * chrome. Hyperframes pin mismatches, fonts, icons, templates, bin and catalog
+ * only report their reinstall hint; only chrome `missing` runs the ensure
+ * command. Returns one entry per attempted row.
+ */
+function needsHeal(r) {
+    return SAFE.has(r.id) && r.status !== "ok";
+}
+function hintEntry(r) {
+    return { id: r.id, healed: false, detail: r.hint ?? "reinstall @anvpx/motion" };
+}
+async function ensureChrome(r, io) {
+    let code = 127;
+    try {
+        code = (await io.run("npx", ["hyperframes", "browser", "ensure"])).code;
+    }
+    catch {
+        code = 1;
+    }
+    return code === 0
+        ? { id: r.id, healed: true, detail: "npx hyperframes browser ensure succeeded" }
+        : { id: r.id, healed: false, detail: r.hint ?? "npx hyperframes browser ensure failed" };
+}
+async function healOne(r, io) {
+    if (!needsHeal(r))
+        return undefined;
+    if (r.id === "chrome-headless-shell" && r.status === "missing")
+        return ensureChrome(r, io);
+    return hintEntry(r);
+}
+export async function healSafeRows(results, io) {
+    const out = [];
+    for (const r of results) {
+        const healed = await healOne(r, io);
+        if (healed)
+            out.push(healed);
+    }
+    return out;
+}
+/** `healed: a, b` plus `still missing: c` (second line only when needed). */
+export function formatHealLines(healed) {
+    const healedIds = healed.filter((h) => h.healed).map((h) => h.id);
+    const missingIds = healed.filter((h) => !h.healed).map((h) => h.id);
+    const healedLine = `healed: ${healedIds.length > 0 ? healedIds.join(", ") : "none"}\n`;
+    if (missingIds.length === 0)
+        return healedLine;
+    return `${healedLine}still missing: ${missingIds.join(", ")}\n`;
+}
+/** One compact line: {results: [...], healed: [{id, healed, detail}]}. */
+export function formatJsonWithHeal(results, healed) {
+    const rows = results.map(({ id, status, version, hint }) => ({
+        id,
+        status,
+        ...(version === undefined ? {} : { version }),
+        ...(hint === undefined ? {} : { hint }),
+    }));
+    return `${JSON.stringify({ results: rows, healed })}\n`;
+}

package/dist/doctor/pins.d.ts

@@ -0,0 +1,8 @@
+import type { Pins } from "./types.ts";
+export declare const PIN_KEYS: {
+    readonly hyperframes: "motionKit.pins.hyperframes";
+    readonly chromeHeadlessShell: "motionKit.pins.chromeHeadlessShell";
+};
+export declare function readPins(packageJson: unknown): Pins;
+/** True when the manifest declares `motionKit.pins`; only then is pin advice actionable. */
+export declare function hasPins(packageJson: unknown): boolean;

package/dist/doctor/pins.js

@@ -0,0 +1,28 @@
+export const PIN_KEYS = {
+    hyperframes: "motionKit.pins.hyperframes",
+    chromeHeadlessShell: "motionKit.pins.chromeHeadlessShell",
+};
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : undefined;
+}
+function pinString(pins, key) {
+    const value = pins?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function readPins(packageJson) {
+    const pins = asRecord(asRecord(asRecord(packageJson)?.motionKit)?.pins);
+    const result = {};
+    const hyperframes = pinString(pins, "hyperframes");
+    const chrome = pinString(pins, "chromeHeadlessShell");
+    if (hyperframes)
+        result.hyperframes = hyperframes;
+    if (chrome)
+        result.chromeHeadlessShell = chrome;
+    return result;
+}
+/** True when the manifest declares `motionKit.pins`; only then is pin advice actionable. */
+export function hasPins(packageJson) {
+    return asRecord(asRecord(asRecord(packageJson)?.motionKit)?.pins) !== undefined;
+}

package/dist/doctor/skills.d.ts

@@ -0,0 +1,15 @@
+import type { Check } from "./types.ts";
+/** Turns a package id into a path; injectable so tests need no real package tree. */
+export type CoreResolver = (id: string) => string;
+/**
+ * Candidate `skills/motion-kit` dirs, installed copy first. `@anvpx/motion/package.json` is
+ * the authoritative root (its exports map ships the manifest); the bare `@anvpx/motion`
+ * entry covers older installs that hide it, and the repo checkout covers development runs
+ * where the package is not resolvable. The repo is never a candidate once core resolves.
+ */
+export declare const skillsDirs: (resolveCorePkg?: CoreResolver) => string[];
+export declare const skillsFiles: (resolveCorePkg?: CoreResolver) => string[];
+/** `mk --help` target: the installed SKILL.md when it exists, else the repo copy. */
+export declare const helpSkillFile: (resolveCorePkg?: CoreResolver) => string;
+export declare const makeSkillsCheck: (resolveCorePkg?: CoreResolver) => Check;
+export declare const checkSkills: Check;

package/dist/doctor/skills.js

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { resolvePluginSourceDir } from "../plugin/install.js";
+const defaultResolve = (id) => createRequire(import.meta.url).resolve(id);
+const skillsDir = (root) => join(root, "skills", "motion-kit");
+/**
+ * Candidate `skills/motion-kit` dirs, installed copy first. `@anvpx/motion/package.json` is
+ * the authoritative root (its exports map ships the manifest); the bare `@anvpx/motion`
+ * entry covers older installs that hide it, and the repo checkout covers development runs
+ * where the package is not resolvable. The repo is never a candidate once core resolves.
+ */
+export const skillsDirs = (resolveCorePkg = defaultResolve) => {
+    const installed = [];
+    try {
+        installed.push(skillsDir(dirname(resolveCorePkg("@anvpx/motion/package.json"))));
+    }
+    catch {
+        // Older installs hide ./package.json; the bare export still names the root.
+    }
+    try {
+        installed.push(skillsDir(dirname(dirname(resolveCorePkg("@anvpx/motion")))));
+    }
+    catch {
+        // Not resolvable from here: fall back to the repo checkout below.
+    }
+    if (installed.length > 0)
+        return [...new Set(installed)];
+    return [skillsDir(dirname(dirname(resolvePluginSourceDir(resolveCorePkg))))];
+};
+export const skillsFiles = (resolveCorePkg = defaultResolve) => skillsDirs(resolveCorePkg).map((dir) => join(dir, "SKILL.md"));
+/** `mk --help` target: the installed SKILL.md when it exists, else the repo copy. */
+export const helpSkillFile = (resolveCorePkg) => {
+    const files = skillsFiles(resolveCorePkg);
+    return (files.find((file) => existsSync(file)) ?? files[0] ?? join("skills", "motion-kit", "SKILL.md"));
+};
+const REFERENCES_HINT = "reinstall @anvpx/motion (it ships skills/motion-kit/references)";
+const MISSING_HINT = "reinstall @anvpx/motion";
+/** The row for one candidate copy, or undefined when that copy is absent. */
+async function skillAt(host, dir) {
+    if (!(await host.exists(join(dir, "SKILL.md")).catch(() => false)))
+        return undefined;
+    const references = await host.listDir(join(dir, "references")).catch(() => []);
+    if (references.length === 0) {
+        return { id: "skills", status: "usable", required: false, version: dir, hint: REFERENCES_HINT };
+    }
+    const count = `${references.length} reference${references.length === 1 ? "" : "s"}`;
+    return { id: "skills", status: "ok", required: false, version: `${dir} (${count})` };
+}
+export const makeSkillsCheck = (resolveCorePkg = defaultResolve) => async ({ host }) => {
+    for (const dir of skillsDirs(resolveCorePkg)) {
+        const found = await skillAt(host, dir);
+        if (found)
+            return found;
+    }
+    return { id: "skills", status: "missing", required: false, hint: MISSING_HINT };
+};
+export const checkSkills = makeSkillsCheck();

package/dist/doctor/types.d.ts

@@ -0,0 +1,36 @@
+import type { Host, Runner } from "../types.ts";
+/**
+ * ok: present and as wanted. usable: present but not as pinned/preferred. missing: absent or
+ * below the minimum. unknown: detection could not decide; never reported as ok or missing.
+ */
+export type CheckStatus = "ok" | "usable" | "missing" | "unknown";
+export interface CheckResult {
+    id: string;
+    status: CheckStatus;
+    /** A required tool that is missing or unknown fails `mk doctor`. */
+    required: boolean;
+    version?: string;
+    /** What to do about it; only shown on non-ok results. */
+    hint?: string;
+}
+/** Pins recorded in the repo's package.json under `motionKit.pins`. */
+export interface Pins {
+    hyperframes?: string;
+    chromeHeadlessShell?: string;
+}
+/** Files `pnpm install` / the repo vendor; injected so tests need no real disk. */
+export interface Vendored {
+    /** Font family ids whose bundled woff2/licence files cannot be read. */
+    missingFonts(): readonly string[];
+    /** The vendored icon set (installed `@anvpx/motion-assets` icons.json). */
+    iconsFile: string;
+}
+export interface CheckContext {
+    run: Runner;
+    host: Host;
+    pins: Pins;
+    /** Whether the root manifest declares `motionKit.pins` at all; consumer projects do not. */
+    pinsPresent: boolean;
+    vendored: Vendored;
+}
+export type Check = (ctx: CheckContext) => Promise<CheckResult>;

package/dist/doctor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/doctor/vendored.d.ts

@@ -0,0 +1,15 @@
+import type { Vendored } from "./types.ts";
+/** Turns a package id into a path; injectable so tests need no real package tree. */
+export type PackageResolver = (id: string) => string;
+/**
+ * Resolve the vendored icon set.
+ * Published layout first: the staged core ships `icons/icons.json` so a
+ * consumer install (`node_modules/@anvpx/motion/icons/icons.json`) works
+ * without the workspace checkout or a separate `@anvpx/motion-assets` install.
+ * Later candidates cover the installed `@anvpx/motion-assets` package (resolved
+ * by name, since installed siblings are `@anvpx/motion-<name>`) and the dev
+ * workspace. Every candidate is verified with `existsSync`; a total miss throws
+ * a fixable error instead of returning a path that does not exist.
+ */
+export declare const resolveIconsFile: (resolvePkg?: PackageResolver) => string;
+export declare const defaultVendored: () => Vendored;

package/dist/doctor/vendored.js

@@ -0,0 +1,90 @@
+import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bundleFonts, FONT_FAMILIES } from "@anvpx/motion-build";
+/** Families whose pinned `@fontsource/*` files cannot be read (`bundleFonts` is the render-time reader). */
+const missingFonts = () => Object.keys(FONT_FAMILIES).filter((id) => {
+    try {
+        bundleFonts([id]);
+        return false;
+    }
+    catch {
+        return true;
+    }
+});
+const nodeRequire = createRequire(import.meta.url);
+const defaultResolve = (id) => nodeRequire.resolve(id);
+/** Icons beside the resolved build package; records misses in `searched`. */
+const buildAnchoredIcons = (resolvePkg, searched) => {
+    try {
+        const buildDir = dirname(realpathSync(resolvePkg("@anvpx/motion-build")));
+        // Installed siblings are `@anvpx/motion-assets`; the dev checkout names the
+        // directory `assets`. Both hold `icons/icons.json`, so try each before giving up.
+        for (const sibling of ["motion-assets", "assets"]) {
+            const candidate = join(buildDir, "..", "..", sibling, "icons", "icons.json");
+            if (existsSync(candidate))
+                return candidate;
+            searched.push(candidate);
+        }
+    }
+    catch {
+        // Not resolvable here: the caller falls through to the fixable error.
+    }
+    return undefined;
+};
+/**
+ * Resolve the vendored icon set.
+ * Published layout first: the staged core ships `icons/icons.json` so a
+ * consumer install (`node_modules/@anvpx/motion/icons/icons.json`) works
+ * without the workspace checkout or a separate `@anvpx/motion-assets` install.
+ * Later candidates cover the installed `@anvpx/motion-assets` package (resolved
+ * by name, since installed siblings are `@anvpx/motion-<name>`) and the dev
+ * workspace. Every candidate is verified with `existsSync`; a total miss throws
+ * a fixable error instead of returning a path that does not exist.
+ */
+export const resolveIconsFile = (resolvePkg = defaultResolve) => {
+    const searched = [];
+    // Staged copies inside the published core tarball (from core/dist or from a
+    // cli/dist staged inside a core install). WHATWG URL resolution normalizes
+    // the `..` segments, so the returned path never contains parent traversal.
+    for (const candidate of [
+        fileURLToPath(new URL("../../icons/icons.json", import.meta.url)),
+        fileURLToPath(new URL("../icons/icons.json", import.meta.url)),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+        searched.push(candidate);
+    }
+    try {
+        const direct = resolvePkg("@anvpx/motion-assets/icons/icons.json");
+        if (existsSync(direct))
+            return direct;
+        searched.push(direct);
+    }
+    catch {
+        /* fall through to package-dir resolution */
+    }
+    try {
+        const pkg = resolvePkg("@anvpx/motion-assets/package.json");
+        const viaPkg = join(dirname(pkg), "icons", "icons.json");
+        if (existsSync(viaPkg))
+            return viaPkg;
+        searched.push(viaPkg);
+    }
+    catch {
+        /* fall through to build-anchored resolution */
+    }
+    const viaBuild = buildAnchoredIcons(resolvePkg, searched);
+    if (viaBuild !== undefined)
+        return viaBuild;
+    const fallback = fileURLToPath(new URL("./icons.json", import.meta.url));
+    if (existsSync(fallback))
+        return fallback;
+    searched.push(fallback);
+    throw new Error(`Cannot locate icons.json (fixable: reinstall @anvpx/motion with its dependencies). Searched: ${searched.join(", ")}`);
+};
+export const defaultVendored = () => ({
+    missingFonts,
+    iconsFile: resolveIconsFile(),
+});

package/dist/doctor/version.d.ts

@@ -0,0 +1,8 @@
+export interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/** Pulls the first version out of text; the pattern must capture major, minor, optional patch. */
+export declare function parseVersion(text: string, pattern?: RegExp): Version | undefined;
+export declare function formatVersion(v: Version): string;

package/dist/doctor/version.js

@@ -0,0 +1,11 @@
+const GENERIC = /(\d+)\.(\d+)(?:\.(\d+))?/;
+/** Pulls the first version out of text; the pattern must capture major, minor, optional patch. */
+export function parseVersion(text, pattern = GENERIC) {
+    const match = pattern.exec(text);
+    if (!match)
+        return undefined;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3] ?? 0) };
+}
+export function formatVersion(v) {
+    return `${v.major}.${v.minor}.${v.patch}`;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,16 @@
+/** The one place exit codes are defined; every command returns one of these. Documented in README.md. */
+export declare const EXIT: {
+    /** Success; warnings allowed. */
+    readonly OK: 0;
+    /** Tool, build or render failure. */
+    readonly ERROR: 1;
+    /** Invalid input: bad flags, unreadable file, or a storyboard that fails validation. Also a check that could not be decided (verify/qc UNKNOWN, doctor unknown). */
+    readonly USAGE: 2;
+    /** `mk render --gated` found no approval for the current storyboard hash (ask the user, then `mk approve`). */
+    readonly AWAITING_APPROVAL: 4;
+    /** QA failed: `mk verify` found a fatal finding. */
+    readonly QA_FAIL: 5;
+    /** A required external tool is missing or cannot be run. */
+    readonly MISSING_TOOL: 127;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];

package/dist/exit-codes.js

@@ -0,0 +1,15 @@
+/** The one place exit codes are defined; every command returns one of these. Documented in README.md. */
+export const EXIT = {
+    /** Success; warnings allowed. */
+    OK: 0,
+    /** Tool, build or render failure. */
+    ERROR: 1,
+    /** Invalid input: bad flags, unreadable file, or a storyboard that fails validation. Also a check that could not be decided (verify/qc UNKNOWN, doctor unknown). */
+    USAGE: 2,
+    /** `mk render --gated` found no approval for the current storyboard hash (ask the user, then `mk approve`). */
+    AWAITING_APPROVAL: 4,
+    /** QA failed: `mk verify` found a fatal finding. */
+    QA_FAIL: 5,
+    /** A required external tool is missing or cannot be run. */
+    MISSING_TOOL: 127,
+};

package/dist/fit/command.d.ts

@@ -0,0 +1,5 @@
+import { type TemplateEnv } from "../template/env.ts";
+import type { Command } from "../types.ts";
+/** `mk fit`; `env` is injectable for tests. */
+export declare const makeFitCommand: (env?: () => TemplateEnv) => Command;
+export declare const fitCommand: Command;

package/dist/fit/command.js

@@ -0,0 +1,154 @@
+import { MIN_HOLD_SECONDS, resolveTimeline, sceneWords, validateStoryboardFull, WORDS_PER_SECOND, } from "@anvpx/motion-build";
+import { parseFlags, requireStoryboard, textFlag, usageError } from "../args.js";
+import { readProvenance } from "../preview/provenance.js";
+import { checkStoryboard } from "../storyboard/check.js";
+import { editStoryboard, round1 } from "../storyboard/edit.js";
+import { defaultEnv, findTemplate } from "../template/env.js";
+import { fitDurations } from "./solve.js";
+import { fitTarget } from "./target.js";
+const USAGE = `mk fit <storyboard.json> --seconds N
+mk fit <storyboard.json> --bpm B --bars R
+
+Stretch or squeeze a storyboard to N seconds in total. Every base scene is scaled by one common factor,
+kept inside its type's range, then validated and written atomically (deterministic; nothing written when refused).
+Range per scene: from the template's pacing.json (the smallest to the largest seconds of that scene type across
+short/standard/long), never under the reading time of its text (3 words per second) or the 2 s minimum hold.
+Without template provenance or pacing for a type, the range is the floor up to 1.5x the current length.
+Refuses, and says why, when N is outside what the scenes allow: add scenes (\`mk scene add\`) or change N.
+  --seconds N   target total (the same total \`mk validate\` and \`mk preview\` report)
+Prints before/after on <= 3 lines. Overlays scale with the scene they cover.
+`;
+const FALLBACK_STRETCH = 1.5;
+const MAX_LISTED = 8;
+const MAX_FLOORS = 2;
+const hardFloor = (words) => Math.max(MIN_HOLD_SECONDS, Math.ceil(words / WORDS_PER_SECOND));
+function rowFor(type, cur, words, pacing) {
+    const floor = hardFloor(words);
+    const seconds = Object.values(pacing?.sceneSeconds[type] ?? {});
+    if (seconds.length === 0)
+        return { cur, lo: floor, hi: Math.max(floor, cur * FALLBACK_STRETCH) };
+    return {
+        cur,
+        lo: Math.max(floor, Math.min(...seconds, cur)),
+        hi: Math.max(floor, cur, ...seconds),
+    };
+}
+const basesOf = (board, timeline, pacing) => timeline.scenes.map((timed) => {
+    const entry = board.scenes[timed.index];
+    const words = sceneWords(entry.props, entry.type);
+    const read = Math.ceil(words / WORDS_PER_SECOND);
+    return {
+        id: timed.id,
+        cur: timed.duration,
+        words,
+        read,
+        row: rowFor(entry.type, timed.duration, words, pacing),
+    };
+});
+const listed = (before, after) => {
+    const changes = before.map((scene, i) => `${scene.id} ${round1(scene.cur)}>${after[i]}`);
+    const shown = changes.slice(0, MAX_LISTED).join(", ");
+    return changes.length > MAX_LISTED ? `${shown} (+${changes.length - MAX_LISTED} more)` : shown;
+};
+const readingFloors = (bases) => [...bases]
+    .sort((a, b) => b.read - a.read)
+    .slice(0, MAX_FLOORS)
+    .map((scene) => `${scene.id} needs >= ${scene.read}s to read (${scene.words} words)`)
+    .join("; ");
+/** Why the target is out of reach, in terms the author can act on. */
+function refusal(reason, range, target, bases, source) {
+    if (reason === "below") {
+        return `${target}s is under the ${range.min}s these scenes need; reading time floors: ${readingFloors(bases)}. Cut text or scenes, or raise --seconds`;
+    }
+    return `${target}s is over the ${range.max}s these scenes can stretch to (range ${range.min}-${range.max}s, ${source}). Add scenes (mk scene add) or lower --seconds`;
+}
+/** Overlay `duration` and `offset` follow the scale of the base scene they cover. */
+function scaleOverlay(scene, scale) {
+    for (const key of ["duration", "offset"]) {
+        const value = scene[key];
+        if (typeof value === "number")
+            scene[key] = round1(value * scale);
+    }
+}
+/** A copy of the storyboard with the new durations; overlays scale with the scene they cover. */
+function withDurations(doc, bases, seconds) {
+    const next = structuredClone(doc);
+    const ratio = new Map();
+    for (const [i, base] of bases.entries()) {
+        const to = seconds[i] ?? base.cur;
+        ratio.set(base.id, to / base.cur);
+        const scene = next.scenes.find((entry) => entry.id === base.id);
+        if (scene)
+            scene.duration = to;
+    }
+    for (const scene of next.scenes) {
+        const scale = scene.layer === "overlay" ? ratio.get(String(scene.over)) : undefined;
+        if (scale !== undefined)
+            scaleOverlay(scene, scale);
+    }
+    return next;
+}
+/** The valid storyboard and its timeline, or undefined when validation or lint has errors. */
+function resolveBoard(doc) {
+    const valid = validateStoryboardFull(doc);
+    if (!valid.ok || checkStoryboard(doc).errors.length > 0)
+        return undefined;
+    const timeline = resolveTimeline(valid.value);
+    return timeline.ok ? { board: valid.value, timeline: timeline.value } : undefined;
+}
+/** The edit: resolve, fit, and describe; refuses (never throws) when it cannot. */
+function fitStoryboard(doc, request) {
+    const resolved = resolveBoard(doc);
+    if (resolved === undefined) {
+        return { ok: false, message: "the storyboard has errors; fix them first (mk validate)" };
+    }
+    const { board, timeline } = resolved;
+    const bases = basesOf(board, timeline, request.pacing);
+    const overlap = timeline.scenes.reduce((sum, scene) => sum + scene.overlap, 0);
+    const fitted = fitDurations(bases.map((base) => base.row), request.target + overlap);
+    if (!fitted.ok) {
+        const range = { min: round1(fitted.min - overlap), max: round1(fitted.max - overlap) };
+        const why = refusal(fitted.reason, range, request.target, bases, request.source);
+        return { ok: false, message: `refused, nothing written: ${why}` };
+    }
+    return {
+        ok: true,
+        value: withDurations(doc, bases, fitted.seconds),
+        lines: (after) => [
+            `fit ok | ${round1(timeline.total)}s -> ${round1(after.total ?? 0)}s (target ${request.target}s) | ${bases.length} scenes | ${request.source}`,
+            listed(bases, fitted.seconds),
+        ],
+    };
+}
+/** The pacing of the template that made the storyboard, when it is installed. */
+async function pacingOf(env, io, path) {
+    const provenance = await readProvenance(io.host, path);
+    const found = provenance && findTemplate(env, io, provenance.template.split("@")[0] ?? "");
+    if (!provenance || !found?.ok) {
+        return { pacing: undefined, source: "fallback range (no template pacing)" };
+    }
+    return { pacing: found.template.pacing, source: provenance.template };
+}
+/** `mk fit`; `env` is injectable for tests. */
+export const makeFitCommand = (env = defaultEnv) => ({
+    name: "fit",
+    summary: "stretch or squeeze a storyboard to --seconds N or --bpm/--bars within each scene's range",
+    async run(args, io) {
+        const parsed = parseFlags("fit", USAGE, args, { seconds: { type: "string" }, bpm: { type: "string" }, bars: { type: "string" } }, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const path = requireStoryboard("fit", USAGE, parsed.positionals, io);
+        if (typeof path !== "string")
+            return path.code;
+        const resolved = fitTarget({
+            seconds: textFlag(parsed.flags, "seconds"),
+            bpm: textFlag(parsed.flags, "bpm"),
+            bars: textFlag(parsed.flags, "bars"),
+        });
+        if (!resolved.ok)
+            return usageError("fit", USAGE, resolved.message, io).code;
+        const request = { target: resolved.target, ...(await pacingOf(env(), io, path)) };
+        return editStoryboard("fit", path, io, (doc) => fitStoryboard(doc, request));
+    },
+});
+export const fitCommand = makeFitCommand();

package/dist/fit/solve.d.ts

@@ -0,0 +1,21 @@
+/** One base scene: current seconds and the seconds it may be stretched or squeezed to. */
+export interface FitRow {
+    readonly cur: number;
+    readonly lo: number;
+    readonly hi: number;
+}
+export type FitResult = {
+    ok: true;
+    seconds: number[];
+} | {
+    ok: false;
+    reason: "below" | "above";
+    min: number;
+    max: number;
+};
+/**
+ * Scales every scene by one common factor, clamped to each scene's [lo, hi], so the durations
+ * add up to `targetSum` seconds (to 0.1 s). Deterministic: bisection on the factor, then the
+ * rounding remainder is distributed by largest fractional part.
+ */
+export declare function fitDurations(rows: readonly FitRow[], targetSum: number): FitResult;