@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/preview/manifest.d.ts

@@ -0,0 +1,94 @@
+import { type ApprovalInputManifest } from "../approval/hash.ts";
+/** Pack directory suffix: the pack of `<stem>.json` is `<out>/<stem>.preview`. */
+export declare const PREVIEW_SUFFIX = ".preview";
+export declare const PREVIEW_JSON = "preview.json";
+/** Default pack location base: `<storyboard dir>/out` (the pack is `<out>/preview`). */
+export declare const defaultOut: (storyboard: string) => string;
+/** `<out>/<stem>.preview`: one pack per storyboard. */
+export declare const packDir: (out: string, storyboard: string) => string;
+export declare const previewManifestPath: (out: string, storyboard: string) => string;
+export type ClipResult = {
+    status: "ok";
+    file: string;
+    sec: number;
+} | {
+    status: "skipped";
+    reason: string;
+};
+export interface StillRow {
+    /** Relative to the pack directory. */
+    file: string;
+    scene: string;
+    t: number;
+    theme: string;
+}
+export interface ChecklistItem {
+    id: string;
+    text: string;
+    done: boolean;
+}
+/** Exact CLI inputs a pack was previewed with, so `mk approve` can infer them (A4). */
+export interface PreviewInputs {
+    readonly assetsDir: string | null;
+    readonly ledger: string | null;
+    readonly audioManifest: string | null;
+    readonly music: string | null;
+    readonly musicVolume: number | null;
+    readonly musicLicense: string | null;
+}
+/** `preview.json`: what the user is about to approve. Written last; `hash` binds it to the storyboard. */
+export interface PreviewManifest {
+    /** Approval hash (storyboard + vendored themes) the pack was made from. */
+    hash: string;
+    /** Exact visual inputs the user approves (single resolver); gated render rechecks it. */
+    inputManifest: ApprovalInputManifest;
+    /** Canonical sha of `inputManifest`; no timestamp or machine path enters it. */
+    inputManifestSha256: string;
+    storyboard: string;
+    /** Absolute inputs (never approval identity) `mk approve` reuses when flags are omitted. */
+    inputs: PreviewInputs;
+    /** `id@version` when the storyboard came from `mk new`, else null. */
+    template: string | null;
+    blueprint: string | null;
+    style: string | null;
+    theme: string;
+    /** Paired theme used for the dark/light extras, or null. */
+    pair: string | null;
+    frame: {
+        width: number;
+        height: number;
+        fps: number;
+    };
+    totalSec: number;
+    scenes: {
+        id: string;
+        type: string;
+        start: number;
+        duration: number;
+    }[];
+    stills: StillRow[];
+    contact: string | null;
+    clip: ClipResult;
+    /** Audible binding: voice manifest + wav hashes the clip was mixed from. Silent packs record audible:false. */
+    audioMix: {
+        manifestSha: string | null;
+        wavSha: string | null;
+        audible: boolean;
+        /** AU-01 bed binding the clip was mixed from; null when narration-only/silent. */
+        musicSha: string | null;
+        musicVolume: number | null;
+        musicLicenseSha: string | null;
+    };
+    /** Labelled estimate; null when the clip was skipped (nothing measured). */
+    estFullRenderSec: number | null;
+    estimateNote: string;
+    lint: {
+        errors: number;
+        warnings: number;
+        items: string[];
+    };
+    budgetSec: number;
+    elapsedSec: number;
+    checklist: ChecklistItem[];
+}
+export declare const CHECKLIST: readonly Omit<ChecklistItem, "done">[];

package/dist/preview/manifest.js

@@ -0,0 +1,19 @@
+import { dirname, join, resolve } from "node:path";
+import { storyboardStem } from "../approval/hash.js";
+/** Pack directory suffix: the pack of `<stem>.json` is `<out>/<stem>.preview`. */
+export const PREVIEW_SUFFIX = ".preview";
+export const PREVIEW_JSON = "preview.json";
+/** Default pack location base: `<storyboard dir>/out` (the pack is `<out>/preview`). */
+export const defaultOut = (storyboard) => join(dirname(resolve(storyboard)), "out");
+/** `<out>/<stem>.preview`: one pack per storyboard. */
+export const packDir = (out, storyboard) => join(out, `${storyboardStem(storyboard)}${PREVIEW_SUFFIX}`);
+export const previewManifestPath = (out, storyboard) => join(packDir(out, storyboard), PREVIEW_JSON);
+export const CHECKLIST = [
+    { id: "shown-contact", text: "contact.png was shown to the user (or its path given)" },
+    { id: "shown-clip", text: "clip.mp4 path was given to the user (or the skip was explained)" },
+    {
+        id: "not-shown",
+        text: "the user knows what is NOT previewed: voice, motion between stills, and any scene without a still",
+    },
+    { id: "explicit-yes", text: "the user said an explicit yes to this exact preview" },
+];

package/dist/preview/pack.d.ts

@@ -0,0 +1,24 @@
+import type { Host, Io } from "../types.ts";
+import type { StillPick } from "./plan.ts";
+/** A still that was captured (light = the storyboard's own theme; extras use the paired theme). */
+export interface Captured {
+    pick: StillPick;
+    theme: string;
+    /** PNG written by `mk still`. */
+    source: string;
+}
+export interface NamedStill extends Captured {
+    /** `NN-<scene>-<theme>.png`. */
+    name: string;
+}
+export declare const CONTACT_COLS = 3;
+/** Timeline order; within one scene the storyboard's own theme comes first. */
+export declare function nameStills(captured: readonly Captured[], primary: string): NamedStill[];
+/** Deletes every PNG in a directory (stale output of an earlier run); a missing directory is fine. */
+export declare function clearPngs(host: Host, dir: string): Promise<void>;
+/** PNGs in a directory, sorted by name (the order `hyperframes snapshot` numbered them). */
+export declare function listPngs(host: Host, dir: string): Promise<string[]>;
+/** ffconcat list for the stills (forward slashes; a quote in a path is refused, not escaped). */
+export declare function concatList(files: readonly string[]): string;
+/** Tiles the stills into one `contact.png` with ffmpeg at `width` px per tile; resolves to an exit code. */
+export declare function contactSheet(io: Io, files: readonly string[], listFile: string, out: string, width?: number): Promise<number>;

package/dist/preview/pack.js

@@ -0,0 +1,53 @@
+import { join } from "node:path";
+import { contactImagesArgs, TILE_WIDTH } from "../contact/argv.js";
+import { EXIT } from "../exit-codes.js";
+const TWO_DIGITS = 2;
+export const CONTACT_COLS = 3;
+/** Timeline order; within one scene the storyboard's own theme comes first. */
+export function nameStills(captured, primary) {
+    const ordered = [...captured].sort((a, b) => a.pick.t - b.pick.t || Number(b.theme === primary) - Number(a.theme === primary));
+    return ordered.map((still, index) => ({
+        ...still,
+        name: `${String(index + 1).padStart(TWO_DIGITS, "0")}-${still.pick.id}-${still.theme}.png`,
+    }));
+}
+/** Deletes every PNG in a directory (stale output of an earlier run); a missing directory is fine. */
+export async function clearPngs(host, dir) {
+    const names = await host.listDir(dir).catch(() => []);
+    for (const name of names)
+        if (name.endsWith(".png"))
+            await host.remove(join(dir, name));
+}
+/** PNGs in a directory, sorted by name (the order `hyperframes snapshot` numbered them). */
+export async function listPngs(host, dir) {
+    const names = await host.listDir(dir).catch(() => []);
+    return names
+        .filter((name) => name.endsWith(".png"))
+        .sort()
+        .map((name) => join(dir, name));
+}
+/** ffconcat list for the stills (forward slashes; a quote in a path is refused, not escaped). */
+export function concatList(files) {
+    const rows = files.map((file) => {
+        if (file.includes("'") || /[\r\n]/.test(file)) {
+            throw new Error(`cannot tile ${JSON.stringify(file)}: quote or line break in path`);
+        }
+        return `file '${file.replaceAll("\\", "/")}'\nduration 1\n`;
+    });
+    return rows.join("");
+}
+/** Tiles the stills into one `contact.png` with ffmpeg at `width` px per tile; resolves to an exit code. */
+export async function contactSheet(io, files, listFile, out, width = TILE_WIDTH) {
+    await io.host.writeTextAtomic(listFile, concatList(files));
+    const args = contactImagesArgs(listFile, out, files.length, Math.min(CONTACT_COLS, files.length), width);
+    const result = await io.run("ffmpeg", args, { timeoutMs: 120_000 });
+    if (result.code === EXIT.MISSING_TOOL) {
+        io.stderr("mk: ffmpeg not found; install ffmpeg and put it on PATH\n");
+        return EXIT.MISSING_TOOL;
+    }
+    if (result.code !== 0) {
+        io.stderr(`mk preview: ffmpeg failed: ${result.stderr.trim().split(/\r?\n/).pop()}\n`);
+        return EXIT.ERROR;
+    }
+    return EXIT.OK;
+}

package/dist/preview/plan.d.ts

@@ -0,0 +1,58 @@
+import type { Storyboard } from "@anvpx/motion-schema";
+/** A base scene as the pickers see it: timing from the resolved timeline, weight = prop size. */
+export interface SceneInfo {
+    id: string;
+    type: string;
+    weight: number;
+    start: number;
+    duration: number;
+}
+export interface StillPick {
+    id: string;
+    type: string;
+    /** Seconds on the storyboard timeline. */
+    t: number;
+}
+export declare const CLIP_SCENE_SEC = 2;
+export declare const CLIP_MAX_SEC = 30;
+/** A still is taken here inside its scene, after the entrance animation has settled. */
+export declare const SETTLED = 0.7;
+/** Scenes shown in both themes of a pair. */
+export declare const DARK_COUNT = 3;
+/**
+ * Which scenes to show, as ascending indices: first, last, each distinct `type` once (the instance
+ * with the most props), then an even spread. Pure and deterministic.
+ */
+export declare function pickScenes(scenes: readonly SceneInfo[], count: number): number[];
+/** Time of each pick: 70% into its scene. */
+export declare function stillPlan(scenes: readonly SceneInfo[], count: number): StillPick[];
+/** The `limit` most distinct picks (different types first), in timeline order. */
+export declare function distinctPicks(picks: readonly StillPick[], limit: number): StillPick[];
+/** Overlay offset/duration pulled inside a base scene that is now `baseSec` long. */
+export declare function withinScene(offset: number, duration: number, baseSec: number): {
+    offset: number;
+    duration: number;
+};
+export interface ClipPlan {
+    storyboard: Storyboard;
+    totalSec: number;
+    /** Base scenes kept, in order. */
+    sceneIds: string[];
+}
+/** Base scenes with resolved timing, as the pickers see them; undefined when timing fails. */
+export declare function sceneInfos(board: Storyboard): SceneInfo[] | undefined;
+/**
+ * What the default still picker chooses from: the base scenes plus every overlay that is off
+ * screen at the settled time of its base scene (so its id would otherwise never be shown), in
+ * timeline order. `mk preview --every` uses `sceneInfos` instead.
+ */
+export declare function stillCandidates(board: Storyboard): SceneInfo[];
+/**
+ * Preview clip as an in-memory storyboard: every base scene at most `CLIP_SCENE_SEC`, overlays
+ * clamped inside, narration stripped. Over `CLIP_MAX_SEC` in total, scenes are sampled with the
+ * same picker as the stills. Scenes are pure functions of time, so the first seconds show the
+ * entrance animation faithfully.
+ */
+export declare function capClip(board: Storyboard, cap?: number, max?: number): ClipPlan;
+/** Budget fallback: run the clip only if the time left covers its expected cost. */
+export declare function shouldRunClip(elapsedMs: number, stillsMs: number, budgetMs: number): boolean;

package/dist/preview/plan.js

@@ -0,0 +1,160 @@
+import { resolveTimeline } from "@anvpx/motion-build";
+export const CLIP_SCENE_SEC = 2;
+export const CLIP_MAX_SEC = 30;
+/** A still is taken here inside its scene, after the entrance animation has settled. */
+export const SETTLED = 0.7;
+/** Scenes shown in both themes of a pair. */
+export const DARK_COUNT = 3;
+/** The clip is expected to cost about this much of what the stills batch cost. */
+const CLIP_COST_FACTOR = 1.5;
+const MIN_OVERLAY_SEC = 1;
+const round3 = (value) => Math.round(value * 1000) / 1000;
+/** Midpoint of the widest gap between picked indices (ties: the earliest gap). */
+function bisect(picked) {
+    const sorted = [...picked].sort((a, b) => a - b);
+    let best = 0;
+    for (let i = 1; i < sorted.length; i += 1) {
+        if ((sorted[i] ?? 0) - (sorted[i - 1] ?? 0) > (sorted[best + 1] ?? 0) - (sorted[best] ?? 0)) {
+            best = i - 1;
+        }
+    }
+    return Math.floor(((sorted[best] ?? 0) + (sorted[best + 1] ?? 0)) / 2);
+}
+const weightOf = (scenes, index) => scenes[index]?.weight ?? 0;
+/**
+ * Which scenes to show, as ascending indices: first, last, each distinct `type` once (the instance
+ * with the most props), then an even spread. Pure and deterministic.
+ */
+export function pickScenes(scenes, count) {
+    const n = scenes.length;
+    if (n === 0 || count <= 0)
+        return [];
+    if (count >= n)
+        return scenes.map((_, i) => i);
+    const picked = new Set([0]);
+    const add = (index) => {
+        if (picked.size < count)
+            picked.add(index);
+    };
+    add(n - 1);
+    for (const type of new Set(scenes.map((s) => s.type))) {
+        const same = scenes.flatMap((s, i) => (s.type === type ? [i] : []));
+        if (same.some((i) => picked.has(i)))
+            continue;
+        add(same.reduce((a, b) => (weightOf(scenes, b) > weightOf(scenes, a) ? b : a)));
+    }
+    while (picked.size < count)
+        picked.add(bisect(picked));
+    return [...picked].sort((a, b) => a - b);
+}
+/** Time of each pick: 70% into its scene. */
+export function stillPlan(scenes, count) {
+    return pickScenes(scenes, count).flatMap((index) => {
+        const scene = scenes[index];
+        if (scene === undefined)
+            return [];
+        const t = Math.round((scene.start + SETTLED * scene.duration) * 100) / 100;
+        return [{ id: scene.id, type: scene.type, t }];
+    });
+}
+/** The `limit` most distinct picks (different types first), in timeline order. */
+export function distinctPicks(picks, limit) {
+    if (picks.length <= limit)
+        return [...picks];
+    const infos = picks.map((p, i) => ({ id: p.id, type: p.type, weight: 1, start: i, duration: 1 }));
+    return pickScenes(infos, limit).flatMap((i) => (picks[i] ? [picks[i]] : []));
+}
+/** Overlay offset/duration pulled inside a base scene that is now `baseSec` long. */
+export function withinScene(offset, duration, baseSec) {
+    const room = Math.min(MIN_OVERLAY_SEC, baseSec);
+    const start = round3(Math.min(offset, baseSec - room));
+    return { offset: start, duration: round3(Math.min(duration, baseSec - start)) };
+}
+const isOverlay = (scene) => scene.layer === "overlay";
+/** Base scenes with resolved timing, as the pickers see them; undefined when timing fails. */
+export function sceneInfos(board) {
+    const timeline = resolveTimeline(board);
+    if (!timeline.ok)
+        return undefined;
+    const entries = new Map(board.scenes.map((s) => [s.id, s]));
+    return timeline.value.scenes.map((t) => ({
+        id: t.id,
+        type: entries.get(t.id)?.type ?? "",
+        weight: JSON.stringify(entries.get(t.id)?.props ?? {}).length,
+        start: t.start,
+        duration: t.duration,
+    }));
+}
+/**
+ * What the default still picker chooses from: the base scenes plus every overlay that is off
+ * screen at the settled time of its base scene (so its id would otherwise never be shown), in
+ * timeline order. `mk preview --every` uses `sceneInfos` instead.
+ */
+export function stillCandidates(board) {
+    const bases = sceneInfos(board);
+    const timeline = resolveTimeline(board);
+    if (bases === undefined || !timeline.ok)
+        return [];
+    const entries = new Map(board.scenes.map((s) => [s.id, s]));
+    const baseById = new Map(bases.map((b) => [b.id, b]));
+    const missed = timeline.value.overlays.flatMap((o) => {
+        const host = baseById.get(o.over);
+        const settled = host === undefined ? undefined : host.start + SETTLED * host.duration;
+        if (settled !== undefined && settled >= o.start && settled < o.end)
+            return [];
+        const entry = entries.get(o.id);
+        return [
+            {
+                id: o.id,
+                type: entry?.type ?? "",
+                weight: JSON.stringify(entry?.props ?? {}).length,
+                start: o.start,
+                duration: o.duration,
+            },
+        ];
+    });
+    return [...bases, ...missed].sort((a, b) => a.start - b.start);
+}
+const capped = (scene, durations, cap) => Math.min(durations.get(scene.id) ?? cap, cap);
+const trimOverlay = (scene, keep, durations, cap) => {
+    const over = scene.over ?? "";
+    if (!keep.has(over))
+        return [];
+    const baseSec = Math.min(durations.get(over) ?? cap, cap);
+    const fit = withinScene(scene.offset ?? 0, scene.duration ?? baseSec, baseSec);
+    return [{ ...scene, ...fit }];
+};
+const trimmed = (board, keep, durations, cap) => board.scenes.flatMap((entry) => {
+    const { narration: _narration, ...scene } = entry;
+    if (isOverlay(scene))
+        return trimOverlay(scene, keep, durations, cap);
+    return keep.has(scene.id)
+        ? [{ ...scene, duration: round3(capped(scene, durations, cap)) }]
+        : [];
+});
+/**
+ * Preview clip as an in-memory storyboard: every base scene at most `CLIP_SCENE_SEC`, overlays
+ * clamped inside, narration stripped. Over `CLIP_MAX_SEC` in total, scenes are sampled with the
+ * same picker as the stills. Scenes are pure functions of time, so the first seconds show the
+ * entrance animation faithfully.
+ */
+export function capClip(board, cap = CLIP_SCENE_SEC, max = CLIP_MAX_SEC) {
+    const infos = sceneInfos(board);
+    if (infos === undefined)
+        return { storyboard: board, totalSec: 0, sceneIds: [] };
+    const durations = new Map(infos.map((info) => [info.id, info.duration]));
+    for (let count = infos.length; count >= 1; count -= 1) {
+        const keep = new Set(pickScenes(infos, count).map((i) => infos[i]?.id ?? ""));
+        const candidate = { ...board, scenes: trimmed(board, keep, durations, cap) };
+        const timeline = resolveTimeline(candidate);
+        if (timeline.ok && (timeline.value.total <= max || count === 1)) {
+            const sceneIds = timeline.value.scenes.map((s) => s.id);
+            return { storyboard: candidate, totalSec: timeline.value.total, sceneIds };
+        }
+    }
+    return { storyboard: board, totalSec: 0, sceneIds: [] };
+}
+/** Budget fallback: run the clip only if the time left covers its expected cost. */
+export function shouldRunClip(elapsedMs, stillsMs, budgetMs) {
+    return elapsedMs + stillsMs * CLIP_COST_FACTOR <= budgetMs;
+}

package/dist/preview/provenance.d.ts

@@ -0,0 +1,23 @@
+import { type TemplateEnv } from "../template/env.ts";
+import type { Host, Io } from "../types.ts";
+/** What `mk new` recorded in `.mk/<stem>/template.json`. */
+export interface TemplateProvenance {
+    /** `id@version`. */
+    template: string;
+    blueprint: string;
+    style: string;
+    length: string;
+}
+export declare const provenancePath: (storyboard: string) => string;
+/** The recorded provenance, or undefined for a storyboard that did not come from `mk new`. */
+export declare function readProvenance(host: Host, storyboard: string): Promise<TemplateProvenance | undefined>;
+export interface Pair {
+    id: string;
+    /** Theme file text, ready to vendor into a scratch project. */
+    text: string;
+}
+/**
+ * The paired theme (light <-> dark) of `theme`, from the template that made the storyboard.
+ * Undefined when the template is not installed, has no pair, or the storyboard is hand-written.
+ */
+export declare function resolvePair(env: TemplateEnv, io: Io, provenance: TemplateProvenance | undefined, theme: string): Pair | undefined;

package/dist/preview/provenance.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { mkDir, readSidecar } from "../approval/hash.js";
+import { findTemplate } from "../template/env.js";
+import { TEMPLATE_PROVENANCE } from "../template/new.js";
+export const provenancePath = (storyboard) => join(mkDir(storyboard), TEMPLATE_PROVENANCE);
+const isProvenance = (value) => {
+    const row = value;
+    return (typeof row === "object" &&
+        row !== null &&
+        typeof row.template === "string" &&
+        typeof row.blueprint === "string" &&
+        typeof row.style === "string" &&
+        typeof row.length === "string");
+};
+/** The recorded provenance, or undefined for a storyboard that did not come from `mk new`. */
+export async function readProvenance(host, storyboard) {
+    try {
+        const parsed = JSON.parse(await readSidecar(host, storyboard, TEMPLATE_PROVENANCE));
+        return isProvenance(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The paired theme (light <-> dark) of `theme`, from the template that made the storyboard.
+ * Undefined when the template is not installed, has no pair, or the storyboard is hand-written.
+ */
+export function resolvePair(env, io, provenance, theme) {
+    if (provenance === undefined)
+        return undefined;
+    const found = findTemplate(env, io, provenance.template.split("@")[0] ?? "");
+    if (!found.ok)
+        return undefined;
+    const pair = found.template.themes.get(theme)?.pair;
+    const file = pair === undefined ? undefined : found.template.themes.get(pair);
+    return file === undefined ? undefined : { id: file.id, text: file.text };
+}

package/dist/publish/command.d.ts

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

package/dist/publish/command.js

@@ -0,0 +1,70 @@
+import { join } from "node:path";
+import { EXIT } from "../exit-codes.js";
+import { parseBuildArgs, prepareProject } from "../workflow/project.js";
+import { COMPOSITION_FILE, PLAYER_FILE, PLAYER_JS, renderCompositionHtml, renderWrapperHtml, WRAPPER_FILE, } from "./player.js";
+import { serveStatic } from "./static.js";
+const USAGE = `mk publish <storyboard.json> [--out <dir>] [--port <n>] [--serve]
+
+Build the storyboard and write a static site that plays it in a browser at 16:9.
+  --out <dir>    project directory (default: <storyboard dir>/out/publish)
+  --port <n>     port for --serve (default: 4321; 0 picks a free one)
+  --serve        serve the directory until interrupted, and print the URL
+
+The site is three files over the built project: composition.html (the build, plus a player),
+player.js (a requestAnimationFrame loop that dispatches the renderer's seek event), and an
+index.html wrapper that scales the fixed 1920x1080 composition to the window. Nothing is
+re-laid-out and nothing is fetched: it plays the same timeline that renders to video.
+`;
+const DEFAULT_PORT = 4321;
+/** The composition's own `<title>`, so the published tab matches the build. */
+const titleOf = (html) => /<title>([^<]*)<\/title>/.exec(html)?.[1] ?? "composition";
+export const publishCommand = {
+    name: "publish",
+    summary: "build a static 16:9 site that plays the storyboard in a browser",
+    async run(args, io) {
+        const parsed = parseBuildArgs("publish", USAGE, args, { port: { type: "string" }, serve: { type: "boolean" } }, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const prepared = await prepareProject(parsed.request, io);
+        if (!prepared.ok)
+            return prepared.code;
+        const index = join(prepared.outDir, WRAPPER_FILE);
+        const original = await io.host.readText(index).catch(() => undefined);
+        if (original === undefined) {
+            io.stderr(`mk: publish: ${index} is missing; the build did not produce an index.html\n`);
+            return EXIT.ERROR;
+        }
+        try {
+            await io.host.writeTextAtomic(join(prepared.outDir, COMPOSITION_FILE), renderCompositionHtml(original));
+            await io.host.writeTextAtomic(join(prepared.outDir, PLAYER_FILE), PLAYER_JS);
+            await io.host.writeTextAtomic(index, renderWrapperHtml({
+                title: titleOf(original),
+                width: prepared.meta.width,
+                height: prepared.meta.height,
+            }));
+        }
+        catch (error) {
+            io.stderr(`mk: publish failed: ${error.message}\n`);
+            return EXIT.ERROR;
+        }
+        const portText = parsed.flags.port;
+        const port = typeof portText === "string" ? Number(portText) : DEFAULT_PORT;
+        if (typeof portText === "string" && (!Number.isInteger(port) || port < 0 || port > 65535)) {
+            io.stderr(`mk publish: --port "${portText}" is not a port number\n`);
+            return EXIT.USAGE;
+        }
+        io.stdout(`published ${prepared.outDir}\n`);
+        if (parsed.flags.serve !== true) {
+            io.stdout(`serve it with any static file server; ES modules do not load from file://\n`);
+            return EXIT.OK;
+        }
+        const served = await serveStatic(prepared.outDir, port);
+        io.stdout(`serving ${served.url} (Ctrl-C to stop)\n`);
+        await new Promise((done) => {
+            process.once("SIGINT", () => done());
+            process.once("SIGTERM", () => done());
+        });
+        await served.close();
+        return EXIT.OK;
+    },
+};

package/dist/publish/player.d.ts

@@ -0,0 +1,25 @@
+/** Files `mk publish` adds beside a built project. */
+export declare const PLAYER_FILE = "player.js";
+export declare const COMPOSITION_FILE = "composition.html";
+export declare const WRAPPER_FILE = "index.html";
+/**
+ * The playback loop. The built project only animates when something dispatches the renderer's
+ * `hf-seek` event, so the player stands in for HyperFrames: it dispatches the same event on a
+ * requestAnimationFrame loop, looping the timeline forever. Nothing else in the page changes.
+ */
+export declare const PLAYER_JS = "// motion-kit player: loops the composition by dispatching the renderer's own seek event.\nconst root = document.getElementById(\"root\");\nconst total = Number(root?.dataset.duration ?? 0) || 1;\nlet startedAt = null;\nlet paused = false;\nlet pausedAt = 0;\n\nconst seek = (time) => {\n  window.dispatchEvent(\n    new CustomEvent(\"hf-seek\", { detail: { time, waitUntil: () => undefined } }),\n  );\n};\n\nconst tick = (now) => {\n  if (startedAt === null) startedAt = now;\n  if (!paused) seek((((now - startedAt) / 1000) % total));\n  requestAnimationFrame(tick);\n};\n\n// Click or Space toggles playback; the timeline keeps looping either way.\nwindow.addEventListener(\"click\", () => {\n  paused = !paused;\n  if (!paused) startedAt = performance.now() - pausedAt * 1000;\n  else pausedAt = ((performance.now() - startedAt) / 1000) % total;\n});\nwindow.addEventListener(\"keydown\", (event) => {\n  if (event.code === \"Space\") {\n    event.preventDefault();\n    window.dispatchEvent(new Event(\"click\"));\n  }\n});\n\nrequestAnimationFrame(tick);\n";
+/**
+ * The composition with the player appended. Every other byte is the build's, so `composition.html`
+ * and the project `mk build` produced stay comparable.
+ */
+export declare const renderCompositionHtml: (indexHtml: string) => string;
+export interface WrapperInput {
+    readonly title: string;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * A 16:9 stage that scales the fixed-size composition to the window. This is the whole of the
+ * "web page" claim: same timeline, same pixels, fitted to the viewport, no responsive re-layout.
+ */
+export declare const renderWrapperHtml: (input: WrapperInput) => string;