@anvpx/motion-cli 0.1.0 → 0.1.1

package/README.md

@@ -105,7 +105,7 @@ Add to the repo-root `package.json`:
 
 ## Install qualification (DL-01)
 
-Install is the npm package install plus `mk doctor` hints; `mk plugin install --out <dir>` stays a separate explicit step, never part of npm install. Qualify with `node scripts/qualify-pack.mjs --json`: fresh pack records full inventory/SHA (`tarball.members`, `sha256`, bytes, `node`/`pnpm`/`npm`/`tar` versions, packed `hyperframes` pin vs root pin, `unpublishedInternals`), installs in an empty external consumer with no workspace fallback (`pnpm-workspace.yaml`/`packages/` absent), then runs native `doctor`/`catalog`/`template list`/`template validate explain` plus `new`/`validate`/`build`/`preview --stills 1 --budget-sec 20`/`approve` smoke with missing-target negatives; final `gated-render`/`verify` stay `NOT_RUN` without an explicit yes (do not render). Registry/marketplace stay `NOT_RUN`; isolated install is currently `BLOCKED` (`404` on unpublished `0.0.0` internals, `base: BLOCKED`; see DISTRIBUTION MK-080 choices A/B). Missing guide/index/font/icon/bed, source fallback reachable, wrong pin, broken install, missing venv/WAV all fail closed with actionable nonzero diagnostics (`reinstall @anvpx/motion`, `copy-dist-assets`, `mk doctor`, `py -3.12 -m venv .venv-voice`).
+Install is the npm package install plus `mk doctor` hints; `mk plugin install --out <dir>` stays a separate explicit step, never part of npm install. Qualify with `node scripts/qualify-pack.mjs --json`: fresh pack records full inventory/SHA (`tarball.members`, `sha256`, bytes, `node`/`pnpm`/`npm`/`tar` versions, packed `hyperframes` pin vs root pin, `unpublishedInternals`), installs in an empty external consumer with no workspace fallback (`pnpm-workspace.yaml`/`packages/` absent), then runs native `doctor`/`catalog`/`template list`/`template validate explain` plus `new`/`validate`/`build`/`preview --stills 1 --budget-sec 20`/`approve` smoke with missing-target negatives; final `gated-render`/`verify` stay `NOT_RUN` without an explicit yes (do not render). Registry/marketplace stay `NOT_RUN`; isolated install is currently `BLOCKED` (`404` on unpublished `0.0.0` internals, `base: BLOCKED`; see DISTRIBUTION MK-080 choices A/B). Missing guide/index/font/icon/bed, source fallback reachable, wrong pin, broken install, missing venv/WAV all fail closed with actionable nonzero diagnostics (`reinstall @anvpx/motion`, `scaffold`, `mk doctor`, `py -3.12 -m venv .venv-voice`).
 
 ## Voice and music delivery (DL-01)
 

package/dist/approval/hash.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { AUDIO_DIR_NAME, normaliseRef as buildNormaliseRef, clipsFromManifest, isContiguous, parseAudioManifest, readRelativeClosure, resolveSceneDir, } from "@anvpx/motion-build";
+import { AUDIO_DIR_NAME, normaliseRef as buildNormaliseRef, clipsFromManifest, isContiguous, parseAudioManifest, placementsFromTimeline, readRelativeClosure, resolveSceneDir, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
 import { parseMusicBed } from "@anvpx/motion-schema";
 import { sceneContainment } from "../storyboard/containment.js";
 export const MK_DIR = ".mk";
@@ -267,7 +267,7 @@ const readLedgerSha = async (host, ledgerPath) => {
     }
 };
 /** Resolves --audio TimingManifest plus every sibling wav into refs + mix. Fails closed. */
-const readAudioRefs = async (host, projectDir, audioManifestPath) => {
+const readAudioRefs = async (host, projectDir, audioManifestPath, storyboardJson) => {
     let text;
     try {
         text = await host.readText(audioManifestPath);
@@ -287,7 +287,20 @@ const readAudioRefs = async (host, projectDir, audioManifestPath) => {
         throw new Error(`invalid --audio manifest ${audioManifestPath}: ${parsed.problems.join("; ")}`);
     }
     const audioDir = join(dirname(resolve(audioManifestPath)), AUDIO_DIR_NAME);
-    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    // The manifest is a non-overlapping voice sequence; the film may start a
+    // scene 0.5 s early for a transition. Bind the placement the renderer will
+    // actually use, not the voice sequence's cumulative start.
+    const valid = validateStoryboardFull(storyboardJson);
+    if (!valid.ok) {
+        throw new Error(`--audio manifest cannot be placed: the storyboard is invalid`);
+    }
+    const timeline = resolveTimeline(valid.value, parsed.manifest);
+    if (!timeline.ok) {
+        throw new Error(`--audio manifest ${audioManifestPath} does not fit the storyboard: ` +
+            timeline.errors.map((error) => error.message).join("; "));
+    }
+    const placements = placementsFromTimeline(timeline.value);
+    const clips = clipsFromManifest(parsed.manifest, audioDir, placements);
     if (clips.length === 0) {
         throw new Error(`--audio manifest ${audioManifestPath} has no scenes; nothing to mix`);
     }
@@ -314,7 +327,7 @@ const readAudioRefs = async (host, projectDir, audioManifestPath) => {
         throw new Error(`--audio manifest ${audioManifestPath} escapes the project (escape)`);
     }
     const audioManifest = { path: manifestRel, sha256: sha256(text) };
-    const mode = clips.length === 1 ? "single" : isContiguous(parsed.manifest.scenes) ? "concat" : "adelay";
+    const mode = clips.length === 1 ? "single" : isContiguous(clips) ? "concat" : "adelay";
     return { audio, audioManifest, mix: { mode, clips: mixClips } };
 };
 /** Resolves --music bed wav plus volume and license-evidence receipt. Fails closed. */
@@ -392,7 +405,7 @@ export async function buildApprovalInputManifest(host, storyboard, opts = {}) {
             audio: [],
         };
     }
-    const { audio, audioManifest, mix } = await readAudioRefs(host, projectDir, opts.audioManifest);
+    const { audio, audioManifest, mix } = await readAudioRefs(host, projectDir, opts.audioManifest, parsed);
     const music = opts.music === undefined
         ? undefined
         : await readMusicRefs(host, projectDir, opts.music, opts.musicVolume, opts.musicLicense);

package/dist/plugin/install.d.ts

@@ -12,8 +12,8 @@ import type { Command } from "../types.ts";
  * at real versions) or choiceB (bundle into one tarball); either lands with
  * a version bump of core manifest + this pin + plugin.json together.
  */
-export declare const PINNED_CORE_VERSION = "0.1.0";
-export declare const PINNED_NPX = "npx -y @anvpx/motion@0.1.0";
+export declare const PINNED_CORE_VERSION = "0.1.1";
+export declare const PINNED_NPX = "npx -y @anvpx/motion@0.1.1";
 /** Skill file whose sha256 must survive `plugin install` byte for byte. */
 export declare const PLUGIN_SKILL: string;
 export interface PluginEnv {

package/dist/plugin/install.js

@@ -17,7 +17,7 @@ import { EXIT } from "../exit-codes.js";
  * at real versions) or choiceB (bundle into one tarball); either lands with
  * a version bump of core manifest + this pin + plugin.json together.
  */
-export const PINNED_CORE_VERSION = "0.1.0";
+export const PINNED_CORE_VERSION = "0.1.1";
 export const PINNED_NPX = `npx -y @anvpx/motion@${PINNED_CORE_VERSION}`;
 /** Skill file whose sha256 must survive `plugin install` byte for byte. */
 export const PLUGIN_SKILL = join("skills", "motion-kit", "SKILL.md");

package/dist/preview/command.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { validateMusicBed } from "@anvpx/motion-audio";
-import { AUDIO_DIR_NAME, CUSTOM_SCENE_TYPE, clipsFromManifest, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, mixAtDeliveryLevel, parseAudioManifest, readRelativeClosure, resolveSceneDir, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
+import { AUDIO_DIR_NAME, CUSTOM_SCENE_TYPE, clipsFromManifest, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, mixAtDeliveryLevel, parseAudioManifest, placementsFromTimeline, readRelativeClosure, resolveSceneDir, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
 import { buildApprovalInputManifest, hashApprovalInput, storyboardHash, } from "../approval/hash.js";
 import { parseFlags, requireStoryboard, textFlag, usageError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
@@ -521,7 +521,13 @@ const mixPreviewClip = async (io, pack, work, audioManifest, storyboard, expecte
         return EXIT.USAGE;
     }
     const audioDir = join(dirname(resolve(audioManifest)), AUDIO_DIR_NAME);
-    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    // Place the voice sequence on the film timeline (transitions start scenes
+    // early), not on the manifest's cumulative starts.
+    const boardLoaded = await readJsonFile(storyboard, io.host);
+    const validBoard = boardLoaded.ok ? validateStoryboardFull(boardLoaded.value) : undefined;
+    const timeline = validBoard?.ok === true ? resolveTimeline(validBoard.value, parsed.manifest) : undefined;
+    const placements = timeline?.ok === true ? placementsFromTimeline(timeline.value) : undefined;
+    const clips = clipsFromManifest(parsed.manifest, audioDir, placements);
     if (clips.length === 0) {
         io.stderr(`mk preview: --audio manifest has no scenes; nothing to mix; ${rerun}\n`);
         return EXIT.USAGE;

package/dist/scene/author.js

@@ -20,7 +20,7 @@ const NEW_FLAGS = {
     force: { type: "boolean" },
 };
 const SCENE_JS = `// @ts-check
-import { mountTimeline } from "../../runtime/mount.js";
+import { ease, interpolate, progress } from "../../runtime/compose.js";
 
 /**
  * Authored scene: seek(t) must be a pure function of t.
@@ -29,33 +29,52 @@ import { mountTimeline } from "../../runtime/mount.js";
  * @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 element = /** @type {HTMLElement | null} */ (root.querySelector(".authored-element"));
+  if (!element) throw new Error("authored scene: missing .authored-element");
+  // Replace the markup, layout and these values with the direction's composition.
+  // Derive every animated value on EVERY seek, including backward seeks.
+  const seek = (t) => {
+    const amount = ease("out", progress(t, 0, 0.8));
+    element.style.opacity = String(amount);
+    element.style.transform = "translateY(" + interpolate(24, 0, amount) + "px)";
+  };
+  seek(0);
+  return {
+    seek,
+    dispose() {
+      element.style.removeProperty("opacity");
+      element.style.removeProperty("transform");
+    },
+    ready: Promise.resolve(),
+  };
 }
 `;
-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>
+const FRAGMENT_HTML = `<div class="authored-composition">
+  <h1 class="authored-element" data-focus-key="subject">Your composition</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 STYLE_CSS = `/* A blank starting surface: design its grid, layers and type from the brief. */
+#scene-root .authored-composition { display: grid; place-items: center; width: 100%; height: 100%; }
+#scene-root .authored-element {
+  margin: 0;
+  font: inherit;
+  font-size: clamp(32px, 6vw, 96px);
+  color: var(--mk-color-fg);
 }
 `;
 const notes = (id) => `# ${id}
 
 Why this scene exists: <one line>.
 
-Promote it to the catalog (\`mk scene promote\`) once two projects use it.
+Direction: <concept, composition, type, motion and sound decisions>.
+
+The markup and motion are yours to replace. Shared \`runtime/compose.js\` offers
+\`progress(t, start, duration)\`, \`interpolate(from, to, amount)\`,
+\`stagger(index, step, start)\` and the existing \`ease(name, amount)\` functions.
+All times are seconds. Progress clamps to 0..1; a zero duration is a cut.
+Assign every animated property from t so seeking A -> B -> A restores A.
+
+Promotion to the catalog (\`mk scene promote\`) is optional when reuse justifies it.
 `;
 const FILES = (id) => [
     ["scene.js", SCENE_JS],

package/dist/voice/run.d.ts

@@ -13,6 +13,12 @@ export interface VoiceRunOptions {
 export declare const VOICE_WAV_FALLBACK_NOTE = "pre-rendered WAV fallback in pack";
 export declare const VOICE_MEASURED_QC_NOTE = "human QC via `mk qc` (pronunciation/intelligibility/pacing/alignment/no-silence)";
 export declare const VOICE_ENV_NOTE = "BLOCKED_ENV stays NOT_RUN, never PASS";
+/**
+ * Tokens the aligner cannot match: a number with no letters (`01`, `$480`,
+ * `1,200`). `mk voice` must fail before synthesis with a fix, not after the
+ * aligner reports `clean_word empty`.
+ */
+export declare const unspokenNarrationTokens: (narration: string) => string[];
 /**
  * Synthesize every narrated base scene, align words, gate silence, and write
  * `.mk/<stem>/voice-manifest.json` + licences-style provenance. Resolves to

package/dist/voice/run.js

@@ -74,16 +74,24 @@ const gateSilence = async (io, sceneId, audioPath, words) => {
     return { silences: silence.intervals };
 };
 /**
- * A6: narration must fit the scene at 180 wpm before anything is synthesized.
- * The render-time reading/narration checks then cannot fail for a length the
- * voice command could have refused; the fix names the scene and the exact edit.
+ * Tokens the aligner cannot match: a number with no letters (`01`, `$480`,
+ * `1,200`). `mk voice` must fail before synthesis with a fix, not after the
+ * aligner reports `clean_word empty`.
+ */
+export const unspokenNarrationTokens = (narration) => splitTokens(narration).filter((token) => /[0-9]/.test(token) && !/\p{L}/u.test(token));
+/**
+ * A6: narration must fit the scene at 180 wpm before anything is synthesized,
+ * and numbers must be written as spoken. The render-time reading/narration
+ * checks then cannot fail for a length the voice command could have refused.
  */
 function narrationFitProblems(board) {
     const timeline = resolveTimeline(board.board);
     if (!timeline.ok)
         return timeline.errors.map((error) => `${error.path}: ${error.message}`);
     const available = new Map(timeline.value.scenes.map((scene) => [scene.id, scene.duration]));
-    return board.narrated.flatMap((scene) => {
+    const unspoken = board.narrated.flatMap((scene) => unspokenNarrationTokens(scene.narration ?? "").map((token) => `"${scene.id}": token "${token}" has no letters; write numbers as spoken ` +
+        `(for example "zero one" or "four hundred eighty")`));
+    const lengths = board.narrated.flatMap((scene) => {
         const count = splitTokens(scene.narration ?? "").length;
         const needed = Math.ceil(count / WORDS_PER_SECOND);
         const seconds = available.get(scene.id) ?? scene.duration ?? 0;
@@ -95,6 +103,7 @@ function narrationFitProblems(board) {
                 `scene is ${seconds}s; set duration >= ${needed} or cut ${excess} word(s)`,
         ];
     });
+    return [...unspoken, ...lengths];
 }
 /** Synth + align + silence gate for one narrated scene; fails closed, never fakes.
  * `j*` (Japanese-pipeline) voices are unaligned-only: the EN wav2vec2 aligner
@@ -160,7 +169,7 @@ export async function runVoice(storyboard, options, io) {
         return board;
     const misfit = narrationFitProblems(board);
     if (misfit.length > 0) {
-        io.stderr(`mk voice: narration does not fit before synthesis:\n${misfit.map((line) => `  - ${line}`).join("\n")}\n`);
+        io.stderr(`mk voice: narration cannot be synthesized yet:\n${misfit.map((line) => `  - ${line}`).join("\n")}\n`);
         return EXIT.USAGE;
     }
     const picked = await pickPython(io, options.python);

package/dist/workflow/draft.js

@@ -1,6 +1,6 @@
 import { dirname, join, resolve } from "node:path";
 import { validateMusicBed } from "@anvpx/motion-audio";
-import { AUDIO_DIR_NAME, clipsFromManifest, missingMusic, mixAtDeliveryLevel, parseAudioManifest, } from "@anvpx/motion-build";
+import { AUDIO_DIR_NAME, clipsFromManifest, missingMusic, mixAtDeliveryLevel, parseAudioManifest, placementsFromTimeline, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
 import { textFlag, usageError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
 import { readJsonFile } from "../storyboard/load.js";
@@ -46,8 +46,19 @@ const downscale = (input, output) => [
     "copy",
     output,
 ];
+/** Final-timeline start/duration per narrated scene; undefined when the board cannot resolve. */
+async function voicePlacements(storyboard, manifest, io) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok)
+        return undefined;
+    const valid = validateStoryboardFull(loaded.value);
+    if (!valid.ok)
+        return undefined;
+    const timeline = resolveTimeline(valid.value, manifest);
+    return timeline.ok ? placementsFromTimeline(timeline.value) : undefined;
+}
 /** Loads a voice TimingManifest plus its sibling wavs; fails closed, never silent. */
-async function loadNarration(audioPath, io) {
+async function loadNarration(storyboard, audioPath, io) {
     const loaded = await readJsonFile(audioPath, io.host);
     if (!loaded.ok) {
         io.stderr(`mk draft: cannot read --audio manifest: ${loaded.message}\n`);
@@ -59,7 +70,8 @@ async function loadNarration(audioPath, io) {
         return { ok: false, code: EXIT.USAGE };
     }
     const audioDir = join(dirname(resolve(audioPath)), AUDIO_DIR_NAME);
-    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    const placements = await voicePlacements(storyboard, parsed.manifest, io);
+    const clips = clipsFromManifest(parsed.manifest, audioDir, placements);
     if (clips.length === 0) {
         io.stderr("mk draft: --audio manifest has no scenes; nothing to mix\n");
         return { ok: false, code: EXIT.USAGE };
@@ -101,7 +113,9 @@ async function resolveDraftPlan(args, io) {
             code: usageError("draft", USAGE, "--music needs --audio: the bed loops to the narration length", io).code,
         };
     }
-    const narration = audioPath === undefined ? undefined : await loadNarration(audioPath, io);
+    const narration = audioPath === undefined
+        ? undefined
+        : await loadNarration(parsed.request.storyboard, audioPath, io);
     if (narration !== undefined && !narration.ok)
         return { code: narration.code };
     const bedded = musicPath === undefined ? undefined : await loadMusic(musicPath, io);

package/dist/workflow/render.js

@@ -1,6 +1,6 @@
 import { dirname, join, resolve } from "node:path";
 import { validateMusicBed } from "@anvpx/motion-audio";
-import { AUDIO_DIR_NAME, clipsFromManifest, compiledAssetMismatches, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, missingMusic, mixAtDeliveryLevel, parseAudioManifest, } from "@anvpx/motion-build";
+import { AUDIO_DIR_NAME, clipsFromManifest, compiledAssetMismatches, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, missingMusic, mixAtDeliveryLevel, parseAudioManifest, placementsFromTimeline, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
 import { approvalState, readApproval } from "../approval/approval.js";
 import { buildApprovalInputManifest, hashApprovalInput, } from "../approval/hash.js";
 import { textFlag, usageError } from "../args.js";
@@ -133,8 +133,19 @@ export async function exportArtifact(io, outDir, format) {
 /** sha256 of zero bytes: a silent/empty wav can never qualify as audible proof. */
 const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 const isFps = (text) => /^\d+$/.test(text) && Number(text) >= 1 && Number(text) <= MAX_FPS;
+/** Final-timeline start/duration per narrated scene; undefined when the board cannot resolve. */
+async function voicePlacements(storyboard, manifest, io) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok)
+        return undefined;
+    const valid = validateStoryboardFull(loaded.value);
+    if (!valid.ok)
+        return undefined;
+    const timeline = resolveTimeline(valid.value, manifest);
+    return timeline.ok ? placementsFromTimeline(timeline.value) : undefined;
+}
 /** Loads a voice TimingManifest plus its sibling wavs; fails closed, never silent. */
-async function loadNarration(name, audioPath, io) {
+async function loadNarration(name, storyboard, audioPath, io) {
     const loaded = await readJsonFile(audioPath, io.host);
     if (!loaded.ok) {
         io.stderr(`mk ${name}: cannot read --audio manifest: ${loaded.message}\n`);
@@ -146,7 +157,10 @@ async function loadNarration(name, audioPath, io) {
         return { ok: false, code: EXIT.USAGE };
     }
     const audioDir = join(dirname(resolve(audioPath)), AUDIO_DIR_NAME);
-    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    // The voice manifest is a non-overlapping audio sequence; the picture starts
+    // scenes early for transitions. Place each wav on the resolved film timeline.
+    const placements = await voicePlacements(storyboard, parsed.manifest, io);
+    const clips = clipsFromManifest(parsed.manifest, audioDir, placements);
     if (clips.length === 0) {
         io.stderr(`mk ${name}: --audio manifest has no scenes; nothing to mix\n`);
         return { ok: false, code: EXIT.USAGE };
@@ -249,7 +263,9 @@ async function resolvePlan(args, io) {
             code: usageError("render", USAGE, "--music needs --audio: the bed loops to the narration length", io).code,
         };
     }
-    const narration = audioPath === undefined ? undefined : await loadNarration("render", audioPath, io);
+    const narration = audioPath === undefined
+        ? undefined
+        : await loadNarration("render", parsed.request.storyboard, audioPath, io);
     if (narration !== undefined && !narration.ok)
         return { code: narration.code };
     const bedded = musicPath === undefined ? undefined : await loadMusic("render", musicPath, io, musicVolume);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvpx/motion-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The mk CLI for @anvpx/motion: validate, preview, approve and render storyboards.",
   "license": "MIT",
   "author": "anvpx",
@@ -30,10 +30,10 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@anvpx/motion-audio": "0.1.0",
-    "@anvpx/motion-build": "0.1.0",
-    "@anvpx/motion-schema": "0.1.0",
-    "@anvpx/motion-templates": "0.1.0"
+    "@anvpx/motion-audio": "0.1.1",
+    "@anvpx/motion-build": "0.1.1",
+    "@anvpx/motion-schema": "0.1.1",
+    "@anvpx/motion-templates": "0.1.1"
   },
   "scripts": {
     "test:integration": "vitest run --config vitest.integration.config.ts"