@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/publish/player.js

@@ -0,0 +1,108 @@
+/** Files `mk publish` adds beside a built project. */
+export const PLAYER_FILE = "player.js";
+export const COMPOSITION_FILE = "composition.html";
+export 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 const PLAYER_JS = `// motion-kit player: loops the composition by dispatching the renderer's own seek event.
+const root = document.getElementById("root");
+const total = Number(root?.dataset.duration ?? 0) || 1;
+let startedAt = null;
+let paused = false;
+let pausedAt = 0;
+
+const seek = (time) => {
+  window.dispatchEvent(
+    new CustomEvent("hf-seek", { detail: { time, waitUntil: () => undefined } }),
+  );
+};
+
+const tick = (now) => {
+  if (startedAt === null) startedAt = now;
+  if (!paused) seek((((now - startedAt) / 1000) % total));
+  requestAnimationFrame(tick);
+};
+
+// Click or Space toggles playback; the timeline keeps looping either way.
+window.addEventListener("click", () => {
+  paused = !paused;
+  if (!paused) startedAt = performance.now() - pausedAt * 1000;
+  else pausedAt = ((performance.now() - startedAt) / 1000) % total;
+});
+window.addEventListener("keydown", (event) => {
+  if (event.code === "Space") {
+    event.preventDefault();
+    window.dispatchEvent(new Event("click"));
+  }
+});
+
+requestAnimationFrame(tick);
+`;
+const escapeHtml = (text) => text.replace(/[&<>"]/g, (char) => `&#${char.charCodeAt(0)};`);
+/**
+ * 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 const renderCompositionHtml = (indexHtml) => {
+    const at = indexHtml.lastIndexOf("</body>");
+    if (at < 0)
+        throw new Error("built index.html has no </body>; is this a HyperFrames project?");
+    const lineStart = indexHtml.lastIndexOf("\n", at) + 1;
+    const tag = `    <script type="module" src="${PLAYER_FILE}"></script>\n`;
+    return `${indexHtml.slice(0, lineStart)}${tag}${indexHtml.slice(lineStart)}`;
+};
+/**
+ * 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 const renderWrapperHtml = (input) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(input.title)}</title>
+    <style>
+      html, body { margin: 0; height: 100%; background: #05070c; }
+      body { display: grid; place-items: center; }
+      .mk-stage {
+        position: relative;
+        width: min(100vw, calc(100vh * ${input.width} / ${input.height}));
+        aspect-ratio: ${input.width} / ${input.height};
+        overflow: hidden;
+        box-shadow: 0 40px 120px -60px #000;
+      }
+      .mk-stage iframe {
+        position: absolute;
+        inset: 0;
+        width: ${input.width}px;
+        height: ${input.height}px;
+        border: 0;
+        transform-origin: 0 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="mk-stage">
+      <iframe
+        id="mk-composition"
+        src="${COMPOSITION_FILE}"
+        title="${escapeHtml(input.title)}"
+        scrolling="no"
+      ></iframe>
+    </div>
+    <script>
+      const stage = document.querySelector(".mk-stage");
+      const frame = document.getElementById("mk-composition");
+      const fit = () => {
+        const width = stage.getBoundingClientRect().width;
+        frame.style.transform = "scale(" + width / ${input.width} + ")";
+      };
+      new ResizeObserver(fit).observe(stage);
+      fit();
+    </script>
+  </body>
+</html>
+`;

package/dist/publish/static.d.ts

@@ -0,0 +1,16 @@
+/** Content type by extension; unknown types are served as bytes rather than guessed. */
+export declare const contentTypeOf: (path: string) => string;
+/**
+ * Absolute path a request maps to inside `root`, or null when it escapes the root or is not a
+ * plain file path. Traversal is rejected after decoding, so `%2e%2e` cannot climb out either.
+ */
+export declare const resolveRequestPath: (root: string, url: string) => string | null;
+export interface Served {
+    readonly url: string;
+    close(): Promise<void>;
+}
+/**
+ * Serves `root` on `port` (0 picks a free one) until closed. Publishing needs a real origin:
+ * ES modules and import maps do not load from `file://`.
+ */
+export declare const serveStatic: (root: string, port: number) => Promise<Served>;

package/dist/publish/static.js

@@ -0,0 +1,78 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, join, resolve, sep } from "node:path";
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".woff2": "font/woff2",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+    ".mp4": "video/mp4",
+    ".wav": "audio/wav",
+    ".cube": "text/plain; charset=utf-8",
+};
+/** Content type by extension; unknown types are served as bytes rather than guessed. */
+export const contentTypeOf = (path) => TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+/**
+ * Absolute path a request maps to inside `root`, or null when it escapes the root or is not a
+ * plain file path. Traversal is rejected after decoding, so `%2e%2e` cannot climb out either.
+ */
+export const resolveRequestPath = (root, url) => {
+    const raw = url.split("?")[0]?.split("#")[0] ?? "/";
+    let path;
+    try {
+        path = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    if (path.includes("\0"))
+        return null;
+    const relative = path === "/" ? "/index.html" : path;
+    const base = resolve(root);
+    const target = resolve(join(base, relative));
+    return target === base || target.startsWith(base + sep) ? target : null;
+};
+/**
+ * Serves `root` on `port` (0 picks a free one) until closed. Publishing needs a real origin:
+ * ES modules and import maps do not load from `file://`.
+ */
+export const serveStatic = async (root, port) => {
+    const base = resolve(root);
+    const server = createServer((request, response) => {
+        const target = resolveRequestPath(base, request.url ?? "/");
+        if (target === null) {
+            response.writeHead(403).end("forbidden");
+            return;
+        }
+        stat(target).then((info) => {
+            if (!info.isFile()) {
+                response.writeHead(404).end("not found");
+                return;
+            }
+            response.writeHead(200, {
+                "content-type": contentTypeOf(target),
+                "content-length": String(info.size),
+                // The composition is served from the same origin as the wrapper it is framed in.
+                "cache-control": "no-store",
+            });
+            createReadStream(target).pipe(response);
+        }, () => {
+            response.writeHead(404).end("not found");
+        });
+    });
+    await new Promise((done) => server.listen(port, "127.0.0.1", done));
+    const address = server.address();
+    const actual = typeof address === "object" && address !== null ? address.port : port;
+    return {
+        url: `http://127.0.0.1:${actual}/`,
+        close: () => new Promise((done) => {
+            server.close(() => done());
+        }),
+    };
+};

package/dist/qc.d.ts

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

package/dist/qc.js

@@ -0,0 +1,192 @@
+import { detectSilence, wordsInSilence } from "@anvpx/motion-audio";
+import { TimingManifestSchema } from "@anvpx/motion-schema";
+import { parseFlags, requirePositional, textFlag, usageError } from "./args.js";
+import { EXIT } from "./exit-codes.js";
+import { readJsonFile } from "./storyboard/load.js";
+import { probeMedia } from "./verify/probe.js";
+import { exitCodeForStatus, formatReport, formatReportJson } from "./verify/report.js";
+const USAGE = `mk qc <manifest.json> [--audio <audio.wav>] [--words <words.json>] [--json]
+
+Gate a voice TimingManifest plus its audio; QC measures, it never decides for you.
+  <manifest.json>  voice TimingManifest to gate (required)
+  --audio <file>   audio covering the manifest timeline; absent audio is UNKNOWN, never FAIL
+  --words <file>   known word timings JSON [{w,start,end}]; overrides manifest words
+  --json           one compact JSON line {status, file, findings}
+Checks: manifest schema; words fully inside silence are fatal; audio duration
+must match the manifest total within 0.5 s. Without --audio the audio gate
+could not be decided: UNKNOWN.
+Exit 0 PASS or WARN; 5 FAIL; 2 UNKNOWN (could not decide) or bad arguments; 127 ffprobe missing.
+`;
+const FLAGS = {
+    audio: { type: "string" },
+    words: { type: "string" },
+    json: { type: "boolean" },
+};
+/** Audio duration within 0.5 s of the manifest total (measured, never inferred). */
+const DURATION_TOLERANCE_S = 0.5;
+const FFMPEG_HINT = "mk: ffprobe not found; install ffmpeg and put it on PATH";
+const isExit = (value) => typeof value === "object" && value !== null && value.kind === "exit";
+const isWordList = (value) => Array.isArray(value) &&
+    value.every((entry) => typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.w === "string" &&
+        Number.isFinite(entry.start) &&
+        Number.isFinite(entry.end));
+/** Manifest words: explicit --words wins, then manifest audio, then scene words. */
+async function resolveWords(io, manifest, wordsPath) {
+    if (wordsPath === undefined) {
+        return manifest.audio?.words ?? manifest.scenes.flatMap((scene) => scene.words ?? []);
+    }
+    const loaded = await readJsonFile(wordsPath, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk qc: ${loaded.message}\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    if (!isWordList(loaded.value)) {
+        return usageError("qc", USAGE, "words file must be a JSON array of {w,start,end}", io);
+    }
+    return loaded.value;
+}
+/** Read the manifest; an invalid manifest fails the gate, an unreadable one is usage. */
+async function loadManifest(io, path) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk qc: ${loaded.message}\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const manifest = TimingManifestSchema.safeParse(loaded.value);
+    if (manifest.success)
+        return manifest.data;
+    return {
+        problems: manifest.error.issues
+            .map((issue) => `${issue.path.join("/")}: ${issue.message}`)
+            .join("; "),
+    };
+}
+/** An UNKNOWN gate report: measured nothing, decided nothing. */
+const unknownReport = (code, message) => ({
+    status: "UNKNOWN",
+    findings: [{ code, level: "warn", message }],
+});
+/** Silence intervals plus measured duration; unknown stays UNKNOWN, missing tools exit. */
+async function measureAudio(io, audio) {
+    const silence = await detectSilence(io.run, { audioPath: audio });
+    if (!silence.ok && silence.status === "missing") {
+        io.stderr(`${FFMPEG_HINT}\n`);
+        return { kind: "exit", code: EXIT.MISSING_TOOL };
+    }
+    if (!silence.ok) {
+        return unknownReport("audio-unreadable", `silence gate failed: ${silence.hint}`);
+    }
+    const probed = await probeMedia(io, audio);
+    if (!probed.ok && probed.kind === "missing-tool") {
+        io.stderr(`${FFMPEG_HINT}\n`);
+        return { kind: "exit", code: EXIT.MISSING_TOOL };
+    }
+    if (!probed.ok) {
+        return unknownReport("audio-unreadable", `could not read audio: ${probed.reason}`);
+    }
+    const format = probed.probe.format;
+    const raw = Number(format?.duration);
+    const audioDuration = Number.isFinite(raw) && raw > 0 ? raw : undefined;
+    return { intervals: silence.intervals, audioDuration };
+}
+/** Silence gate plus duration cross-check; never throws. */
+async function gateAudio(io, manifest, audio, wordsPath) {
+    if (!(await io.host.exists(audio))) {
+        io.stderr(`mk qc: cannot read ${audio}; check the path.\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const words = await resolveWords(io, manifest, wordsPath);
+    if (isExit(words))
+        return words;
+    const measured = await measureAudio(io, audio);
+    if (isExit(measured) || "status" in measured)
+        return measured;
+    const findings = audioFindings(words ?? [], measured.intervals, manifest, measured.audioDuration);
+    return { status: statusOf(findings, (words ?? []).length > 0), findings };
+}
+const statusOf = (findings, decidable) => {
+    if (findings.some((f) => f.level === "fatal"))
+        return "FAIL";
+    if (!decidable)
+        return "UNKNOWN";
+    return findings.some((f) => f.level === "warn") ? "WARN" : "PASS";
+};
+const silenceFinding = (inside) => {
+    const shown = inside
+        .slice(0, 3)
+        .map((word) => `"${word.w}" at ${word.start.toFixed(2)}s`)
+        .join(", ");
+    return {
+        code: "words-in-silence",
+        level: "fatal",
+        message: `${inside.length} word(s) inside silence (${shown}); refusing fake timing`,
+    };
+};
+const audioFindings = (words, intervals, manifest, audioDuration) => {
+    const findings = [];
+    if (words.length === 0) {
+        findings.push({
+            code: "audio-words-missing",
+            level: "warn",
+            message: "no word timings (manifest audio, scene words or --words); gate undecided (unaligned narration, e.g. Japanese j-voice, stays UNKNOWN, never FAIL)",
+        });
+    }
+    else {
+        const swallowed = wordsInSilence(words, intervals);
+        if (swallowed.length > 0)
+            findings.push(silenceFinding(swallowed));
+    }
+    const total = manifest.scenes.reduce((sum, scene) => sum + scene.duration, 0);
+    if (audioDuration !== undefined && Math.abs(audioDuration - total) > DURATION_TOLERANCE_S) {
+        findings.push({
+            code: "audio-duration-mismatch",
+            level: "fatal",
+            message: `Audio is ${audioDuration.toFixed(2)}s, manifest total is ${total.toFixed(2)}s.`,
+        });
+    }
+    return findings;
+};
+const audioAbsent = () => ({
+    status: "UNKNOWN",
+    findings: [
+        {
+            code: "audio-not-provided",
+            level: "warn",
+            message: "no --audio; the audio gate could not be decided (audio is opt-in)",
+        },
+    ],
+});
+export const qcCommand = {
+    name: "qc",
+    summary: "gate a voice manifest plus its audio: PASS, WARN, FAIL or UNKNOWN",
+    async run(args, io) {
+        const parsed = parseFlags("qc", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const manifestPath = requirePositional("qc", USAGE, parsed.positionals, "<manifest.json>", io);
+        if (typeof manifestPath !== "string")
+            return manifestPath.code;
+        const manifest = await loadManifest(io, manifestPath);
+        if (isExit(manifest))
+            return manifest.code;
+        if ("problems" in manifest) {
+            const invalid = {
+                status: "FAIL",
+                findings: [{ code: "manifest-invalid", level: "fatal", message: manifest.problems }],
+            };
+            io.stdout(reportOf(parsed.flags.json === true, manifestPath, invalid));
+            return exitCodeForStatus(invalid.status);
+        }
+        const audio = textFlag(parsed.flags, "audio");
+        const gated = audio === undefined
+            ? audioAbsent()
+            : await gateAudio(io, manifest, audio, textFlag(parsed.flags, "words"));
+        if (isExit(gated))
+            return gated.code;
+        io.stdout(reportOf(parsed.flags.json === true, manifestPath, gated));
+        return exitCodeForStatus(gated.status);
+    },
+};
+const reportOf = (json, file, report) => json ? formatReportJson(file, report) : formatReport(file, report);

package/dist/scene/author.d.ts

@@ -0,0 +1,16 @@
+import type { Io } from "../types.ts";
+declare const USAGE = "mk scene new <id> [--dir <path>] [--force]\nmk scene lint <dir>\n\nAuthor a scene (type \"custom\"): three files beside the storyboard, rendered like a catalog scene.\n  new   scaffold scene.js, fragment.html, style.css and notes.md (refuses to overwrite without --force)\n        --dir path   where to write it (default scenes/<id>)\n  lint  determinism and safety check: clocks, timers, network, workers, window, CSS animation/transition\n  promote  copy an authored scene into the catalog package (maintainer workflow) and print the registry lines\n           --as type   catalog type name (required)\nExit 0 when clean; 2 on lint errors or bad usage.\n";
+declare function runNew(args: readonly string[], io: Io): Promise<number>;
+declare function runLint(args: readonly string[], io: Io): Promise<number>;
+/**
+ * Files for a promoted catalog scene. A promoted scene is static: it keeps its markup
+ * and code verbatim, so the plugin only needs an empty strict schema and a body.
+ * Adding props is a human design step, deliberately not guessed here.
+ */
+export declare const promoteFiles: (type: string, source: {
+    js: string;
+    html: string;
+    css?: string;
+}) => readonly (readonly [string, string])[];
+declare function runPromote(args: readonly string[], io: Io): Promise<number>;
+export { runLint as sceneLint, runNew as sceneNew, runPromote as scenePromote, USAGE as SCENE_AUTHOR_USAGE, };

package/dist/scene/author.js

@@ -0,0 +1,260 @@
+import { dirname, join, resolve } from "node:path";
+import { lintCustomSource, readRelativeClosure } from "@anvpx/motion-build";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { sceneContainment } from "../storyboard/containment.js";
+import { formatFindings, summaryLine } from "../storyboard/report.js";
+const USAGE = `mk scene new <id> [--dir <path>] [--force]
+mk scene lint <dir>
+
+Author a scene (type "custom"): three files beside the storyboard, rendered like a catalog scene.
+  new   scaffold scene.js, fragment.html, style.css and notes.md (refuses to overwrite without --force)
+        --dir path   where to write it (default scenes/<id>)
+  lint  determinism and safety check: clocks, timers, network, workers, window, CSS animation/transition
+  promote  copy an authored scene into the catalog package (maintainer workflow) and print the registry lines
+           --as type   catalog type name (required)
+Exit 0 when clean; 2 on lint errors or bad usage.
+`;
+const NEW_FLAGS = {
+    dir: { type: "string" },
+    force: { type: "boolean" },
+};
+const SCENE_JS = `// @ts-check
+import { mountTimeline } from "../../runtime/mount.js";
+
+/**
+ * Authored scene: seek(t) must be a pure function of t.
+ * No clocks, no timers, no unseeded random, no network, no window globals.
+ * Guide: the authoring-scene reference in the installed motion-kit skill
+ * @type {import("../../runtime/mount.js").CreateScene}
+ */
+export function createScene(root, config, ctx) {
+  return mountTimeline(root, config, ctx, { baseDelay: 0.3, staggerFrames: 6, rise: 48 });
+}
+`;
+const FRAGMENT_HTML = `<div class="authored-stack">
+  <p class="authored-kicker" data-anim="rise" data-step="0" data-focus-key="kicker">Kicker</p>
+  <h1 class="authored-title" data-anim="rise" data-step="1" data-focus-key="title">Your scene</h1>
+</div>
+`;
+const STYLE_CSS = `#scene-root .authored-stack { display: flex; flex-direction: column; gap: 24px; }
+#scene-root .authored-kicker {
+  font-size: 22px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--mk-color-accent);
+}
+#scene-root .authored-title {
+  font-size: 96px;
+  line-height: 1.05;
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+`;
+const notes = (id) => `# ${id}
+
+Why this scene exists: <one line>.
+
+Promote it to the catalog (\`mk scene promote\`) once two projects use it.
+`;
+const FILES = (id) => [
+    ["scene.js", SCENE_JS],
+    ["fragment.html", FRAGMENT_HTML],
+    ["style.css", STYLE_CSS],
+    ["notes.md", notes(id)],
+];
+async function runNew(args, io) {
+    const parsed = parseFlags("scene", USAGE, args, NEW_FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [id, ...extra] = parsed.positionals;
+    if (id === undefined)
+        return usageError("scene", USAGE, "missing <id>", io).code;
+    if (extra.length > 0)
+        return usageError("scene", USAGE, `unexpected "${extra[0]}"`, io).code;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+        return usageError("scene", USAGE, "<id> must be a lowercase slug", io).code;
+    }
+    const requested = textFlag(parsed.flags, "dir") ?? join("scenes", id);
+    const dir = resolve(requested);
+    const force = parsed.flags.force === true;
+    const targets = FILES(id).map(([name]) => join(dir, name));
+    if (!force) {
+        const taken = await Promise.all(targets.map((path) => io.host.exists(path)));
+        if (taken.some(Boolean)) {
+            return usageError("scene", USAGE, `${dir} already has files; pass --force to overwrite`, io)
+                .code;
+        }
+    }
+    for (const [name, text] of FILES(id))
+        await io.host.writeText(join(dir, name), text);
+    io.stdout(`wrote ${requested} (${FILES(id).length} files)\n`);
+    io.stdout(`next: add { "type": "custom", "props": { "dir": "${requested.replaceAll("\\", "/")}" } } and run mk validate\n`);
+    return EXIT.OK;
+}
+async function runLint(args, io) {
+    const parsed = parseFlags("scene", USAGE, args, {}, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [dir, ...extra] = parsed.positionals;
+    if (dir === undefined)
+        return usageError("scene", USAGE, "missing <dir>", io).code;
+    if (extra.length > 0)
+        return usageError("scene", USAGE, `unexpected "${extra[0]}"`, io).code;
+    const base = resolve(dir);
+    const required = ["scene.js", "fragment.html"];
+    const missing = [];
+    for (const file of required) {
+        if (!(await io.host.exists(join(base, file))))
+            missing.push(file);
+    }
+    if (missing.length > 0) {
+        io.stderr(`mk scene lint: missing ${missing.join(", ")} in ${dir}\n`);
+        return EXIT.USAGE;
+    }
+    const js = await io.host.readText(join(base, "scene.js"));
+    const html = await io.host.readText(join(base, "fragment.html"));
+    const cssPath = join(base, "style.css");
+    const css = (await io.host.exists(cssPath)) ? await io.host.readText(cssPath) : undefined;
+    const findings = lintCustomSource({ js, html, ...(css === undefined ? {} : { css }) }, dir);
+    // A linked directory or file can point outside while still looking local.
+    const containment = sceneContainment(dirname(base), base, [...required, "style.css"]);
+    if (!containment.dirInside) {
+        findings.push({
+            severity: "error",
+            path: base,
+            message: "scene directory resolves outside its parent (symlink/junction)",
+            suggestion: "replace the link with a real directory",
+        });
+    }
+    for (const file of containment.escapedFiles) {
+        findings.push({
+            severity: "error",
+            path: `${dir}/${file}`,
+            message: "scene file resolves outside the scene directory (symlink/junction)",
+            suggestion: "replace the link with a real file",
+        });
+    }
+    const closure = await readRelativeClosure(js, async (path) => {
+        const check = sceneContainment(dirname(base), base, [path]);
+        if (!check.dirInside || check.escapedFiles.length > 0)
+            return undefined;
+        const full = join(base, path);
+        return (await io.host.exists(full)) ? io.host.readText(full) : undefined;
+    });
+    for (const specifier of closure.escaping) {
+        findings.push({
+            severity: "error",
+            path: "scene.js",
+            message: `relative import "${specifier}" escapes the scene directory`,
+            suggestion: "keep helpers inside the scene directory (./lib/format.js)",
+        });
+    }
+    for (const path of closure.missing) {
+        findings.push({
+            severity: "error",
+            path: "scene.js",
+            message: `cannot import "./${path}": no such file beside the scene`,
+            suggestion: "add the file, or inline the code",
+        });
+    }
+    if (closure.overflow) {
+        findings.push({
+            severity: "error",
+            path: "scene.js",
+            message: "scene helper closure is too large",
+            suggestion: "keep the scene to a few small helpers",
+        });
+    }
+    for (const helper of closure.files) {
+        findings.push(...lintCustomSource({ js: helper.text }, dir).map((finding) => ({
+            ...finding,
+            path: finding.path.replace(/scene\.js:/, `${helper.path}:`),
+        })));
+    }
+    io.stdout(formatFindings(findings));
+    io.stdout(summaryLine(findings.length, 0));
+    return findings.length === 0 ? EXIT.OK : EXIT.USAGE;
+}
+/** camelCase export name for a promoted scene type. */
+const exportName = (type) => `${type.replace(/[^a-zA-Z0-9]+(.)/g, (_, char) => char.toUpperCase())}Scene`;
+/**
+ * Files for a promoted catalog scene. A promoted scene is static: it keeps its markup
+ * and code verbatim, so the plugin only needs an empty strict schema and a body.
+ * Adding props is a human design step, deliberately not guessed here.
+ */
+export const promoteFiles = (type, source) => {
+    const index = `import { z } from "zod";
+import { defineScene } from "../../define-scene.ts";
+import { readText } from "../../text-file.ts";
+
+const FRAGMENT = readText("./fragment.html", import.meta.url);
+
+/** Promoted from an authored scene. Give it props before it ships: configSchema is empty. */
+export const ${exportName(type)} = defineScene({
+  type: "${type}",
+  configSchema: z.strictObject({}),
+  meta: { purpose: "TODO: one line for the catalog.", example: {} },
+  style: readText("./style.css", import.meta.url),
+  script: readText("./scene.js", import.meta.url),
+  render: () => ({ body: FRAGMENT }),
+});
+`;
+    const files = [
+        ["index.ts", index],
+        ["scene.js", source.js],
+        ["fragment.html", source.html],
+    ];
+    return source.css === undefined ? files : [...files, ["style.css", source.css]];
+};
+const CATALOG_DIR = join("packages", "scenes", "src", "scenes");
+async function runPromote(args, io) {
+    const parsed = parseFlags("scene", USAGE, args, PROMOTE_FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [dir, ...extra] = parsed.positionals;
+    if (dir === undefined)
+        return usageError("scene", USAGE, "missing <dir>", io).code;
+    if (extra.length > 0)
+        return usageError("scene", USAGE, `unexpected "${extra[0]}"`, io).code;
+    const type = textFlag(parsed.flags, "as");
+    if (type === undefined)
+        return usageError("scene", USAGE, "missing --as <type>", io).code;
+    if (!/^[a-z][a-z0-9-]*$/.test(type)) {
+        return usageError("scene", USAGE, "--as must be a lowercase slug", io).code;
+    }
+    const source = resolve(dir);
+    const required = ["scene.js", "fragment.html"];
+    const missing = [];
+    for (const file of required) {
+        if (!(await io.host.exists(join(source, file))))
+            missing.push(file);
+    }
+    if (missing.length > 0) {
+        io.stderr(`mk scene promote: missing ${missing.join(", ")} in ${dir}\n`);
+        return EXIT.USAGE;
+    }
+    const target = resolve(CATALOG_DIR, type);
+    if (await io.host.exists(target)) {
+        return usageError("scene", USAGE, `${CATALOG_DIR}/${type} already exists`, io).code;
+    }
+    const js = await io.host.readText(join(source, "scene.js"));
+    const html = await io.host.readText(join(source, "fragment.html"));
+    const cssPath = join(source, "style.css");
+    const css = (await io.host.exists(cssPath)) ? await io.host.readText(cssPath) : undefined;
+    for (const [name, text] of promoteFiles(type, {
+        js,
+        html,
+        ...(css === undefined ? {} : { css }),
+    })) {
+        await io.host.writeText(join(target, name), text);
+    }
+    io.stdout(`promoted ${dir} -> ${CATALOG_DIR}/${type}\n`);
+    io.stdout(`register it in the catalog registry:\n`);
+    io.stdout(`  import { ${exportName(type)} } from "./scenes/${type}/index.ts";\n`);
+    io.stdout(`  ${exportName(type)},\n`);
+    io.stdout(`then run pnpm test (the catalog snapshot will ask for the new type).\n`);
+    return EXIT.OK;
+}
+const PROMOTE_FLAGS = { as: { type: "string" } };
+export { runLint as sceneLint, runNew as sceneNew, runPromote as scenePromote, USAGE as SCENE_AUTHOR_USAGE, };

package/dist/scene/command.d.ts

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