@odori/cli 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "The odori command line: discovery, Studio, component installation, stills, tests, and export jobs.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "playwright-core": "1.55.0",
     "tsx": "4.20.5",
     "vite": "7.3.0",
-    "odori": "0.0.3"
+    "odori": "0.0.5"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
@@ -36,7 +36,7 @@
     "@types/react-dom": "19.2.3",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
-    "@odori/registry": "0.0.3"
+    "@odori/registry": "0.0.5"
   },
   "publishConfig": {
     "access": "public"

package/src/assets.ts

@@ -0,0 +1,90 @@
+import {createHash} from "node:crypto";
+import {existsSync} from "node:fs";
+import {mkdir, readFile, rm, writeFile} from "node:fs/promises";
+import {dirname, relative, resolve} from "node:path";
+import type {ResolvedConfig} from "./config";
+import {log} from "./log";
+import {cacheRoot} from "./binaries";
+import {registryOrigin, resolveWithinRoot, type RegistryComponent} from "./registry-source";
+
+/**
+ * Installing a produced file.
+ *
+ * Most of the registry is source, and source is what `odori add` was built to
+ * copy. Some sound cannot be reached from oscillators — a keyboard, a room, a
+ * voice — so those ship as recordings instead, and installing one has to mean
+ * fetching bytes rather than writing a module. The rules are the same rules:
+ * the destination is confined to the project, the bytes are checked against
+ * the hash the registry published before anything is written, and a file the
+ * project already has is left alone unless replacing it was asked for.
+ *
+ * The download is cached beside the browser and the encoder, so a second
+ * project on the same machine costs no second round trip.
+ */
+const assetCache = (integrity: string): string =>
+  resolve(cacheRoot(), "assets", createHash("sha256").update(integrity).digest("hex").slice(0, 16));
+
+const verify = (bytes: Uint8Array, expected: string, source: string): void => {
+  const actual = `sha256-${createHash("sha256").update(bytes).digest("base64")}`;
+  if (actual === expected) return;
+  throw new Error(
+    `The bytes at ${source} do not match the hash the registry published.\n` +
+      `  expected ${expected}\n  received ${actual}\n` +
+      "Nothing was written. This is a truncated download, a stale proxy, or a tampered file.",
+  );
+};
+
+export const installAsset = async (
+  config: ResolvedConfig,
+  component: RegistryComponent,
+  options: {dryRun?: boolean; force?: boolean} = {},
+): Promise<boolean> => {
+  const asset = component.asset;
+  if (!asset) return false;
+
+  const destination = resolveWithinRoot(config.root, asset.target);
+  const exists = existsSync(destination);
+  log.detail(`  ${exists ? "replace" : "create "} ${relative(config.root, destination)}`);
+  if (options.dryRun) return false;
+
+  if (exists && !options.force) {
+    log.warn(`${relative(config.root, destination)} already exists. Keeping it. Use --force to replace it.`);
+    return true;
+  }
+
+  const cached = assetCache(asset.integrity);
+  let bytes: Uint8Array | null = null;
+
+  if (existsSync(cached)) {
+    const stored = await readFile(cached);
+    // A cache that does not verify is a cache miss, not a failure: the bytes
+    // on the machine are the one part of this nobody published. Refusing here
+    // would strand a project behind a corrupt file it never asked for.
+    try {
+      verify(stored, asset.integrity, cached);
+      bytes = stored;
+    } catch {
+      log.detail("  the cached copy did not verify; downloading it again");
+      await rm(cached, {force: true});
+    }
+  }
+
+  if (!bytes) {
+    const url = new URL(asset.url, `${registryOrigin(config)}/`).toString();
+    const response = await fetch(url, {signal: AbortSignal.timeout(30_000)});
+    if (!response.ok) throw new Error(`Could not download ${url}: ${response.status} ${response.statusText}`);
+    const downloaded = new Uint8Array(await response.arrayBuffer());
+    // A download that does not verify is a failure: this is the check that
+    // makes fetching bytes into somebody's repository defensible.
+    verify(downloaded, asset.integrity, url);
+    await mkdir(dirname(cached), {recursive: true});
+    await writeFile(cached, downloaded);
+    bytes = downloaded;
+  }
+
+  await mkdir(dirname(destination), {recursive: true});
+  await writeFile(destination, bytes);
+  log.success(`${component.namespaced} to ${relative(config.root, destination)}`);
+  log.detail(`  ${component.family} · ${Math.round(asset.bytes / 1024)} KB · answers to "${asset.cue}"`);
+  return true;
+};

package/src/brand-file.ts

@@ -48,9 +48,13 @@ const brandFiles = async (config: ResolvedConfig): Promise<string[]> => {
  */
 export const registerCueInBrand = async (
   config: ResolvedConfig,
-  cue: {name: string; export: string},
+  cue: {name: string; export: string} | {name: string; url: string},
   componentName: string,
 ): Promise<BrandRegistration | null> => {
+  // A score is registered by calling its factory, which needs an import. A
+  // recording is registered by its URL, which needs nothing: the value is the
+  // path the dev server and the render worker both serve it from.
+  const url = "url" in cue ? cue.url : null;
   for (const file of await brandFiles(config)) {
     const source = await readFile(file, "utf8");
     if (source.includes(`"${cue.name}"`) || source.includes(`'${cue.name}'`)) {
@@ -62,26 +66,34 @@ export const registerCueInBrand = async (
     const block = source.match(/(audio:\s*\{[\s\S]*?cues:\s*\{)([\s\S]*?)(\n(\s*)\},)/);
     const inline = source.match(/(audio:\s*\{[^\n}]*cues:\s*\{)([^\n{}]*)(\})/);
 
+    const value = url ? JSON.stringify(url) : `${(cue as {export: string}).export}()`;
+
     let withCue: string;
     if (block) {
       const indent = `${block[4]}  `;
-      const entry = `\n${indent}"${cue.name}": ${cue.export}(),`;
+      const entry = `\n${indent}"${cue.name}": ${value},`;
       withCue = source.replace(block[0], `${block[1]}${block[2]}${entry}${block[3]}`);
     } else if (inline) {
       // An inline block grows in place rather than being reformatted: this
       // edits somebody's source, and reflowing their file is not the job.
       const existing = inline[2].trim();
-      const entry = `"${cue.name}": ${cue.export}()`;
+      const entry = `"${cue.name}": ${value}`;
       withCue = source.replace(inline[0], `${inline[1]}${existing ? `${existing.replace(/,$/, "")}, ` : ""}${entry}${inline[3]}`);
     } else {
       continue;
     }
 
+    // A URL needs no import, so the edit is finished.
+    if (url) {
+      await writeFile(file, withCue, "utf8");
+      return {file: relative(config.root, file), already: false};
+    }
+
     // The import path is relative to the brand file, which is usually the
     // layout beside videos/components.
     const from = resolve(config.root, config.componentsDir, componentName, componentName);
     const specifier = relative(resolve(file, ".."), from).split("\\").join("/");
-    const importLine = `import {${cue.export}} from "${specifier.startsWith(".") ? specifier : `./${specifier}`}";`;
+    const importLine = `import {${(cue as {export: string}).export}} from "${specifier.startsWith(".") ? specifier : `./${specifier}`}";`;
     const withImport = withCue.includes(importLine)
       ? withCue
       : withCue.replace(/^(import [\s\S]*?;\n)/, `$1${importLine}\n`);

package/src/cli.ts

@@ -10,11 +10,24 @@ import {initCommand} from "./commands/init";
 import {inspectCommand} from "./commands/inspect";
 import {listCommand} from "./commands/list";
 import {newCommand} from "./commands/new";
-import {stillCommand} from "./commands/still";
+import {frameCommand} from "./commands/frame";
 import {testCommand} from "./commands/test";
 
 type Flags = Record<string, string | boolean>;
 
+/**
+ * Flags that are on or off, and therefore never take the next word.
+ *
+ * Without this list `odori add --force title-reveal` reads "force" as the
+ * string "title-reveal": the flag does nothing and the component quietly
+ * vanishes from the list, which is two failures for the price of one and
+ * neither of them says anything. A switch has no value to take.
+ */
+const BOOLEAN_FLAGS = new Set(["force", "dry-run", "json", "no-audio", "no-frame-skip", "no-open", "open", "help", "version"]);
+
+/** Commands that used to exist under another name. */
+const RENAMED: Record<string, string> = {still: "frame"};
+
 export const parseArgs = (argv: string[]): {command: string; positionals: string[]; flags: Flags} => {
   const [command = "help", ...rest] = argv;
   const positionals: string[] = [];
@@ -31,7 +44,7 @@ export const parseArgs = (argv: string[]): {command: string; positionals: string
       }
       const name = token.slice(2);
       const next = rest[index + 1];
-      if (next === undefined || next.startsWith("--")) flags[name] = true;
+      if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) flags[name] = true;
       else {
         flags[name] = next;
         index += 1;
@@ -84,9 +97,9 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   update: ["force"],
   list: [],
   inspect: ["json", "input"],
-  still: ["frame", "output", "input"],
+  frame: ["at", "output", "input"],
   test: ["json"],
-  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-audio", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -160,18 +173,20 @@ const USAGE: Record<string, string> = {
   Print discovered video ids and formats.`,
   inspect: `odori inspect <id> [--json] [--input <json>]
   Show resolved layout, inputs, scenes, and assets.`,
-  still: `odori still <id> --frame <n> [--output <path>] [--input <json>]
-  Render one deterministic frame.`,
+  frame: `odori frame <id> --at <time> [--output <path>] [--input <json>]
+  Render one deterministic frame to a PNG. --at is a duration: 4s, 500ms, or
+  120f for frame 120. A bare number is seconds.`,
   test: `odori test [id] [--json]
   Validate contracts and representative frames. --json emits one object per
   check, for CI.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
              [--preset <name>] [--format <name>] [--quality <tier>] [--scale <n>]
-             [--no-frame-skip] [--retry <job>]
+             [--no-audio] [--no-frame-skip] [--retry <job>]
   Render and encode a distributable file. --format is mp4, webm, prores, gif,
   or png; without it the output's extension decides, and mp4 is the default.
   --quality is studio, social, or web. --scale multiplies the output size,
-  0.25 to 2. A retry keeps the settings its job was created with.`,
+  0.25 to 2. --no-audio writes the picture with no sound. A retry keeps the
+  settings its job was created with.`,
   jobs: `odori jobs
   List export jobs and their status.`,
 };
@@ -190,14 +205,14 @@ Usage
   odori update [components]        Apply upstream component changes
   odori list                       Print discovered video ids and formats
   odori inspect <id> [--json]      Show resolved layout, inputs, scenes, assets
-  odori still <id> --frame 120     Render one deterministic frame
+  odori frame <id> --at 4s          Render one deterministic frame to a PNG
   odori test [id] [--json]         Validate contracts and representative frames
   odori export <id> [--output f]   Render and encode a distributable file
   odori jobs                       List export jobs and their status
 
 Options
   --input '{"headline":"..."}'     Serializable input for the video schema
-  --output <path>                  Output path for still and export
+  --output <path>                  Output path for frame and export
   --force                          Replace locally modified component source
   --concurrency <n>                Parallel render workers for export
   --preset <name>                  x264 preset for export, default medium
@@ -280,9 +295,11 @@ export const run = async (argv: string[]): Promise<number> => {
       case "inspect":
         await inspectCommand(positionals[0] ?? "", {json: flags.json === true, input: parseInput(flags)});
         return 0;
-      case "still":
-        await stillCommand(positionals[0] ?? "", {
-          frame: numberFlag(flags, "frame") ?? 0,
+      case "frame":
+        await frameCommand(positionals[0] ?? "", {
+          // A duration, so "4s" and "120f" both work; a bare number is
+          // seconds, the way every other time value in Odori reads.
+          at: typeof flags.at === "string" ? flags.at : (numberFlag(flags, "at") ?? 0),
           output: typeof flags.output === "string" ? flags.output : undefined,
           input: parseInput(flags),
         });
@@ -299,6 +316,7 @@ export const run = async (argv: string[]): Promise<number> => {
           quality: typeof flags.quality === "string" ? flags.quality : undefined,
           scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : undefined,
+          audio: flags["no-audio"] === true ? false : undefined,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,
         });
@@ -312,6 +330,13 @@ export const run = async (argv: string[]): Promise<number> => {
         log.info(HELP);
         return 0;
       default: {
+        // A rename is not a typo, and edit distance will never connect the old
+        // name to the new one. Say what happened instead of listing everything.
+        const renamed = RENAMED[command];
+        if (renamed) {
+          log.error(`"odori ${command}" is now "odori ${renamed}".`);
+          return 1;
+        }
         const commands = Object.keys(COMMAND_FLAGS).filter((name) => name !== "help");
         const suggestion = nearest(command, commands);
         log.error(`Unknown command "${command}".${suggestion ? ` Did you mean "odori ${suggestion}"?` : ""}`);

package/src/commands/add.ts

@@ -6,6 +6,7 @@ import {loadConfig} from "../config";
 import {log} from "../log";
 import {registerCueInBrand} from "../brand-file";
 import {assertSafeName, normalizeComponentName, registryUrl, resolveItem, resolveRegistry, resolveWithinRoot, verifyIntegrity} from "../registry-source";
+import {installAsset} from "../assets";
 import {readProvenance, writeProvenance} from "./update";
 
 /**
@@ -29,6 +30,10 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
 
   const queue = [...names.map(normalizeComponentName)];
   const installed: string[] = [];
+  /* Kept so the summary can repeat itself at the end. Installing a library is
+     hundreds of lines of output, and a warning at line 40 is a warning nobody
+     read. */
+  const kept: string[] = [];
 
   while (queue.length > 0) {
     const name = queue.shift()!;
@@ -46,6 +51,30 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
       else log.warn(`${component.namespaced} needs a "${cue}" cue and no registry entry provides one.`);
     }
 
+    // An asset is bytes, not source: it is fetched, verified, and written into
+    // public/, then registered by URL. Nothing about it is a file to edit, so
+    // it never goes through the copy-and-record path below.
+    if (component.kind === "asset" && component.asset) {
+      const written = await installAsset(config, component, {dryRun: options.dryRun, force: options.force});
+      if (!options.dryRun && written) {
+        installed.push(component.name);
+        const registered = await registerCueInBrand(
+          config,
+          {name: component.asset.cue, url: component.asset.url},
+          component.name,
+        );
+        if (registered?.already) {
+          log.detail(`  "${component.asset.cue}" is already registered in ${registered.file}`);
+        } else if (registered) {
+          log.detail(`  registered "${component.asset.cue}" in ${registered.file}`);
+        } else {
+          log.warn(`  No brand with an audio.cues block found. Add it yourself:`);
+          log.detail(`    audio: {cues: {"${component.asset.cue}": "${component.asset.url}"}}`);
+        }
+      }
+      continue;
+    }
+
     // The item document carries the file contents; the index does not.
     const {item, origin} = await resolveItem(config, component.name);
     // Before anything is written: the bytes have to be the bytes the registry
@@ -78,7 +107,8 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
         const current = hashString(await readFile(destination, "utf8"));
         const recorded = provenance[component.name]?.hashes[name];
         if (current !== recorded) {
-          log.warn(`${relative(config.root, destination)} was modified locally. Keeping your version. Use --force to replace it.`);
+          log.warn(`${relative(config.root, destination)} was modified locally. Keeping your version.`);
+          kept.push(relative(config.root, destination));
           continue;
         }
       }
@@ -122,6 +152,12 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
     return;
   }
   await writeProvenance(config, provenance);
+
+  if (kept.length > 0) {
+    log.warn(`Kept ${kept.length} locally modified ${kept.length === 1 ? "file" : "files"}:`);
+    for (const file of kept) log.detail(`  ${file}`);
+    log.detail(`Run odori diff to see what upstream changed, or odori add <name> --force to replace them.`);
+  }
   log.detail("Run odori dev to preview the installed component fixtures.");
 };
 

package/src/commands/dev.ts

@@ -1,4 +1,4 @@
-import {resolve} from "node:path";
+import {relative, resolve} from "node:path";
 import {homedir} from "node:os";
 import {existsSync} from "node:fs";
 import {readFile} from "node:fs/promises";
@@ -174,7 +174,10 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
                 exportDestination(config),
                 `${outputName(video.entry.metadata.id)}${format.extension}`,
               );
-              const record = await createJob(config, manifest, output, {format: format.name, quality, scale});
+              // Frozen with the job: a retry from the CLI has to produce the
+              // same file, silence included.
+              const audio = body.audio !== false;
+              const record = await createJob(config, manifest, output, {format: format.name, quality, scale, audio});
               json(response, 202, record.job);
 
               void runJob(config, origin, record, video).catch((error) => {
@@ -208,6 +211,33 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
               return;
             }
 
+            /**
+             * The source that produced the frame you are looking at.
+             *
+             * Studio shows the path already; a path you cannot read is a
+             * riddle. Reading is confined to source files inside the project,
+             * because this serves whatever a query string asks for and the
+             * only safe answer to "../../.ssh/id_rsa" is no.
+             */
+            if (request.method === "GET" && url.startsWith("/source")) {
+              const asked = new URL(url, "http://localhost").searchParams.get("file") ?? "";
+              const file = resolve(config.root, asked);
+              const inside = relative(config.root, file);
+              const readable = /\.(tsx?|jsx?|css|json|md)$/.test(file);
+              if (!inside || inside.startsWith("..") || !readable) {
+                json(response, 400, {error: `Refusing to read ${asked}.`});
+                return;
+              }
+              try {
+                response.statusCode = 200;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end(await readFile(file, "utf8"));
+              } catch {
+                json(response, 404, {error: `${asked} is not there.`});
+              }
+              return;
+            }
+
             if (request.method === "GET" && url.startsWith("/jobs")) {
               json(response, 200, await listJobs(config));
               return;

package/src/commands/doctor.ts

@@ -12,7 +12,14 @@ export type Check = {
   /** What was found. Printed on success and on failure alike. */
   detail: string;
   ok: boolean;
-  /** The command or edit that fixes it. Only read when `ok` is false. */
+  /**
+   * True for something that passes but is worth saying. A project is not
+   * broken by it and CI should not fail on it, which is exactly why it needs
+   * somewhere to be said: otherwise the only two volumes are silence and
+   * failure, and everything that deserves a word in between gets silence.
+   */
+  warn?: boolean;
+  /** The command or edit that fixes it. Only read when `ok` is false or warned. */
   fix?: string;
 };
 
@@ -125,6 +132,39 @@ export const runChecks = async (root: string): Promise<Check[]> => {
   } catch {
     writable = false;
   }
+  /**
+   * A component nobody can preview.
+   *
+   * Discovery is filename driven: a sibling `*.preview.tsx` is what makes a
+   * component exist to Studio, to the catalog and to the palette. Write one
+   * without it and it works perfectly inside its video and is invisible
+   * everywhere else, including to the person who has to tune it next week.
+   * That is a fine choice for a one-off set piece and an accident the rest of
+   * the time, so this counts them rather than ruling on them.
+   */
+  const componentsRoot = resolve(root, config.componentsDir);
+  const orphans: string[] = [];
+  if (existsSync(componentsRoot)) {
+    const {readdir} = await import("node:fs/promises");
+    for (const entry of await readdir(componentsRoot, {withFileTypes: true})) {
+      if (!entry.isDirectory()) continue;
+      const files = await readdir(resolve(componentsRoot, entry.name));
+      const source = files.some((file) => /\.tsx$/.test(file) && !file.endsWith(".preview.tsx"));
+      const fixture = files.some((file) => file.endsWith(".preview.tsx"));
+      if (source && !fixture) orphans.push(entry.name);
+    }
+  }
+  checks.push({
+    name: "Component previews",
+    detail:
+      orphans.length === 0
+        ? "every component has a fixture"
+        : `${orphans.length} without a fixture: ${orphans.slice(0, 4).join(", ")}${orphans.length > 4 ? ", …" : ""}`,
+    ok: true,
+    warn: orphans.length > 0,
+    fix: `Add a sibling <name>.preview.tsx with defineComponentPreview so Studio can play it on its own. A component with no fixture only ever renders inside a video.`,
+  });
+
   checks.push({
     name: "Generated cache",
     detail: writable ? ".odori/ is writable" : ".odori/ cannot be written",
@@ -146,13 +186,18 @@ export const doctorCommand = async (root = process.cwd()): Promise<number> => {
   log.title("odori doctor");
   for (const check of checks) {
     const label = check.name.padEnd(width);
-    if (check.ok) log.success(`${label}  ${check.detail}`);
+    if (check.ok && check.warn) log.warn(`${label}  ${check.detail}`);
+    else if (check.ok) log.success(`${label}  ${check.detail}`);
     else log.error(`${label}  ${check.detail}`);
   }
 
+  const warned = checks.filter((check) => check.ok && check.warn);
   const failed = checks.filter((check) => !check.ok);
   if (failed.length === 0) {
     log.detail("Everything a render needs is present.");
+    // A warning is not a failure, so it is said after the all clear rather
+    // than instead of it, and it never changes the exit code.
+    for (const check of warned) log.detail(`  ${check.fix}`);
     return 0;
   }
 

package/src/commands/exportVideo.ts

@@ -36,6 +36,7 @@ export const runJob = async (
     quality?: Quality;
     scale?: number;
     format?: VideoFormat;
+    audio?: boolean;
     skipUnchangedFrames?: boolean;
     signal?: AbortSignal;
     onProgress?: (job: ExportJob) => void;
@@ -94,6 +95,7 @@ export const runJob = async (
           quality: options.quality ?? (record.render?.quality as Quality | undefined),
           scale: options.scale ?? record.render?.scale,
           format: options.format ?? (record.render?.format ? resolveFormat(record.render.format, record.output) : undefined),
+          audio: options.audio ?? record.render?.audio,
           skipUnchangedFrames: options.skipUnchangedFrames,
           signal: controller.signal,
           onTimings: (timings) => {
@@ -151,6 +153,8 @@ export const exportCommand = async (
     quality?: string;
     scale?: number;
     format?: string;
+    /** False writes the picture with no audio track. */
+    audio?: boolean;
     skipUnchangedFrames?: boolean;
     retry?: string;
   } = {},
@@ -183,6 +187,7 @@ export const exportCommand = async (
             format: format.name,
             quality,
             scale,
+            audio: options.audio !== false,
             ...(options.preset ? {preset: options.preset} : {}),
           });
         })();
@@ -201,6 +206,7 @@ export const exportCommand = async (
       quality: options.retry && options.quality === undefined ? undefined : quality,
       scale: options.retry && options.scale === undefined ? undefined : scale,
       format: options.retry ? undefined : format,
+      audio: options.audio,
       skipUnchangedFrames: options.skipUnchangedFrames,
       onProgress: (next) => {
         if (next.status === "rendering" || next.status === "encoding") {

package/src/commands/{still.ts → frame.ts}

@@ -1,23 +1,37 @@
 import {resolve} from "node:path";
+import {framesFromOffset, resolveEntryLayout, type Duration} from "odori";
 import {log} from "../log";
 import {findVideo, freezeManifest, outputName} from "../project";
 import {renderStill} from "../render";
 import {compileInBrowser, createContext, targetFor, withServer} from "./shared";
 
-export const stillCommand = async (
+/**
+ * One frame of a video, as a PNG.
+ *
+ * `at` is a duration like everything else in Odori: a bare number is seconds,
+ * and `120f` is frame 120. Which frame that resolves to depends on the
+ * video's frame rate, and the frame rate belongs to the video's layout, so
+ * the position is checked for shape first and resolved once the video is
+ * loaded. A typo still costs nothing: no discovery, no dev server, no
+ * browser.
+ */
+export const frameCommand = async (
   id: string,
-  options: {frame?: number; output?: string; input?: Record<string, unknown>} = {},
+  options: {at?: Duration; output?: string; input?: Record<string, unknown>} = {},
 ) => {
-  const frame = options.frame ?? 0;
-  // A frame is an index into the timeline. Checking it first means a typo
-  // costs nothing: no discovery, no dev server, no browser.
-  if (!Number.isInteger(frame) || frame < 0) {
-    throw new Error(`Frame must be a whole number of frames from the start, got ${String(frame)}.`);
-  }
+  const at = options.at ?? 0;
+  // A position, not a length: frame zero is the first frame, so this is
+  // framesFromOffset rather than framesFromDuration, which floors at one. Any
+  // frame rate rejects a malformed duration, so this validates the shape
+  // before the work starts; the real rate resolves the number below.
+  framesFromOffset(at, 30);
 
   const {config, graph, videos} = await createContext();
   const video = findVideo(videos, id);
 
+  const fps = resolveEntryLayout(video.entry).format.fps;
+  const frame = framesFromOffset(at, fps);
+
   const output = await withServer(config, async (server) => {
     const {durationInFrames, scenes, audio} = await compileInBrowser(server.url, targetFor(video, options.input), config);
     const {manifest, input, prepared} = await freezeManifest(
@@ -35,6 +49,6 @@ export const stillCommand = async (
     return renderStill(server.url, target, frame, file, config);
   });
 
-  log.success(`Still frame ${frame} written to ${output}`);
+  log.success(`Frame ${frame} written to ${output}`);
   return output;
 };