@odori/cli 0.0.3 → 0.0.4

package/dist/{chunk-RXLB2CXH.js → chunk-NYXWEZU2.js}

@@ -20,9 +20,9 @@ var log = {
 };
 
 // src/commands/add.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
-import { existsSync as existsSync6 } from "fs";
-import { relative as relative4, resolve as resolve6 } from "path";
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile6 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import { relative as relative5, resolve as resolve7 } from "path";
 import { hashString as hashString2 } from "odori";
 
 // src/config.ts
@@ -86,6 +86,7 @@ var brandFiles = async (config) => {
   return found.sort((left, right) => left.depth - right.depth).map((entry) => entry.file);
 };
 var registerCueInBrand = async (config, cue, componentName) => {
+  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}'`)) {
@@ -93,19 +94,24 @@ var registerCueInBrand = async (config, cue, componentName) => {
     }
     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.export}()`;
     let withCue;
     if (block) {
       const indent = `${block[4]}  `;
       const entry = `
-${indent}"${cue.name}": ${cue.export}(),`;
+${indent}"${cue.name}": ${value},`;
       withCue = source.replace(block[0], `${block[1]}${block[2]}${entry}${block[3]}`);
     } else if (inline) {
       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;
     }
+    if (url) {
+      await writeFile(file, withCue, "utf8");
+      return { file: relative(config.root, file), already: false };
+    }
     const from = resolve2(config.root, config.componentsDir, componentName, componentName);
     const specifier = relative(resolve2(file, ".."), from).split("\\").join("/");
     const importLine = `import {${cue.export}} from "${specifier.startsWith(".") ? specifier : `./${specifier}`}";`;
@@ -288,12 +294,21 @@ var resolveWithinRoot = (root, target) => {
 };
 var DEFAULT_URL = "https://odori.dev/r/v1";
 var registryUrl = (config) => (config.registryUrl ?? process.env.ODORI_REGISTRY ?? DEFAULT_URL).replace(/\/$/, "");
+var registryOrigin = (config) => {
+  const url = registryUrl(config);
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url.replace(/\/r(\/v\d+)?$/, "");
+  }
+};
 var cacheDir = (url) => resolve4(cacheRoot(), "registry", createHash("sha256").update(url).digest("hex").slice(0, 16));
 var toComponent = (item) => ({
   name: item.name,
   namespaced: item.meta?.namespaced ?? `@odori/${item.name}`,
   kind: item.meta?.kind ?? "component",
   ...item.meta?.cue ? { cue: item.meta.cue } : {},
+  ...item.meta?.asset ? { asset: item.meta.asset } : {},
   family: item.meta?.family ?? "Uncategorized",
   description: item.description ?? "",
   files: item.files.map((file) => file.path.split("/").pop() ?? file.path),
@@ -302,7 +317,7 @@ var toComponent = (item) => ({
 });
 var snapshotItems = async () => {
   try {
-    const loaded = await import("./registry-snapshot-BDP6PVYB.js");
+    const loaded = await import("./registry-snapshot-MSH2EA36.js");
     return loaded.default.items;
   } catch {
     throw new Error(
@@ -393,10 +408,66 @@ Nothing was written. This is a truncated download, a stale proxy, or a tampered
   );
 };
 
-// src/commands/update.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+// src/assets.ts
+import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync5 } from "fs";
-import { relative as relative3, resolve as resolve5 } from "path";
+import { mkdir as mkdir3, readFile as readFile4, rm, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname3, relative as relative3, resolve as resolve5 } from "path";
+var assetCache = (integrity) => resolve5(cacheRoot(), "assets", createHash2("sha256").update(integrity).digest("hex").slice(0, 16));
+var verify = (bytes, expected, source) => {
+  const actual = `sha256-${createHash2("sha256").update(bytes).digest("base64")}`;
+  if (actual === expected) return;
+  throw new Error(
+    `The bytes at ${source} do not match the hash the registry published.
+  expected ${expected}
+  received ${actual}
+Nothing was written. This is a truncated download, a stale proxy, or a tampered file.`
+  );
+};
+var installAsset = async (config, component, options = {}) => {
+  const asset = component.asset;
+  if (!asset) return false;
+  const destination = resolveWithinRoot(config.root, asset.target);
+  const exists = existsSync5(destination);
+  log.detail(`  ${exists ? "replace" : "create "} ${relative3(config.root, destination)}`);
+  if (options.dryRun) return false;
+  if (exists && !options.force) {
+    log.warn(`${relative3(config.root, destination)} already exists. Keeping it. Use --force to replace it.`);
+    return true;
+  }
+  const cached = assetCache(asset.integrity);
+  let bytes = null;
+  if (existsSync5(cached)) {
+    const stored = await readFile4(cached);
+    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(3e4) });
+    if (!response.ok) throw new Error(`Could not download ${url}: ${response.status} ${response.statusText}`);
+    const downloaded = new Uint8Array(await response.arrayBuffer());
+    verify(downloaded, asset.integrity, url);
+    await mkdir3(dirname3(cached), { recursive: true });
+    await writeFile4(cached, downloaded);
+    bytes = downloaded;
+  }
+  await mkdir3(dirname3(destination), { recursive: true });
+  await writeFile4(destination, bytes);
+  log.success(`${component.namespaced} to ${relative3(config.root, destination)}`);
+  log.detail(`  ${component.family} \xB7 ${Math.round(asset.bytes / 1024)} KB \xB7 answers to "${asset.cue}"`);
+  return true;
+};
+
+// src/commands/update.ts
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
+import { relative as relative4, resolve as resolve6 } from "path";
 import { hashString } from "odori";
 
 // src/diff.ts
@@ -459,15 +530,15 @@ var formatDiff = (lines, context = 2) => {
 };
 
 // src/commands/update.ts
-var provenanceFile = (config) => resolve5(config.root, config.outDir, "components.json");
+var provenanceFile = (config) => resolve6(config.root, config.outDir, "components.json");
 var readProvenance = async (config) => {
   const file = provenanceFile(config);
-  if (!existsSync5(file)) return {};
-  return JSON.parse(await readFile4(file, "utf8"));
+  if (!existsSync6(file)) return {};
+  return JSON.parse(await readFile5(file, "utf8"));
 };
 var writeProvenance = async (config, provenance) => {
-  await mkdir3(resolve5(config.root, config.outDir), { recursive: true });
-  await writeFile4(provenanceFile(config), `${JSON.stringify(provenance, null, 2)}
+  await mkdir4(resolve6(config.root, config.outDir), { recursive: true });
+  await writeFile5(provenanceFile(config), `${JSON.stringify(provenance, null, 2)}
 `, "utf8");
 };
 var componentStatus = async (config, only) => {
@@ -483,10 +554,10 @@ var componentStatus = async (config, only) => {
     const upstreamFiles = new Map(item.files.map((file) => [file.path.split("/").pop() ?? file.path, file.content]));
     const files = await Promise.all(
       component.files.map(async (file) => {
-        const localPath = resolve5(config.root, config.componentsDir, name, file);
+        const localPath = resolve6(config.root, config.componentsDir, name, file);
         const content = upstreamFiles.get(file);
         if (content === void 0) throw new Error(`The registry document for "${name}" has no file named ${file}.`);
-        const local = existsSync5(localPath) ? hashString(await readFile4(localPath, "utf8")) : null;
+        const local = existsSync6(localPath) ? hashString(await readFile5(localPath, "utf8")) : null;
         return {
           file,
           localPath,
@@ -523,14 +594,14 @@ var diffCommand = async (names, options = {}) => {
     log.title(`@odori/${status.name}  ${LABELS[status.state]}`);
     for (const file of status.files) {
       if (file.local === null) {
-        log.error(`  ${file.file} is missing from ${relative3(config.root, resolve5(file.localPath, ".."))}`);
+        log.error(`  ${file.file} is missing from ${relative4(config.root, resolve6(file.localPath, ".."))}`);
         continue;
       }
       if (file.local === file.upstream) {
         log.detail(`  ${file.file} identical to upstream`);
         continue;
       }
-      const lines = diffLines(await readFile4(file.localPath, "utf8"), file.content);
+      const lines = diffLines(await readFile5(file.localPath, "utf8"), file.content);
       const { added, removed } = countChanges(lines);
       log.info(`  ${file.file}  +${added} -${removed} against upstream`);
       if (options.full) for (const line of formatDiff(lines)) log.detail(`    ${line}`);
@@ -563,8 +634,8 @@ var updateCommand = async (names, options = {}) => {
       continue;
     }
     for (const file of status.files) {
-      await mkdir3(resolve5(file.localPath, ".."), { recursive: true });
-      await writeFile4(file.localPath, file.content, "utf8");
+      await mkdir4(resolve6(file.localPath, ".."), { recursive: true });
+      await writeFile5(file.localPath, file.content, "utf8");
     }
     provenance[status.name] = {
       source: `@odori/${status.name}`,
@@ -604,34 +675,54 @@ var addCommand = async (names, options = {}) => {
       if (provider) queue.push(provider.name);
       else log.warn(`${component.namespaced} needs a "${cue}" cue and no registry entry provides one.`);
     }
+    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;
+    }
     const { item, origin } = await resolveItem(config, component.name);
     verifyIntegrity(item, origin);
-    const target = resolve6(config.root, config.componentsDir, assertSafeName(component.name));
+    const target = resolve7(config.root, config.componentsDir, assertSafeName(component.name));
     const hashes = {};
     for (const file of item.files) {
       const destination = resolveWithinRoot(config.root, file.target);
-      const exists = existsSync6(destination);
-      log.detail(`  ${exists ? "replace" : "create "} ${relative4(config.root, destination)}`);
+      const exists = existsSync7(destination);
+      log.detail(`  ${exists ? "replace" : "create "} ${relative5(config.root, destination)}`);
     }
     if (options.dryRun) {
       installed.push(component.name);
       continue;
     }
-    await mkdir4(target, { recursive: true });
+    await mkdir5(target, { recursive: true });
     for (const file of item.files) {
       const name2 = file.path.split("/").pop() ?? file.path;
       const destination = resolveWithinRoot(config.root, file.target);
       hashes[name2] = hashString2(file.content);
-      if (existsSync6(destination) && !options.force) {
-        const current = hashString2(await readFile5(destination, "utf8"));
+      if (existsSync7(destination) && !options.force) {
+        const current = hashString2(await readFile6(destination, "utf8"));
         const recorded = provenance[component.name]?.hashes[name2];
         if (current !== recorded) {
-          log.warn(`${relative4(config.root, destination)} was modified locally. Keeping your version. Use --force to replace it.`);
+          log.warn(`${relative5(config.root, destination)} was modified locally. Keeping your version. Use --force to replace it.`);
           continue;
         }
       }
-      await mkdir4(resolve6(destination, ".."), { recursive: true });
-      await writeFile5(destination, file.content, "utf8");
+      await mkdir5(resolve7(destination, ".."), { recursive: true });
+      await writeFile6(destination, file.content, "utf8");
     }
     provenance[component.name] = {
       source: component.namespaced,
@@ -640,7 +731,7 @@ var addCommand = async (names, options = {}) => {
       hashes
     };
     installed.push(component.name);
-    log.success(`${component.namespaced} to ${relative4(config.root, target)}/`);
+    log.success(`${component.namespaced} to ${relative5(config.root, target)}/`);
     if (component.kind === "cue" && component.cue) {
       log.detail(
         `  ${component.family} \xB7 ${component.contract.recommendedDurationInFrames} frames \xB7 registers "${component.cue.name}"`
@@ -688,19 +779,19 @@ var registryCommand = async () => {
 };
 
 // src/commands/dev.ts
-import { resolve as resolve18 } from "path";
+import { relative as relative7, resolve as resolve19 } from "path";
 import { homedir as homedir2 } from "os";
-import { existsSync as existsSync15 } from "fs";
-import { readFile as readFile12 } from "fs/promises";
+import { existsSync as existsSync16 } from "fs";
+import { readFile as readFile13 } from "fs/promises";
 
 // src/jobs.ts
-import { mkdir as mkdir5, readFile as readFile6, readdir as readdir2, rename, writeFile as writeFile6 } from "fs/promises";
-import { existsSync as existsSync7 } from "fs";
-import { join as join2, resolve as resolve7 } from "path";
-var buildsDir = (config) => resolve7(config.root, config.outDir, "builds");
+import { mkdir as mkdir6, readFile as readFile7, readdir as readdir2, rename, writeFile as writeFile7 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import { join as join2, resolve as resolve8 } from "path";
+var buildsDir = (config) => resolve8(config.root, config.outDir, "builds");
 var jobFile = (config, id) => join2(buildsDir(config), `${id}.json`);
 var createJob = async (config, manifest, output, render) => {
-  await mkdir5(buildsDir(config), { recursive: true });
+  await mkdir6(buildsDir(config), { recursive: true });
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const job = {
     id: `job-${manifest.manifestHash.slice(0, 10)}-${Date.now().toString(36)}`,
@@ -714,14 +805,14 @@ var createJob = async (config, manifest, output, render) => {
     updatedAt: now
   };
   const record = { job, manifest, output, ...render ? { render } : {} };
-  await writeFile6(jobFile(config, job.id), `${JSON.stringify(record, null, 2)}
+  await writeFile7(jobFile(config, job.id), `${JSON.stringify(record, null, 2)}
 `, "utf8");
   return record;
 };
 var readJob = async (config, id) => {
   const file = jobFile(config, id);
-  if (!existsSync7(file)) throw new Error(`Unknown job "${id}". Run odori jobs to list them.`);
-  return JSON.parse(await readFile6(file, "utf8"));
+  if (!existsSync8(file)) throw new Error(`Unknown job "${id}". Run odori jobs to list them.`);
+  return JSON.parse(await readFile7(file, "utf8"));
 };
 var writeLocks = /* @__PURE__ */ new Map();
 var withJobLock = (id, task) => {
@@ -736,7 +827,7 @@ var withJobLock = (id, task) => {
 var writeRecord = async (config, record) => {
   const file = jobFile(config, record.job.id);
   const temporary = `${file}.${process.pid}.tmp`;
-  await writeFile6(temporary, `${JSON.stringify(record, null, 2)}
+  await writeFile7(temporary, `${JSON.stringify(record, null, 2)}
 `, "utf8");
   await rename(temporary, file);
 };
@@ -779,13 +870,13 @@ var reconcileJobs = async (config) => {
   return stale.length;
 };
 var listJobs = async (config, options = {}) => {
-  if (!existsSync7(buildsDir(config))) return [];
+  if (!existsSync8(buildsDir(config))) return [];
   if (options.reconcile !== false) await reconcileJobs(config);
   const files = (await readdir2(buildsDir(config))).filter((file) => file.endsWith(".json"));
   const jobs = [];
   for (const file of files) {
     try {
-      const raw = await readFile6(join2(buildsDir(config), file), "utf8");
+      const raw = await readFile7(join2(buildsDir(config), file), "utf8");
       jobs.push(JSON.parse(raw).job);
     } catch {
       continue;
@@ -803,9 +894,9 @@ var JobQueue = class {
 };
 
 // src/discovery.ts
-import { mkdir as mkdir6, readdir as readdir3, readFile as readFile7, stat, writeFile as writeFile7 } from "fs/promises";
-import { existsSync as existsSync8 } from "fs";
-import { join as join3, relative as relative5, resolve as resolve8, sep as sep2 } from "path";
+import { mkdir as mkdir7, readdir as readdir3, readFile as readFile8, stat, writeFile as writeFile8 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import { join as join3, relative as relative6, resolve as resolve9, sep as sep2 } from "path";
 import { hashString as hashString3 } from "odori";
 var IGNORED = /* @__PURE__ */ new Set(["node_modules", ".git", ".odori", "out", "dist", ".next"]);
 var walk = async (directory2, files = []) => {
@@ -827,22 +918,22 @@ var toIdentifier = (value, prefix) => {
 };
 var AUDIO_EXTENSIONS = /\.(m4a|mp3|wav|aac|ogg|opus|flac)$/i;
 var discoverAudio = async (config) => {
-  const root = resolve8(config.root, config.audioDir);
-  if (!existsSync8(root)) return [];
-  const publicRoot = resolve8(config.root, "public");
+  const root = resolve9(config.root, config.audioDir);
+  if (!existsSync9(root)) return [];
+  const publicRoot = resolve9(config.root, "public");
   const files = (await walk(root)).filter((file) => AUDIO_EXTENSIONS.test(file)).sort();
   return Promise.all(
     files.map(async (file) => ({
-      name: relative5(root, file).replace(AUDIO_EXTENSIONS, "").split(sep2).join("/"),
-      url: file.startsWith(`${publicRoot}${sep2}`) ? `/${relative5(publicRoot, file).split(sep2).join("/")}` : `/${relative5(config.root, file).split(sep2).join("/")}`,
-      relativeFile: relative5(config.root, file),
+      name: relative6(root, file).replace(AUDIO_EXTENSIONS, "").split(sep2).join("/"),
+      url: file.startsWith(`${publicRoot}${sep2}`) ? `/${relative6(publicRoot, file).split(sep2).join("/")}` : `/${relative6(config.root, file).split(sep2).join("/")}`,
+      relativeFile: relative6(config.root, file),
       bytes: (await stat(file)).size
     }))
   );
 };
 var discoverProject = async (config) => {
-  const videosRoot = resolve8(config.root, config.videosDir);
-  if (!existsSync8(videosRoot)) {
+  const videosRoot = resolve9(config.root, config.videosDir);
+  if (!existsSync9(videosRoot)) {
     throw new Error(`No ${config.videosDir}/ directory found in ${config.root}. Run "odori init" first.`);
   }
   const files = (await walk(videosRoot)).sort();
@@ -850,18 +941,42 @@ var discoverProject = async (config) => {
   const videos = [];
   const previews = [];
   const brands = [];
+  const categories = [];
   const hashParts = [];
-  const componentsRoot = resolve8(config.root, config.componentsDir);
+  const importedBy = {};
+  const componentsRoot = resolve9(config.root, config.componentsDir);
   for (const file of files) {
-    const relativeFile = relative5(config.root, file);
+    const relativeFile = relative6(config.root, file);
     let contents = "";
     if (/\.(tsx|ts|css|json)$/.test(file)) {
-      contents = await readFile7(file, "utf8");
+      contents = await readFile8(file, "utf8");
       hashParts.push(`${relativeFile}:${hashString3(contents)}`);
     }
     const base = file.split(sep2).pop() ?? "";
+    if (base === "category.json") {
+      const path = relative6(componentsRoot, resolve9(file, "..")).split(sep2).join("/");
+      if (!path.startsWith("..")) {
+        try {
+          const declared = JSON.parse(contents);
+          categories.push({
+            path,
+            ...typeof declared.name === "string" ? { name: declared.name } : {},
+            ...typeof declared.order === "number" ? { order: declared.order } : {}
+          });
+        } catch (error) {
+          log.warn(
+            `${relativeFile} is not valid JSON, so that directory names itself: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    }
     if (base === "video.tsx") {
-      const slug = relative5(videosRoot, file).replace(/\/?video\.tsx$/, "").split(sep2).join("/") || "video";
+      for (const match of contents.matchAll(/from\s+["'][^"']*\/components\/([^/"']+)\//g)) {
+        (importedBy[match[1]] ??= /* @__PURE__ */ new Set()).add(relative6(videosRoot, file).replace(/\/?video\.tsx$/, "") || "video");
+      }
+    }
+    if (base === "video.tsx") {
+      const slug = relative6(videosRoot, file).replace(/\/?video\.tsx$/, "").split(sep2).join("/") || "video";
       videos.push({
         slug,
         file,
@@ -887,7 +1002,7 @@ var discoverProject = async (config) => {
         // From the whole relative path, like previews: basenames repeat
         // (`layout.tsx` beside `brands/layout.ts`), identifiers cannot.
         identifier: toIdentifier(
-          `${relative5(videosRoot, file).replace(/\.tsx?$/, "").split(sep2).join("-")}-module`,
+          `${relative6(videosRoot, file).replace(/\.tsx?$/, "").split(sep2).join("-")}-module`,
           "brands"
         )
       });
@@ -898,15 +1013,19 @@ var discoverProject = async (config) => {
         file,
         relativeFile,
         importPath: file,
-        identifier: toIdentifier(`${relative5(videosRoot, file).split(sep2).join("-")}`, "preview")
+        identifier: toIdentifier(`${relative6(videosRoot, file).split(sep2).join("-")}`, "preview")
       });
     }
   }
-  return { videos, previews, brands, audio, sourceHash: hashString3(hashParts.join("|")) };
+  for (const preview of previews) {
+    const users = importedBy[preview.name];
+    if (users) preview.usedBy = [...users].sort();
+  }
+  return { videos, previews, brands, audio, categories, sourceHash: hashString3(hashParts.join("|")) };
 };
 var generateImports = (graph, outDir) => {
   const importPath = (file) => {
-    const relativePath = relative5(outDir, file).split(sep2).join("/");
+    const relativePath = relative6(outDir, file).split(sep2).join("/");
     return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
   };
   const lines = [
@@ -939,17 +1058,21 @@ var generateImports = (graph, outDir) => {
   return lines.join("\n");
 };
 var writeGenerated = async (config, graph) => {
-  const outDir = resolve8(config.root, config.outDir);
-  await mkdir6(outDir, { recursive: true });
+  const outDir = resolve9(config.root, config.outDir);
+  await mkdir7(outDir, { recursive: true });
   const target = join3(outDir, "imports.generated.ts");
-  await writeFile7(target, generateImports(graph, outDir), "utf8");
-  await writeFile7(
+  await writeFile8(target, generateImports(graph, outDir), "utf8");
+  await writeFile8(
     join3(outDir, "catalog.json"),
     `${JSON.stringify(
       {
         sourceHash: graph.sourceHash,
         videos: graph.videos.map((video) => ({ slug: video.slug, file: video.relativeFile })),
-        previews: graph.previews.map((preview) => ({ name: preview.name, file: preview.relativeFile })),
+        previews: graph.previews.map((preview) => ({
+          name: preview.name,
+          file: preview.relativeFile,
+          usedBy: preview.usedBy ?? []
+        })),
         brands: graph.brands.map((brand) => ({ name: brand.name, file: brand.relativeFile })),
         audio: graph.audio.map((entry) => ({ name: entry.name, url: entry.url, file: entry.relativeFile }))
       },
@@ -963,7 +1086,7 @@ var writeGenerated = async (config, graph) => {
 };
 
 // src/project.ts
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   createRenderManifest,
@@ -973,45 +1096,45 @@ import {
 } from "odori";
 
 // src/integrity.ts
-import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync9 } from "fs";
-import { mkdir as mkdir7, readFile as readFile8, writeFile as writeFile8 } from "fs/promises";
-import { dirname as dirname3, resolve as resolve9 } from "path";
-var cacheFile = (config) => resolve9(config.root, config.outDir, "cache", "integrity.json");
+import { createHash as createHash3 } from "crypto";
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir8, readFile as readFile9, writeFile as writeFile9 } from "fs/promises";
+import { dirname as dirname4, resolve as resolve10 } from "path";
+var cacheFile = (config) => resolve10(config.root, config.outDir, "cache", "integrity.json");
 var readCache = async (config) => {
   const file = cacheFile(config);
-  if (!existsSync9(file)) return {};
+  if (!existsSync10(file)) return {};
   try {
-    return JSON.parse(await readFile8(file, "utf8"));
+    return JSON.parse(await readFile9(file, "utf8"));
   } catch {
     return {};
   }
 };
 var writeCache = async (config, cache) => {
   const file = cacheFile(config);
-  await mkdir7(dirname3(file), { recursive: true });
-  await writeFile8(file, `${JSON.stringify(cache, null, 2)}
+  await mkdir8(dirname4(file), { recursive: true });
+  await writeFile9(file, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 };
-var sha256 = (bytes) => `sha256-${createHash2("sha256").update(bytes).digest("base64")}`;
+var sha256 = (bytes) => `sha256-${createHash3("sha256").update(bytes).digest("base64")}`;
 var localCandidates = (config, url) => [
-  resolve9(config.root, "public", url.replace(/^\//, "")),
-  resolve9(config.root, url.replace(/^\//, ""))
+  resolve10(config.root, "public", url.replace(/^\//, "")),
+  resolve10(config.root, url.replace(/^\//, ""))
 ];
-var isServed = (config, file) => file.startsWith(resolve9(config.root, "public") + "/");
+var isServed = (config, file) => file.startsWith(resolve10(config.root, "public") + "/");
 var createIntegrityResolver = async (config) => {
   const cache = await readCache(config);
   const warned = /* @__PURE__ */ new Set();
   let dirty = false;
   const resolveIntegrity = async (url) => {
     if (url.startsWith("/__odori/cue/")) return `cue-${url.slice(url.lastIndexOf("-") + 1).replace(/\.wav$/, "")}`;
-    const local = localCandidates(config, url).find((candidate) => existsSync9(candidate));
+    const local = localCandidates(config, url).find((candidate) => existsSync10(candidate));
     if (local) {
       if (!isServed(config, local) && !warned.has(url)) {
         warned.add(url);
         log.warn(`${url} resolves to ${local}, which is outside public/ and will not be served. Move it into public/.`);
       }
-      const bytes = await readFile8(local);
+      const bytes = await readFile9(local);
       const { mtimeMs } = await import("fs/promises").then((fs) => fs.stat(local));
       const hit = cache[url];
       if (hit && hit.mtimeMs === mtimeMs && hit.size === bytes.byteLength) return hit.integrity;
@@ -1043,9 +1166,9 @@ var createIntegrityResolver = async (config) => {
 };
 
 // src/prepare-cache.ts
-import { existsSync as existsSync10 } from "fs";
-import { mkdir as mkdir8, readFile as readFile9, readdir as readdir4, rm, writeFile as writeFile9 } from "fs/promises";
-import { join as join4, resolve as resolve10 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { mkdir as mkdir9, readFile as readFile10, readdir as readdir4, rm as rm2, writeFile as writeFile10 } from "fs/promises";
+import { join as join4, resolve as resolve11 } from "path";
 import { hashValue } from "odori";
 
 // src/paths.ts
@@ -1053,13 +1176,13 @@ var outputName = (id) => id.split("/").join("-");
 var fileKey = (id) => id.split("/").join("+");
 
 // src/prepare-cache.ts
-var directory = (config) => resolve10(config.root, config.outDir, "cache", "prepare");
+var directory = (config) => resolve11(config.root, config.outDir, "cache", "prepare");
 var prepareCacheKey = (key) => `${fileKey(key.videoId)}__${hashValue(key)}`;
 var readPrepareCache = async (config, key) => {
   const file = join4(directory(config), `${prepareCacheKey(key)}.json`);
-  if (!existsSync10(file)) return { hit: false, value: void 0 };
+  if (!existsSync11(file)) return { hit: false, value: void 0 };
   try {
-    const entry = JSON.parse(await readFile9(file, "utf8"));
+    const entry = JSON.parse(await readFile10(file, "utf8"));
     return { hit: true, value: entry.value };
   } catch {
     return { hit: false, value: void 0 };
@@ -1068,17 +1191,17 @@ var readPrepareCache = async (config, key) => {
 var writePrepareCache = async (config, key, value) => {
   if (value === void 0) return;
   const target = directory(config);
-  await mkdir8(target, { recursive: true });
+  await mkdir9(target, { recursive: true });
   const entry = { key, value, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile9(join4(target, `${prepareCacheKey(key)}.json`), `${JSON.stringify(entry, null, 2)}
+  await writeFile10(join4(target, `${prepareCacheKey(key)}.json`), `${JSON.stringify(entry, null, 2)}
 `, "utf8");
 };
 var clearPrepareCache = async (config, videoId) => {
   const target = directory(config);
-  if (!existsSync10(target)) return 0;
+  if (!existsSync11(target)) return 0;
   const files = await readdir4(target);
   const matches = files.filter((file) => videoId ? file.startsWith(`${fileKey(videoId)}__`) : file.endsWith(".json"));
-  await Promise.all(matches.map((file) => rm(join4(target, file), { force: true })));
+  await Promise.all(matches.map((file) => rm2(join4(target, file), { force: true })));
   return matches.length;
 };
 
@@ -1122,7 +1245,7 @@ var findVideo = (videos, id) => {
   return found;
 };
 var runPrepare = async (video, config, graph, input, options = {}) => {
-  const prepareFile = resolve11(video.file, "..", "prepare.ts");
+  const prepareFile = resolve12(video.file, "..", "prepare.ts");
   let prepare;
   try {
     const module = await import(pathToFileURL2(prepareFile).href);
@@ -1319,20 +1442,20 @@ var alphaWarning = (format, transparent) => transparent && !format.alpha ? `${fo
 
 // src/render.ts
 import { spawn as spawn2 } from "child_process";
-import { copyFile as copyFile2, mkdir as mkdir11, rm as rm2, writeFile as writeFile12 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir12, rm as rm3, writeFile as writeFile13 } from "fs/promises";
 import { cpus } from "os";
-import { dirname as dirname4, join as join6, resolve as resolve15 } from "path";
+import { dirname as dirname5, join as join6, resolve as resolve16 } from "path";
 import { chromium } from "playwright-core";
 
 // src/audio-mix.ts
-import { existsSync as existsSync12 } from "fs";
-import { resolve as resolve13 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { resolve as resolve14 } from "path";
 import { duckEnvelope, envelopeAtFrame } from "odori";
 
 // src/cues.ts
-import { existsSync as existsSync11, statSync } from "fs";
-import { mkdir as mkdir9, writeFile as writeFile10 } from "fs/promises";
-import { basename, resolve as resolve12 } from "path";
+import { existsSync as existsSync12, statSync } from "fs";
+import { mkdir as mkdir10, writeFile as writeFile11 } from "fs/promises";
+import { basename, resolve as resolve13 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 import {
   SAMPLE_RATE,
@@ -1343,8 +1466,8 @@ import {
   isCueDefinition,
   resolveEntryLayout as resolveEntryLayout2
 } from "odori";
-var cueCacheDir = (config) => resolve12(config.root, config.outDir, "cues");
-var cueFile = (config, url) => resolve12(cueCacheDir(config), basename(url));
+var cueCacheDir = (config) => resolve13(config.root, config.outDir, "cues");
+var cueFile = (config, url) => resolve13(cueCacheDir(config), basename(url));
 var materializeCues = async (config, brands, fps) => {
   const seen = /* @__PURE__ */ new Map();
   for (const brand of brands) {
@@ -1353,17 +1476,17 @@ var materializeCues = async (config, brands, fps) => {
     }
   }
   if (seen.size === 0) return [];
-  await mkdir9(cueCacheDir(config), { recursive: true });
+  await mkdir10(cueCacheDir(config), { recursive: true });
   const written = [];
   for (const [url, cue] of seen) {
     const file = cueFile(config, url);
-    if (existsSync11(file)) {
+    if (existsSync12(file)) {
       written.push({ cue, file, rendered: false });
       continue;
     }
     const samples = cueSamples(cue, fps);
     const signal = cue.render({ samples, sampleRate: SAMPLE_RATE });
-    await writeFile10(file, encodeWav(signal));
+    await writeFile11(file, encodeWav(signal));
     written.push({ cue, file, rendered: true });
   }
   return written;
@@ -1421,13 +1544,13 @@ var resolveCueFile = (config, src) => {
   if (/^https?:\/\//.test(src)) return null;
   if (src.startsWith("/__odori/cue/")) {
     const generated = cueFile(config, src);
-    return existsSync12(generated) ? generated : null;
+    return existsSync13(generated) ? generated : null;
   }
   const candidates = [
-    resolve13(config.root, "public", src.replace(/^\//, "")),
-    resolve13(config.root, src.replace(/^\//, ""))
+    resolve14(config.root, "public", src.replace(/^\//, "")),
+    resolve14(config.root, src.replace(/^\//, ""))
   ];
-  return candidates.find((candidate) => existsSync12(candidate)) ?? null;
+  return candidates.find((candidate) => existsSync13(candidate)) ?? null;
 };
 var volumeFilter = (cue, cues, fps) => {
   const authored = cue.gainPoints ?? [];
@@ -1547,11 +1670,11 @@ var planChunks = ({
 var chunkFrames = (chunk) => Array.from({ length: length(chunk) }, (_, offset) => chunk.start + offset);
 
 // src/chunk-cache.ts
-import { existsSync as existsSync13 } from "fs";
-import { copyFile, mkdir as mkdir10, readFile as readFile10, writeFile as writeFile11 } from "fs/promises";
-import { join as join5, resolve as resolve14 } from "path";
+import { existsSync as existsSync14 } from "fs";
+import { copyFile, mkdir as mkdir11, readFile as readFile11, writeFile as writeFile12 } from "fs/promises";
+import { join as join5, resolve as resolve15 } from "path";
 import { hashValue as hashValue2 } from "odori";
-var cacheDir2 = (config) => resolve14(config.root, config.outDir, "cache", "chunks");
+var cacheDir2 = (config) => resolve15(config.root, config.outDir, "cache", "chunks");
 var chunkKey = (identity) => hashValue2({
   videoId: identity.videoId,
   // The browser that drew the frames is part of what the frames are. Without
@@ -1576,9 +1699,9 @@ var chunkKey = (identity) => hashValue2({
 var readChunkRecord = async (config, key) => {
   const meta = join5(cacheDir2(config), `${key}.json`);
   const media = join5(cacheDir2(config), `${key}.mp4`);
-  if (!existsSync13(meta) || !existsSync13(media)) return null;
+  if (!existsSync14(meta) || !existsSync14(media)) return null;
   try {
-    return JSON.parse(await readFile10(meta, "utf8"));
+    return JSON.parse(await readFile11(meta, "utf8"));
   } catch {
     return null;
   }
@@ -1588,10 +1711,10 @@ var useChunkRecord = async (config, key, destination) => {
 };
 var writeChunkRecord = async (config, key, signatures, file) => {
   const directory2 = cacheDir2(config);
-  await mkdir10(directory2, { recursive: true });
+  await mkdir11(directory2, { recursive: true });
   await copyFile(file, join5(directory2, `${key}.mp4`));
   const record = { key, signatures, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile11(join5(directory2, `${key}.json`), `${JSON.stringify(record)}
+  await writeFile12(join5(directory2, `${key}.json`), `${JSON.stringify(record)}
 `, "utf8");
 };
 var signaturesMatch = (recorded, observed) => recorded.length === observed.length && recorded.every((signature, index) => signature === observed[index]);
@@ -1739,7 +1862,7 @@ var ensureFfmpeg = async (config) => {
 var renderStill = async (origin, target, frame, output, config) => {
   const { browser, page, errors } = await openRenderPage(origin, target, config);
   try {
-    await mkdir11(dirname4(output), { recursive: true });
+    await mkdir12(dirname5(output), { recursive: true });
     await seekTo(page, frame);
     await page.screenshot({ path: output });
     if (errors.length > 0) log.warn(`The page reported an error while rendering: ${errors[0]}`);
@@ -1895,8 +2018,8 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
   const chunkFormat = chunkable ? format : LOSSLESS;
   const skipUnchanged = options.skipUnchangedFrames ?? config.skipUnchangedFrames ?? true;
   const cache = options.cache ?? config.cacheChunks ?? true;
-  const work = options.workDir ?? resolve15(config.root, config.outDir, "frames", `${target.videoId.split("/").join("-")}-${Date.now().toString(36)}`);
-  await mkdir11(work, { recursive: true });
+  const work = options.workDir ?? resolve16(config.root, config.outDir, "frames", `${target.videoId.split("/").join("-")}-${Date.now().toString(36)}`);
+  await mkdir12(work, { recursive: true });
   const concurrency = chunkable ? requested : 1;
   const { chunks, lanes } = planChunks({
     durationInFrames: target.durationInFrames,
@@ -1907,7 +2030,7 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
   const stats = { captured: 0, reused: 0, cachedChunks: 0 };
   let succeeded = false;
   try {
-    await mkdir11(dirname4(output), { recursive: true });
+    await mkdir12(dirname5(output), { recursive: true });
     const captureStart = performance.now();
     await Promise.all(
       lanes.map(
@@ -1954,12 +2077,12 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
       await copyFile2(ordered[0], silent);
     } else {
       const list = join6(work, "chunks.txt");
-      await writeFile12(list, ordered.map((file) => `file '${file.split("'").join("'\\''")}'`).join("\n"), "utf8");
+      await writeFile13(list, ordered.map((file) => `file '${file.split("'").join("'\\''")}'`).join("\n"), "utf8");
       await run(ffmpeg, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", silent], options.signal);
     }
     if (!chunkable) {
       const destination = format.name === "png" && !output.includes("%") ? sequencePattern(output) : output;
-      if (destination !== output) await mkdir11(dirname4(destination), { recursive: true });
+      if (destination !== output) await mkdir12(dirname5(destination), { recursive: true });
       await run(ffmpeg, ["-y", "-i", silent, ...format.args(encode), destination], options.signal);
       if (mixInputs.length > 0) {
         log.detail(`${format.name} carries no audio track; ${mixInputs.length} cue(s) were not mixed in.`);
@@ -2013,7 +2136,7 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
     succeeded = true;
     return output;
   } finally {
-    if (succeeded && !options.workDir) await rm2(work, { recursive: true, force: true });
+    if (succeeded && !options.workDir) await rm3(work, { recursive: true, force: true });
     else if (!succeeded) log.detail(`Chunks left for inspection in ${work}`);
   }
 };
@@ -2045,25 +2168,25 @@ var openInBrowser = (url) => {
 };
 
 // src/server.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
 import { createServer } from "vite";
 import react from "@vitejs/plugin-react";
-import { readFile as readFile11 } from "fs/promises";
-import { dirname as dirname5, resolve as resolve16, sep as sep3 } from "path";
-var cliRoot = resolve16(dirname5(fileURLToPath(import.meta.url)), "..");
-var studioRoot = resolve16(cliRoot, "studio");
-var studioEntry = resolve16(studioRoot, "index.html");
-var installRoot = resolve16(cliRoot, "..", "..");
+import { readFile as readFile12 } from "fs/promises";
+import { dirname as dirname6, resolve as resolve17, sep as sep3 } from "path";
+var cliRoot = resolve17(dirname6(fileURLToPath(import.meta.url)), "..");
+var studioRoot = resolve17(cliRoot, "studio");
+var studioEntry = resolve17(studioRoot, "index.html");
+var installRoot = resolve17(cliRoot, "..", "..");
 var VIRTUAL_ID = "virtual:odori-project";
 var RESOLVED_ID = `\0${VIRTUAL_ID}`;
 var runtimeSource = (root) => {
-  for (const from of [resolve16(root, "package.json"), import.meta.url]) {
+  for (const from of [resolve17(root, "package.json"), import.meta.url]) {
     try {
       const manifest = createRequire2(from).resolve("odori/package.json");
-      const src = resolve16(manifest, "..", "src");
-      if (existsSync14(resolve16(src, "index.tsx"))) return src;
+      const src = resolve17(manifest, "..", "src");
+      if (existsSync15(resolve17(src, "index.tsx"))) return src;
     } catch {
     }
   }
@@ -2102,6 +2225,8 @@ var odoriProjectPlugin = (config, getGraph) => ({
       `export const project = ${JSON.stringify({
         root: config.root,
         videosDir: config.videosDir,
+        componentsDir: config.componentsDir,
+        categories: graph.categories,
         exportDir: config.exportDir,
         audioDir: config.audioDir,
         docsUrl: config.docsUrl,
@@ -2110,7 +2235,11 @@ var odoriProjectPlugin = (config, getGraph) => ({
         assets: config.assets ?? [],
         files: {
           videos: graph.videos.map((video) => ({ id: video.slug, file: video.relativeFile })),
-          previews: graph.previews.map((preview) => ({ id: preview.name, file: preview.relativeFile })),
+          previews: graph.previews.map((preview) => ({
+            id: preview.name,
+            file: preview.relativeFile,
+            usedBy: preview.usedBy ?? []
+          })),
           brands: graph.brands.map((brand) => ({ id: brand.name, file: brand.relativeFile }))
         }
       })};`
@@ -2180,15 +2309,15 @@ var startStudioServer = async (initialConfig, options = {}) => {
     ],
     // The project's public/ directory is served at the root, so brand fonts,
     // logos, and footage resolve identically in preview and render.
-    publicDir: existsSync14(resolve16(config.root, "public")) ? resolve16(config.root, "public") : false,
+    publicDir: existsSync15(resolve17(config.root, "public")) ? resolve17(config.root, "public") : false,
     resolve: {
       dedupe: ["react", "react-dom", "odori"],
       // Only when the runtime is present as source. A consumer resolves the
       // published package through its exports map instead.
       alias: odoriSrc ? [
-        { find: /^odori\/preview$/, replacement: resolve16(odoriSrc, "preview.ts") },
-        { find: /^odori\/manifest$/, replacement: resolve16(odoriSrc, "manifest.ts") },
-        { find: /^odori$/, replacement: resolve16(odoriSrc, "index.tsx") }
+        { find: /^odori\/preview$/, replacement: resolve17(odoriSrc, "preview.ts") },
+        { find: /^odori\/manifest$/, replacement: resolve17(odoriSrc, "manifest.ts") },
+        { find: /^odori$/, replacement: resolve17(odoriSrc, "index.tsx") }
       ] : []
     },
     server: {
@@ -2218,7 +2347,7 @@ var startStudioServer = async (initialConfig, options = {}) => {
     }, 150);
   };
   const rediscover = async (file) => {
-    if (!file.startsWith(resolve16(config.root, config.videosDir))) return;
+    if (!file.startsWith(resolve17(config.root, config.videosDir))) return;
     const isEntry = file.endsWith("video.tsx") || file.endsWith(".preview.tsx") || file.includes(`${sep3}brands${sep3}`);
     if (!isEntry) return;
     try {
@@ -2235,7 +2364,7 @@ var startStudioServer = async (initialConfig, options = {}) => {
   };
   vite.watcher.on("add", (file) => void rediscover(file));
   vite.watcher.on("unlink", (file) => void rediscover(file));
-  vite.watcher.add(resolve16(config.root, config.videosDir));
+  vite.watcher.add(resolve17(config.root, config.videosDir));
   const reloadConfig = async (file) => {
     if (!/odori\.config\.(?:ts|mjs|js)$/.test(file)) return;
     try {
@@ -2252,14 +2381,14 @@ var startStudioServer = async (initialConfig, options = {}) => {
     vite.ws.send({ type: "full-reload" });
   };
   const refreshCues = (file) => {
-    if (!file.startsWith(resolve16(config.root, config.videosDir) + sep3)) return;
+    if (!file.startsWith(resolve17(config.root, config.videosDir) + sep3)) return;
     if (!/\.tsx?$/.test(file)) return;
     scheduleCueRefresh();
   };
   vite.watcher.on("change", (file) => refreshCues(file));
   vite.watcher.on("change", (file) => void reloadConfig(file));
   for (const name of ["odori.config.ts", "odori.config.mjs", "odori.config.js"]) {
-    vite.watcher.add(resolve16(config.root, name));
+    vite.watcher.add(resolve17(config.root, name));
   }
   vite.middlewares.use(async (request, response, next) => {
     const url = (request.url ?? "/").split("?")[0];
@@ -2269,7 +2398,7 @@ var startStudioServer = async (initialConfig, options = {}) => {
       return;
     }
     try {
-      const html = await readFile11(studioEntry, "utf8");
+      const html = await readFile12(studioEntry, "utf8");
       response.statusCode = 200;
       response.setHeader("content-type", "text/html");
       response.end(await vite.transformIndexHtml(url, html));
@@ -2290,7 +2419,7 @@ var startStudioServer = async (initialConfig, options = {}) => {
 };
 
 // src/commands/exportVideo.ts
-import { resolve as resolve17 } from "path";
+import { resolve as resolve18 } from "path";
 import { resolveEntryLayout as resolveEntryLayout4 } from "odori";
 
 // src/commands/shared.ts
@@ -2459,7 +2588,7 @@ var exportCommand = async (id, options = {}) => {
         options.input ?? {},
         { scenes: compiled.scenes, audio: compiled.audio }
       );
-      const output = resolve17(
+      const output = resolve18(
         config.root,
         options.output ?? `${config.exportDir}/${outputName(id)}${format.extension}`
       );
@@ -2525,8 +2654,8 @@ var json = (response, status, payload) => {
   response.end(JSON.stringify(payload));
 };
 var exportDestination = (config) => {
-  const downloads = resolve18(homedir2(), "Downloads");
-  return existsSync15(downloads) ? downloads : resolve18(config.root, config.exportDir);
+  const downloads = resolve19(homedir2(), "Downloads");
+  return existsSync16(downloads) ? downloads : resolve19(config.root, config.exportDir);
 };
 var LOOPBACK = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
 var hostOf = (value) => {
@@ -2585,7 +2714,7 @@ var devCommand = async (options = {}) => {
               );
               const frame = Number(body.frame ?? 0);
               const inline = body.inline === true;
-              const file = inline ? resolve18(config.root, config.outDir, `${outputName(video.entry.metadata.id)}-${frame}.png`) : resolve18(exportDestination(config), `${outputName(video.entry.metadata.id)}-${frame}.png`);
+              const file = inline ? resolve19(config.root, config.outDir, `${outputName(video.entry.metadata.id)}-${frame}.png`) : resolve19(exportDestination(config), `${outputName(video.entry.metadata.id)}-${frame}.png`);
               await renderStill(
                 origin,
                 targetFor(
@@ -2601,7 +2730,7 @@ var devCommand = async (options = {}) => {
               if (inline) {
                 response.statusCode = 200;
                 response.setHeader("content-type", "image/png");
-                response.end(await readFile12(file));
+                response.end(await readFile13(file));
                 return;
               }
               json(response, 200, { id: "still", status: "ready", progress: 1, output: file });
@@ -2623,7 +2752,7 @@ var devCommand = async (options = {}) => {
                 input,
                 { scenes: compiled.scenes, audio: compiled.audio }
               );
-              const output = resolve18(
+              const output = resolve19(
                 exportDestination(config),
                 `${outputName(video.entry.metadata.id)}${format.extension}`
               );
@@ -2656,6 +2785,24 @@ var devCommand = async (options = {}) => {
               json(response, 200, (await readJob(config, id)).job);
               return;
             }
+            if (request.method === "GET" && url.startsWith("/source")) {
+              const asked = new URL(url, "http://localhost").searchParams.get("file") ?? "";
+              const file = resolve19(config.root, asked);
+              const inside = relative7(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 readFile13(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;
@@ -2680,16 +2827,16 @@ var devCommand = async (options = {}) => {
 
 // src/commands/doctor.ts
 import { constants } from "fs";
-import { access, mkdir as mkdir12, readFile as readFile13, rm as rm3, writeFile as writeFile13 } from "fs/promises";
-import { existsSync as existsSync16 } from "fs";
+import { access, mkdir as mkdir13, readFile as readFile14, rm as rm4, writeFile as writeFile14 } from "fs/promises";
+import { existsSync as existsSync17 } from "fs";
 import { createRequire as createRequire3 } from "module";
-import { relative as relative6, resolve as resolve19 } from "path";
+import { relative as relative8, resolve as resolve20 } from "path";
 var MINIMUM_NODE = 20;
 var version = (value) => value.replace(/^v/, "").split(".").map(Number);
 var runChecks = async (root) => {
   const checks = [];
   const config = await loadConfig(root);
-  const require2 = createRequire3(resolve19(root, "package.json"));
+  const require2 = createRequire3(resolve20(root, "package.json"));
   const [major] = version(process.version);
   checks.push({
     name: "Node",
@@ -2700,7 +2847,7 @@ var runChecks = async (root) => {
   let react2 = "not found";
   let reactOk = false;
   try {
-    const manifest = JSON.parse(await readFile13(require2.resolve("react/package.json"), "utf8"));
+    const manifest = JSON.parse(await readFile14(require2.resolve("react/package.json"), "utf8"));
     react2 = manifest.version;
     reactOk = version(react2)[0] >= 19;
   } catch {
@@ -2712,16 +2859,16 @@ var runChecks = async (root) => {
     ok: reactOk,
     fix: "The runtime needs React 19. Install it: npm install react@19 react-dom@19"
   });
-  const videosDir = resolve19(config.root, config.videosDir);
+  const videosDir = resolve20(config.root, config.videosDir);
   checks.push({
     name: "Source root",
-    detail: existsSync16(videosDir) ? relative6(config.root, videosDir) + "/" : `no ${config.videosDir}/`,
-    ok: existsSync16(videosDir),
+    detail: existsSync17(videosDir) ? relative8(config.root, videosDir) + "/" : `no ${config.videosDir}/`,
+    ok: existsSync17(videosDir),
     fix: 'Run "odori init" to add the videos source root.'
   });
   checks.push({
     name: "Config",
-    detail: config.configPath ? relative6(config.root, config.configPath) : "defaults (no odori.config.ts)",
+    detail: config.configPath ? relative8(config.root, config.configPath) : "defaults (no odori.config.ts)",
     // Loading got this far, so a config that exists also parsed.
     ok: true
   });
@@ -2747,23 +2894,42 @@ var runChecks = async (root) => {
     detail: unpinned.length === 0 ? `pinned binaries from ${cacheRoot()}` : `${unpinned.length} of 2 from the host; frames may differ from another machine`,
     ok: true
   });
-  const generated = resolve19(config.root, ".odori");
+  const generated = resolve20(config.root, ".odori");
   let writable = false;
   try {
-    await mkdir12(generated, { recursive: true });
-    const probe = resolve19(generated, ".doctor");
-    await writeFile13(probe, "", "utf8");
+    await mkdir13(generated, { recursive: true });
+    const probe = resolve20(generated, ".doctor");
+    await writeFile14(probe, "", "utf8");
     await access(probe, constants.W_OK);
-    await rm3(probe, { force: true });
+    await rm4(probe, { force: true });
     writable = true;
   } catch {
     writable = false;
   }
+  const componentsRoot = resolve20(root, config.componentsDir);
+  const orphans = [];
+  if (existsSync17(componentsRoot)) {
+    const { readdir: readdir8 } = await import("fs/promises");
+    for (const entry of await readdir8(componentsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const files = await readdir8(resolve20(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 ? ", \u2026" : ""}`,
+    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",
     ok: writable,
-    fix: `Odori writes its import graph and render cache to ${relative6(process.cwd(), generated) || ".odori"}. Check the directory's permissions.`
+    fix: `Odori writes its import graph and render cache to ${relative8(process.cwd(), generated) || ".odori"}. Check the directory's permissions.`
   });
   return checks;
 };
@@ -2773,12 +2939,15 @@ var doctorCommand = async (root = process.cwd()) => {
   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.");
+    for (const check of warned) log.detail(`  ${check.fix}`);
     return 0;
   }
   log.info("");
@@ -2787,14 +2956,14 @@ var doctorCommand = async (root = process.cwd()) => {
 };
 
 // src/commands/init.ts
-import { mkdir as mkdir14, writeFile as writeFile15 } from "fs/promises";
-import { existsSync as existsSync18 } from "fs";
-import { relative as relative8, resolve as resolve21 } from "path";
+import { mkdir as mkdir15, writeFile as writeFile16 } from "fs/promises";
+import { existsSync as existsSync19 } from "fs";
+import { relative as relative10, resolve as resolve22 } from "path";
 
 // src/commands/new.ts
-import { mkdir as mkdir13, readdir as readdir5, writeFile as writeFile14 } from "fs/promises";
-import { existsSync as existsSync17 } from "fs";
-import { relative as relative7, resolve as resolve20 } from "path";
+import { mkdir as mkdir14, readdir as readdir5, writeFile as writeFile15 } from "fs/promises";
+import { existsSync as existsSync18 } from "fs";
+import { relative as relative9, resolve as resolve21 } from "path";
 var titleCase = (value) => value.split(/[-_\s]+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 var pascalCase = (value) => titleCase(value).replace(/\s+/g, "");
 var videoTemplate = (name, hasLayout) => `import {Scene, Video, defineVideoMetadata} from "odori";
@@ -2852,27 +3021,27 @@ ${closing}
 `;
 };
 var installedParts = async (config) => {
-  const componentsDir = resolve20(config.root, config.componentsDir);
-  if (!existsSync17(componentsDir)) return { title: false, end: false };
+  const componentsDir = resolve21(config.root, config.componentsDir);
+  if (!existsSync18(componentsDir)) return { title: false, end: false };
   const entries = (await readdir5(componentsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   return { title: entries.includes("title-reveal"), end: entries.includes("end-card") };
 };
 var newCommand = async (name, options = {}) => {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error("Use a lowercase, dash separated name.");
   const config = await loadConfig(process.cwd());
-  const directory2 = resolve20(config.root, config.videosDir, name);
-  const file = resolve20(directory2, "video.tsx");
-  if (existsSync17(file)) throw new Error(`${relative7(config.root, file)} already exists.`);
-  const hasLayout = existsSync17(resolve20(config.root, config.videosDir, "layout.tsx"));
+  const directory2 = resolve21(config.root, config.videosDir, name);
+  const file = resolve21(directory2, "video.tsx");
+  if (existsSync18(file)) throw new Error(`${relative9(config.root, file)} already exists.`);
+  const hasLayout = existsSync18(resolve21(config.root, config.videosDir, "layout.tsx"));
   const parts = options.blank === true ? { title: false, end: false } : await installedParts(config);
   const composed = parts.title || parts.end;
-  await mkdir13(directory2, { recursive: true });
-  await writeFile14(
+  await mkdir14(directory2, { recursive: true });
+  await writeFile15(
     file,
     composed ? composedTemplate(name, hasLayout, parts) : videoTemplate(name, hasLayout),
     "utf8"
   );
-  log.success(`Created ${relative7(config.root, file)}`);
+  log.success(`Created ${relative9(config.root, file)}`);
   if (composed) log.detail("Composed from the components this project has installed.");
   else if (options.blank !== true) {
     log.detail("No registry components installed yet: odori add title-reveal end-card");
@@ -2906,21 +3075,21 @@ export const productLayout = defineVideoLayout({
 });
 `;
 var initCommand = async (root = process.cwd()) => {
-  const videosDir = resolve21(root, defaultConfig.videosDir);
-  await mkdir14(resolve21(videosDir, "components"), { recursive: true });
+  const videosDir = resolve22(root, defaultConfig.videosDir);
+  await mkdir15(resolve22(videosDir, "components"), { recursive: true });
   const files = [
-    [resolve21(root, "odori.config.ts"), CONFIG_TEMPLATE],
-    [resolve21(videosDir, "layout.tsx"), LAYOUT_TEMPLATE],
-    [resolve21(videosDir, "launch", "video.tsx"), videoTemplate("launch", true)]
+    [resolve22(root, "odori.config.ts"), CONFIG_TEMPLATE],
+    [resolve22(videosDir, "layout.tsx"), LAYOUT_TEMPLATE],
+    [resolve22(videosDir, "launch", "video.tsx"), videoTemplate("launch", true)]
   ];
   for (const [file, contents] of files) {
-    if (existsSync18(file)) {
-      log.detail(`Kept existing ${relative8(root, file)}`);
+    if (existsSync19(file)) {
+      log.detail(`Kept existing ${relative10(root, file)}`);
       continue;
     }
-    await mkdir14(resolve21(file, ".."), { recursive: true });
-    await writeFile15(file, contents, "utf8");
-    log.success(`Created ${relative8(root, file)}`);
+    await mkdir15(resolve22(file, ".."), { recursive: true });
+    await writeFile16(file, contents, "utf8");
+    log.success(`Created ${relative10(root, file)}`);
   }
   log.detail("Next: odori doctor, then odori add title-reveal end-card, then odori dev.");
 };
@@ -3011,15 +3180,16 @@ var listCommand = async () => {
   }
 };
 
-// src/commands/still.ts
-import { resolve as resolve22 } from "path";
-var stillCommand = async (id, options = {}) => {
-  const frame = options.frame ?? 0;
-  if (!Number.isInteger(frame) || frame < 0) {
-    throw new Error(`Frame must be a whole number of frames from the start, got ${String(frame)}.`);
-  }
+// src/commands/frame.ts
+import { resolve as resolve23 } from "path";
+import { framesFromOffset, resolveEntryLayout as resolveEntryLayout7 } from "odori";
+var frameCommand = async (id, options = {}) => {
+  const at = options.at ?? 0;
+  framesFromOffset(at, 30);
   const { config, graph, videos } = await createContext();
   const video = findVideo(videos, id);
+  const fps = resolveEntryLayout7(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(
@@ -3033,21 +3203,21 @@ var stillCommand = async (id, options = {}) => {
       throw new Error(`Frame ${frame} is past the last frame (${manifest.format.durationInFrames - 1}).`);
     }
     const target = targetFor({ ...video, durationInFrames: manifest.format.durationInFrames }, input, prepared);
-    const file = resolve22(config.root, options.output ?? `${config.exportDir}/${outputName(id)}-${frame}.png`);
+    const file = resolve23(config.root, options.output ?? `${config.exportDir}/${outputName(id)}-${frame}.png`);
     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;
 };
 
 // src/commands/test.ts
-import { isOdoriSchema as isOdoriSchema2, resolveEntryLayout as resolveEntryLayout8 } from "odori";
+import { isOdoriSchema as isOdoriSchema2, resolveEntryLayout as resolveEntryLayout9 } from "odori";
 
 // src/contracts.ts
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { readdir as readdir6 } from "fs/promises";
-import { resolve as resolve23 } from "path";
-import { cueUrl as cueUrl2, isCueDefinition as isCueDefinition2, resolveEntryLayout as resolveEntryLayout7 } from "odori";
+import { resolve as resolve24 } from "path";
+import { cueUrl as cueUrl2, isCueDefinition as isCueDefinition2, resolveEntryLayout as resolveEntryLayout8 } from "odori";
 var primaryFamily = (stack) => (stack.split(",")[0] ?? "").trim().replace(/^["']|["']$/g, "");
 var SYSTEM_FAMILIES = /* @__PURE__ */ new Set([
   "system-ui",
@@ -3113,8 +3283,8 @@ var checkAudioWindows = (cues, brand, videoId) => {
   return failures;
 };
 var checkInstalledContracts = async (config, videos) => {
-  const componentsDir = resolve23(config.root, config.componentsDir);
-  const onDisk = existsSync19(componentsDir) ? (await readdir6(componentsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
+  const componentsDir = resolve24(config.root, config.componentsDir);
+  const onDisk = existsSync20(componentsDir) ? (await readdir6(componentsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
   const names = /* @__PURE__ */ new Set([...Object.keys(await readProvenance(config)), ...onDisk]);
   if (names.size === 0) return [];
   const { items } = await resolveRegistry(config, { allowNetwork: false });
@@ -3123,7 +3293,7 @@ var checkInstalledContracts = async (config, videos) => {
   const seen = /* @__PURE__ */ new Set();
   const failures = [];
   for (const video of videos) {
-    const { brand } = resolveEntryLayout7(video.entry);
+    const { brand } = resolveEntryLayout8(video.entry);
     for (const failure of checkComponentRequirements(installed, brand, video.entry.metadata.id)) {
       const key = `${brand.name}:${failure.message}`;
       if (seen.has(key)) continue;
@@ -3135,9 +3305,9 @@ var checkInstalledContracts = async (config, videos) => {
 };
 
 // src/determinism.ts
-import { readdir as readdir7, readFile as readFile14 } from "fs/promises";
-import { existsSync as existsSync20 } from "fs";
-import { join as join7, relative as relative9, resolve as resolve24 } from "path";
+import { readdir as readdir7, readFile as readFile15 } from "fs/promises";
+import { existsSync as existsSync21 } from "fs";
+import { join as join7, relative as relative11, resolve as resolve25 } from "path";
 var FORBIDDEN = [
   {
     pattern: /\bMath\.random\s*\(/,
@@ -3178,11 +3348,11 @@ var walk2 = async (directory2, files = []) => {
   return files;
 };
 var checkDeterminism = async (config) => {
-  const root = resolve24(config.root, config.videosDir);
-  if (!existsSync20(root)) return [];
+  const root = resolve25(config.root, config.videosDir);
+  if (!existsSync21(root)) return [];
   const files = await walk2(root);
   const findings = await Promise.all(
-    files.map(async (file) => scanSource(await readFile14(file, "utf8"), relative9(config.root, file)))
+    files.map(async (file) => scanSource(await readFile15(file, "utf8"), relative11(config.root, file)))
   );
   return findings.flat();
 };
@@ -3281,7 +3451,7 @@ var FRAME_SCRIPT = `(() => {
 })()`;
 var testVideo = async (origin, video, config, failures, quiet = false) => {
   const id = video.entry.metadata.id;
-  const layout = resolveEntryLayout8(video.entry);
+  const layout = resolveEntryLayout9(video.entry);
   if (isOdoriSchema2(video.entry.metadata.schema)) {
     const result = video.entry.metadata.schema.safeParse(video.entry.metadata.defaultProps ?? {});
     if (!result.success) failures.push({ video: id, message: `defaultProps fail the schema: ${result.issues.join("; ")}` });
@@ -3446,7 +3616,7 @@ var COMMAND_FLAGS = {
   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"],
   jobs: [],
@@ -3509,8 +3679,9 @@ var USAGE = {
   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.`,
@@ -3538,14 +3709,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
@@ -3622,9 +3793,11 @@ var run2 = async (argv) => {
       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 : void 0,
           input: parseInput(flags)
         });
@@ -3729,7 +3902,7 @@ export {
   exportCommand,
   jobsCommand,
   devCommand,
-  stillCommand,
+  frameCommand,
   diffLines,
   countChanges,
   formatDiff,