@odori/cli 0.0.2 → 0.0.4

package/dist/{chunk-7XJL2BYO.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 relative3, 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}`}";`;
@@ -121,7 +127,7 @@ ${indent}"${cue.name}": ${cue.export}(),`;
 import { createHash } from "crypto";
 import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname2, resolve as resolve4 } from "path";
+import { dirname as dirname2, isAbsolute, relative as relative2, resolve as resolve4, sep } from "path";
 
 // src/binaries.ts
 import { spawn } from "child_process";
@@ -268,14 +274,41 @@ var installCommand = async () => {
 
 // src/registry-source.ts
 var normalizeComponentName = (name) => name.replace(/^@odori\//, "");
+var assertSafeName = (name) => {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    throw new Error(
+      `Refusing component name ${JSON.stringify(name)}: a name must be a lowercase slug (letters, digits, and single dashes). This registry is malformed or tampered with.`
+    );
+  }
+  return name;
+};
+var resolveWithinRoot = (root, target) => {
+  const destination = resolve4(root, target);
+  const rel = relative2(root, destination);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(
+      `Refusing to write ${JSON.stringify(target)}: it resolves outside the project. Nothing was written.`
+    );
+  }
+  return destination;
+};
 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),
@@ -284,7 +317,7 @@ var toComponent = (item) => ({
 });
 var snapshotItems = async () => {
   try {
-    const loaded = await import("./registry-snapshot-NIH2JMQ6.js");
+    const loaded = await import("./registry-snapshot-MSH2EA36.js");
     return loaded.default.items;
   } catch {
     throw new Error(
@@ -327,6 +360,7 @@ var resolveRegistry = async (config, options = {}) => {
   return { items: await bundled(), origin: "bundled", detail: "the copy built into this CLI" };
 };
 var resolveItem = async (config, name, options = {}) => {
+  assertSafeName(name);
   const url = registryUrl(config);
   const cache = resolve4(cacheDir(url), `${name}.json`);
   if (options.allowNetwork !== false) {
@@ -349,9 +383,14 @@ var resolveItem = async (config, name, options = {}) => {
   if (!item) throw new Error(`No component named "${name}" in the registry at ${url}, in the cache, or in this CLI.`);
   return { item, origin: "bundled" };
 };
-var verifyIntegrity = (item) => {
+var verifyIntegrity = (item, origin = "network") => {
   const expected = item.meta?.integrity;
-  if (!expected) return;
+  if (!expected) {
+    if (origin === "bundled") return;
+    throw new Error(
+      `The registry document for "${item.name}" carries no integrity hash. A fetched item must be verifiable; refusing to write it. Nothing was written.`
+    );
+  }
   const hash = createHash("sha256");
   for (const file of [...item.files].sort((left, right) => left.path.localeCompare(right.path))) {
     hash.update(file.path);
@@ -369,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 relative2, 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
@@ -435,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) => {
@@ -459,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,
@@ -499,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 ${relative2(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}`);
@@ -539,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}`,
@@ -557,7 +652,7 @@ var updateCommand = async (names, options = {}) => {
 
 // src/commands/add.ts
 var addCommand = async (names, options = {}) => {
-  if (names.length === 0) throw new Error("Name at least one component, for example @odori/title-reveal.");
+  if (names.length === 0) throw new Error("Name at least one component, for example title-reveal.");
   const config = await loadConfig(process.cwd());
   const source = await resolveRegistry(config);
   const registry = source.items;
@@ -580,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.`);
     }
-    const { item } = await resolveItem(config, component.name);
-    verifyIntegrity(item);
-    const target = resolve6(config.root, config.componentsDir, component.name);
+    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 = resolve7(config.root, config.componentsDir, assertSafeName(component.name));
     const hashes = {};
     for (const file of item.files) {
-      const destination = resolve6(config.root, file.target);
-      const exists = existsSync6(destination);
-      log.detail(`  ${exists ? "replace" : "create "} ${relative3(config.root, destination)}`);
+      const destination = resolveWithinRoot(config.root, file.target);
+      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 = resolve6(config.root, file.target);
+      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(`${relative3(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,
@@ -616,7 +731,7 @@ var addCommand = async (names, options = {}) => {
       hashes
     };
     installed.push(component.name);
-    log.success(`${component.namespaced} to ${relative3(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}"`
@@ -664,17 +779,19 @@ var registryCommand = async () => {
 };
 
 // src/commands/dev.ts
-import { resolve as resolve18 } from "path";
-import { readFile as readFile12 } from "fs/promises";
+import { relative as relative7, resolve as resolve19 } from "path";
+import { homedir as homedir2 } from "os";
+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) => {
-  await mkdir5(buildsDir(config), { recursive: true });
+var createJob = async (config, manifest, output, render) => {
+  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)}`,
@@ -687,15 +804,15 @@ var createJob = async (config, manifest, output) => {
     createdAt: now,
     updatedAt: now
   };
-  const record = { job, manifest, output };
-  await writeFile6(jobFile(config, job.id), `${JSON.stringify(record, null, 2)}
+  const record = { job, manifest, output, ...render ? { render } : {} };
+  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) => {
@@ -710,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);
 };
@@ -753,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;
@@ -777,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 relative4, resolve as resolve8, sep } 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 = []) => {
@@ -801,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: relative4(root, file).replace(AUDIO_EXTENSIONS, "").split(sep).join("/"),
-      url: file.startsWith(`${publicRoot}${sep}`) ? `/${relative4(publicRoot, file).split(sep).join("/")}` : `/${relative4(config.root, file).split(sep).join("/")}`,
-      relativeFile: relative4(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();
@@ -824,16 +941,42 @@ var discoverProject = async (config) => {
   const videos = [];
   const previews = [];
   const brands = [];
+  const categories = [];
   const hashParts = [];
+  const importedBy = {};
+  const componentsRoot = resolve9(config.root, config.componentsDir);
   for (const file of files) {
-    const relativeFile = relative4(config.root, file);
+    const relativeFile = relative6(config.root, file);
+    let contents = "";
     if (/\.(tsx|ts|css|json)$/.test(file)) {
-      const contents = await readFile7(file, "utf8");
+      contents = await readFile8(file, "utf8");
       hashParts.push(`${relativeFile}:${hashString3(contents)}`);
     }
-    const base = file.split(sep).pop() ?? "";
+    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") {
+      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 = relative4(videosRoot, file).replace(/\/?video\.tsx$/, "").split(sep).join("/") || "video";
+      const slug = relative6(videosRoot, file).replace(/\/?video\.tsx$/, "").split(sep2).join("/") || "video";
       videos.push({
         slug,
         file,
@@ -841,13 +984,27 @@ var discoverProject = async (config) => {
         importPath: file,
         identifier: toIdentifier(slug, "video")
       });
-    } else if (file.split(sep).includes("brands") && /\.tsx?$/.test(base) && !base.endsWith(".preview.tsx")) {
+    } else if (
+      // A brand module is recognized by what it does, not where it sits. The
+      // scaffold defines its brand in videos/layout.tsx, so a directory-name
+      // rule alone left the default project's brand invisible to everything
+      // that reads this list — most visibly the dev server's cue registry,
+      // which then answered new cue URLs with 404s until a restart. Installed
+      // component source is excluded the way brand-file.ts excludes it: a
+      // component may mention defineBrand without being where a brand lives.
+      /\.tsx?$/.test(base) && !base.endsWith(".preview.tsx") && !file.startsWith(componentsRoot + sep2) && (file.split(sep2).includes("brands") || contents.includes("defineBrand("))
+    ) {
       const name = base.replace(/\.tsx?$/, "");
       brands.push({
         name,
         file,
         relativeFile,
-        identifier: toIdentifier(`${name}-module`, "brands")
+        // From the whole relative path, like previews: basenames repeat
+        // (`layout.tsx` beside `brands/layout.ts`), identifiers cannot.
+        identifier: toIdentifier(
+          `${relative6(videosRoot, file).replace(/\.tsx?$/, "").split(sep2).join("-")}-module`,
+          "brands"
+        )
       });
     } else if (base.endsWith(".preview.tsx")) {
       const name = base.replace(/\.preview\.tsx$/, "");
@@ -856,15 +1013,19 @@ var discoverProject = async (config) => {
         file,
         relativeFile,
         importPath: file,
-        identifier: toIdentifier(`${relative4(videosRoot, file).split(sep).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 = relative4(outDir, file).split(sep).join("/");
+    const relativePath = relative6(outDir, file).split(sep2).join("/");
     return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
   };
   const lines = [
@@ -897,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 }))
       },
@@ -921,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,
@@ -931,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;
@@ -1001,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
@@ -1011,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 };
@@ -1026,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;
 };
 
@@ -1080,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);
@@ -1162,22 +1327,135 @@ var freezeManifest = async (video, graph, config, rawInput, options = {}) => {
   return { manifest, input, prepared };
 };
 
+// src/formats.ts
+var QUALITIES = ["studio", "social", "web"];
+var scaleFilter = (scale) => `scale=trunc(iw*${scale}/2)*2:trunc(ih*${scale}/2)*2:flags=lanczos`;
+var scaleArgs = (scale) => scale === 1 ? [] : ["-vf", scaleFilter(scale)];
+var FORMATS = {
+  mp4: {
+    name: "mp4",
+    extension: ".mp4",
+    alpha: false,
+    chunked: true,
+    audio: true,
+    description: "H.264 in MP4. Plays everywhere; the default.",
+    args: ({ preset, quality, scale }) => [
+      ...scaleArgs(scale),
+      "-c:v",
+      "libx264",
+      "-crf",
+      { studio: "17", social: "21", web: "27" }[quality],
+      "-preset",
+      preset,
+      "-pix_fmt",
+      "yuv420p"
+    ]
+  },
+  webm: {
+    name: "webm",
+    extension: ".webm",
+    alpha: true,
+    // VP9 in WebM concatenates cleanly through the demuxer, same as H.264.
+    chunked: true,
+    audio: true,
+    description: "VP9 in WebM, with alpha. For the web, and for overlays.",
+    args: ({ quality, scale }) => [
+      ...scaleArgs(scale),
+      "-c:v",
+      "libvpx-vp9",
+      "-crf",
+      { studio: "24", social: "31", web: "38" }[quality],
+      "-b:v",
+      "0",
+      "-pix_fmt",
+      "yuva420p",
+      "-row-mt",
+      "1"
+    ]
+  },
+  prores: {
+    name: "prores",
+    extension: ".mov",
+    alpha: true,
+    chunked: true,
+    audio: true,
+    description: "ProRes 4444 in MOV, with alpha. For handing to an editor.",
+    // Quality is the profile here, and the profile is the point: an editor
+    // format that quietly compressed would defeat its own reason to exist.
+    args: ({ scale }) => [
+      ...scaleArgs(scale),
+      "-c:v",
+      "prores_ks",
+      "-profile:v",
+      "4444",
+      "-pix_fmt",
+      "yuva444p10le",
+      "-alpha_bits",
+      "8"
+    ]
+  },
+  gif: {
+    name: "gif",
+    extension: ".gif",
+    alpha: false,
+    // A GIF's palette is computed across the whole animation, so chunks would
+    // each invent their own and the result would flicker between them.
+    chunked: false,
+    audio: false,
+    description: "An animated GIF, palette optimised. Silent, by the format.",
+    // The palette pass is a filter graph already, so scaling joins it rather
+    // than adding a second -vf that ffmpeg would silently drop.
+    args: ({ scale }) => [
+      "-vf",
+      `${scale === 1 ? "" : `${scaleFilter(scale)},`}split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3`,
+      "-loop",
+      "0"
+    ]
+  },
+  png: {
+    name: "png",
+    extension: ".png",
+    alpha: true,
+    chunked: false,
+    audio: false,
+    description: "A numbered PNG sequence, with alpha. For a compositor.",
+    args: ({ scale }) => [...scaleArgs(scale), "-c:v", "png", "-pix_fmt", "rgba"]
+  }
+};
+var formatNames = () => Object.keys(FORMATS);
+var resolveFormat = (requested, output) => {
+  if (requested) {
+    const format = FORMATS[requested.toLowerCase()];
+    if (!format) {
+      throw new Error(`Unknown format "${requested}". Available: ${formatNames().join(", ")}`);
+    }
+    return format;
+  }
+  if (output) {
+    const extension = output.slice(output.lastIndexOf(".")).toLowerCase();
+    const matched = Object.values(FORMATS).find((format) => format.extension === extension);
+    if (matched) return matched;
+  }
+  return FORMATS.mp4;
+};
+var alphaWarning = (format, transparent) => transparent && !format.alpha ? `${format.name} has no alpha channel, so the transparent background will render black. Use webm, prores, or png.` : null;
+
 // 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,
@@ -1188,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) {
@@ -1198,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;
@@ -1234,23 +1512,28 @@ var renderedCue = (url) => {
   return wav;
 };
 var isBrand = (value) => typeof value === "object" && value !== null && value.kind === "odori-brand";
+var isLayout = (value) => typeof value === "object" && value !== null && value.kind === "odori-layout";
 var importFresh = async (file) => await import(`${pathToFileURL3(file).href}?odori=${statSync(file).mtimeMs}`);
-var registerProjectCues = async (graph) => {
+var registerProjectCues = async (graph, load = importFresh) => {
   for (const discovered of graph.brands) {
     try {
-      const module = await importFresh(discovered.file);
-      registerCues(Object.values(module).filter(isBrand), defaultLayout.format.fps);
+      const values = Object.values(await load(discovered.file));
+      registerCues(values.filter(isBrand), defaultLayout.format.fps);
+      for (const layout of values.filter(isLayout)) registerCues([layout.brand], layout.format.fps);
     } catch (error) {
       log.warn(`[odori] could not read cues from ${discovered.relativeFile}: ${message(error)}`);
     }
   }
-  try {
-    for (const video of await loadVideos(graph)) {
-      const layout = resolveEntryLayout2(video.entry);
+  for (const video of graph.videos) {
+    try {
+      const module = await load(video.file);
+      if (!module.default || !module.metadata) continue;
+      const entry = { component: module.default, metadata: module.metadata };
+      const layout = resolveEntryLayout2(entry);
       registerCues([layout.brand], layout.format.fps);
+    } catch (error) {
+      log.warn(`[odori] generated cues in ${video.relativeFile} may use the default frame rate: ${message(error)}`);
     }
-  } catch (error) {
-    log.warn(`[odori] generated cues may use the default frame rate: ${message(error)}`);
   }
   return known.size;
 };
@@ -1261,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 ?? [];
@@ -1387,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
@@ -1409,14 +1692,16 @@ var chunkKey = (identity) => hashValue2({
   height: identity.height,
   fps: identity.fps,
   preset: identity.preset,
+  quality: identity.quality ?? null,
+  scale: identity.scale ?? null,
   input: identity.input ?? null
 });
 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;
   }
@@ -1426,88 +1711,14 @@ 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]);
 
-// src/formats.ts
-var FORMATS = {
-  mp4: {
-    name: "mp4",
-    extension: ".mp4",
-    alpha: false,
-    chunked: true,
-    audio: true,
-    description: "H.264 in MP4. Plays everywhere; the default.",
-    args: (preset) => ["-c:v", "libx264", "-crf", "17", "-preset", preset, "-pix_fmt", "yuv420p"]
-  },
-  webm: {
-    name: "webm",
-    extension: ".webm",
-    alpha: true,
-    // VP9 in WebM concatenates cleanly through the demuxer, same as H.264.
-    chunked: true,
-    audio: true,
-    description: "VP9 in WebM, with alpha. For the web, and for overlays.",
-    args: () => ["-c:v", "libvpx-vp9", "-crf", "24", "-b:v", "0", "-pix_fmt", "yuva420p", "-row-mt", "1"]
-  },
-  prores: {
-    name: "prores",
-    extension: ".mov",
-    alpha: true,
-    chunked: true,
-    audio: true,
-    description: "ProRes 4444 in MOV, with alpha. For handing to an editor.",
-    args: () => ["-c:v", "prores_ks", "-profile:v", "4444", "-pix_fmt", "yuva444p10le", "-alpha_bits", "8"]
-  },
-  gif: {
-    name: "gif",
-    extension: ".gif",
-    alpha: false,
-    // A GIF's palette is computed across the whole animation, so chunks would
-    // each invent their own and the result would flicker between them.
-    chunked: false,
-    audio: false,
-    description: "An animated GIF, palette optimised. Silent, by the format.",
-    args: () => [
-      "-vf",
-      "split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3",
-      "-loop",
-      "0"
-    ]
-  },
-  png: {
-    name: "png",
-    extension: ".png",
-    alpha: true,
-    chunked: false,
-    audio: false,
-    description: "A numbered PNG sequence, with alpha. For a compositor.",
-    args: () => ["-c:v", "png", "-pix_fmt", "rgba"]
-  }
-};
-var formatNames = () => Object.keys(FORMATS);
-var resolveFormat = (requested, output) => {
-  if (requested) {
-    const format = FORMATS[requested.toLowerCase()];
-    if (!format) {
-      throw new Error(`Unknown format "${requested}". Available: ${formatNames().join(", ")}`);
-    }
-    return format;
-  }
-  if (output) {
-    const extension = output.slice(output.lastIndexOf(".")).toLowerCase();
-    const matched = Object.values(FORMATS).find((format) => format.extension === extension);
-    if (matched) return matched;
-  }
-  return FORMATS.mp4;
-};
-var alphaWarning = (format, transparent) => transparent && !format.alpha ? `${format.name} has no alpha channel, so the transparent background will render black. Use webm, prores, or png.` : null;
-
 // src/render.ts
 var encodeParam = (value) => Buffer.from(JSON.stringify(value), "utf8").toString("base64");
 var renderUrl = (origin, target, frame) => {
@@ -1651,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]}`);
@@ -1675,10 +1886,19 @@ var sequencePattern = (output) => {
   const extension = dot > 0 ? output.slice(dot) : ".png";
   return join6(stem, `%05d${extension}`);
 };
-var openChunkEncoder = (ffmpeg, file, fps, preset, format, signal) => {
+var LOSSLESS = {
+  name: "lossless",
+  extension: ".mkv",
+  alpha: true,
+  chunked: true,
+  audio: false,
+  description: "FFV1 in MKV, the lossless intermediate for one-pass formats.",
+  args: () => ["-c:v", "ffv1", "-level", "3"]
+};
+var openChunkEncoder = (ffmpeg, file, fps, encode, format, signal) => {
   const child = spawn2(
     ffmpeg,
-    ["-y", "-f", "image2pipe", "-framerate", String(fps), "-i", "pipe:0", ...format.args(preset), file],
+    ["-y", "-f", "image2pipe", "-framerate", String(fps), "-i", "pipe:0", ...format.args(encode), file],
     { stdio: ["pipe", "ignore", "pipe"] }
   );
   let stderr = "";
@@ -1728,7 +1948,7 @@ var captureLane = async (origin, target, config, lane, stats, options) => {
         }
       }
       const file = options.chunkFile(chunk);
-      const encoder = openChunkEncoder(options.ffmpeg, file, target.fps, options.preset, options.format, options.signal);
+      const encoder = openChunkEncoder(options.ffmpeg, file, target.fps, options.encode, options.format, options.signal);
       const signatures = [];
       let previousSignature = null;
       let previousFrame = null;
@@ -1788,13 +2008,18 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
   const browserPath = await browserExecutable(config);
   const renderer = (await resolveBrowser(config))?.version ?? browserPath;
   const requested = Math.max(1, Math.min(options.concurrency ?? config.concurrency ?? defaultConcurrency(), 16));
-  const preset = options.preset ?? config.preset ?? "medium";
+  const encode = {
+    preset: options.preset ?? config.preset ?? "medium",
+    quality: options.quality ?? "studio",
+    scale: options.scale ?? 1
+  };
   const format = options.format ?? FORMATS.mp4;
   const chunkable = format.chunked;
+  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,
@@ -1805,15 +2030,15 @@ 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(
         (lane) => captureLane(origin, target, config, lane, stats, {
           skipUnchanged,
           signal: options.signal,
-          preset,
-          format,
+          encode,
+          format: chunkFormat,
           ffmpeg,
           workDir: work,
           chunkFile,
@@ -1821,11 +2046,17 @@ var renderMovie = async (origin, target, output, config, onProgress, options = {
             videoId: target.videoId,
             chunk,
             renderer,
-            format: format.name,
+            format: chunkFormat.name,
             width: target.width,
             height: target.height,
             fps: target.fps,
-            preset,
+            preset: encode.preset,
+            // Both change the encoded bytes, so both are part of what a
+            // chunk is: a half-size chunk must never answer for a full
+            // one. A lossless intermediate is the exception by design —
+            // the final pass applies them, so one capture serves all.
+            quality: chunkable ? encode.quality : void 0,
+            scale: chunkable ? encode.scale : void 0,
             input: target.input
           }) : void 0,
           onFrame: () => onProgress?.(stats.captured / Math.max(1, target.durationInFrames), "rendering")
@@ -1846,13 +2077,13 @@ 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 });
-      await run(ffmpeg, ["-y", "-i", silent, ...format.args(preset), destination], options.signal);
+      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.`);
       }
@@ -1905,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}`);
   }
 };
@@ -1937,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 sep2 } 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 {
     }
   }
@@ -1994,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,
@@ -2002,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 }))
         }
       })};`
@@ -2014,7 +2251,6 @@ var startStudioServer = async (initialConfig, options = {}) => {
   const odoriSrc = runtimeSource(config.root);
   let graph = await discoverProject(config);
   await writeGenerated(config, graph);
-  await registerProjectCues(graph);
   const vite = await createServer({
     root: studioRoot,
     configFile: false,
@@ -2073,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: {
@@ -2093,14 +2329,31 @@ var startStudioServer = async (initialConfig, options = {}) => {
     },
     optimizeDeps: { include: ["react", "react-dom", "react/jsx-dev-runtime"] }
   });
+  const loadModule = (file) => vite.ssrLoadModule(`/@fs${file}`);
+  await registerProjectCues(graph, loadModule);
+  let refreshTimer;
+  let refreshChain = Promise.resolve();
+  const enqueueRefresh = (task) => {
+    const next = refreshChain.then(task, task);
+    refreshChain = next.catch(() => void 0);
+    return next;
+  };
+  const scheduleCueRefresh = () => {
+    clearTimeout(refreshTimer);
+    refreshTimer = setTimeout(() => {
+      void enqueueRefresh(() => registerProjectCues(graph, loadModule)).catch((error) => {
+        vite.config.logger.warn(`[odori] cue refresh skipped: ${error instanceof Error ? error.message : String(error)}`);
+      });
+    }, 150);
+  };
   const rediscover = async (file) => {
-    if (!file.startsWith(resolve16(config.root, config.videosDir))) return;
-    const isEntry = file.endsWith("video.tsx") || file.endsWith(".preview.tsx") || file.includes(`${sep2}brands${sep2}`);
+    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 {
       graph = await discoverProject(config);
       await writeGenerated(config, graph);
-      await registerProjectCues(graph);
+      await enqueueRefresh(() => registerProjectCues(graph, loadModule));
     } catch (error) {
       vite.config.logger.warn(`[odori] rediscovery skipped: ${error instanceof Error ? error.message : String(error)}`);
       return;
@@ -2111,14 +2364,14 @@ 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 {
       config = await loadConfig(config.root);
       graph = await discoverProject(config);
       await writeGenerated(config, graph);
-      await registerProjectCues(graph);
+      await enqueueRefresh(() => registerProjectCues(graph, loadModule));
     } catch (error) {
       vite.config.logger.warn(`[odori] config reload skipped: ${error instanceof Error ? error.message : String(error)}`);
       return;
@@ -2127,14 +2380,15 @@ var startStudioServer = async (initialConfig, options = {}) => {
     if (module) vite.moduleGraph.invalidateModule(module);
     vite.ws.send({ type: "full-reload" });
   };
-  const refreshCues = async (file) => {
-    if (!file.startsWith(resolve16(config.root, config.videosDir)) || !file.split(sep2).includes("brands")) return;
-    await registerProjectCues(graph);
+  const refreshCues = (file) => {
+    if (!file.startsWith(resolve17(config.root, config.videosDir) + sep3)) return;
+    if (!/\.tsx?$/.test(file)) return;
+    scheduleCueRefresh();
   };
-  vite.watcher.on("change", (file) => void refreshCues(file));
+  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];
@@ -2144,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));
@@ -2165,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
@@ -2274,8 +2528,12 @@ var runJob = async (config, origin, record, video, options = {}) => exportQueue.
       },
       {
         concurrency: options.concurrency,
-        preset: options.preset,
-        format: options.format,
+        // The record freezes how it should be encoded alongside what, so a
+        // retry from any surface produces the same file the first run would.
+        preset: options.preset ?? record.render?.preset,
+        quality: options.quality ?? record.render?.quality,
+        scale: options.scale ?? record.render?.scale,
+        format: options.format ?? (record.render?.format ? resolveFormat(record.render.format, record.output) : void 0),
         skipUnchangedFrames: options.skipUnchangedFrames,
         signal: controller.signal,
         onTimings: (timings) => {
@@ -2302,9 +2560,23 @@ var runJob = async (config, origin, record, video, options = {}) => exportQueue.
     running.delete(record.job.id);
   }
 });
+var resolveQuality = (requested) => {
+  if (!requested) return "studio";
+  if (QUALITIES.includes(requested)) return requested;
+  throw new Error(`Unknown quality "${requested}". Available: ${QUALITIES.join(", ")}`);
+};
+var resolveScale = (requested) => {
+  if (requested === void 0) return 1;
+  if (!Number.isFinite(requested) || requested < 0.25 || requested > 2) {
+    throw new Error(`Scale ${requested} is out of range. Use a value between 0.25 and 2.`);
+  }
+  return requested;
+};
 var exportCommand = async (id, options = {}) => {
   const { config, graph, videos } = await createContext();
   const format = resolveFormat(options.format ?? config.format, options.output);
+  const quality = resolveQuality(options.quality);
+  const scale = resolveScale(options.scale);
   return withServer(config, async (server) => {
     const record = options.retry ? await readJob(config, options.retry) : await (async () => {
       const video2 = findVideo(videos, id);
@@ -2316,11 +2588,16 @@ 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}`
       );
-      return createJob(config, manifest, output);
+      return createJob(config, manifest, output, {
+        format: format.name,
+        quality,
+        scale,
+        ...options.preset ? { preset: options.preset } : {}
+      });
     })();
     const video = findVideo(videos, record.manifest.videoId);
     log.detail(`job ${record.job.id} manifest ${record.manifest.manifestHash}`);
@@ -2331,7 +2608,10 @@ var exportCommand = async (id, options = {}) => {
     const job = await runJob(config, server.url, record, video, {
       concurrency: options.concurrency,
       preset: options.preset,
-      format,
+      // A retry keeps what its record froze; an explicit flag still wins.
+      quality: options.retry && options.quality === void 0 ? void 0 : quality,
+      scale: options.retry && options.scale === void 0 ? void 0 : scale,
+      format: options.retry ? void 0 : format,
       skipUnchangedFrames: options.skipUnchangedFrames,
       onProgress: (next) => {
         if (next.status === "rendering" || next.status === "encoding") {
@@ -2373,6 +2653,35 @@ var json = (response, status, payload) => {
   response.setHeader("content-type", "application/json");
   response.end(JSON.stringify(payload));
 };
+var exportDestination = (config) => {
+  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) => {
+  if (!value) return null;
+  const withoutPort = value.startsWith("[") ? value.slice(0, value.indexOf("]") + 1) : value.split(":")[0];
+  return withoutPort || null;
+};
+var isLocalRequest = (request) => {
+  const host = hostOf(request.headers.host);
+  if (!host || !LOOPBACK.has(host)) return false;
+  const origin = request.headers.origin;
+  if (origin) {
+    try {
+      if (!LOOPBACK.has(hostOf(new URL(origin).host) ?? "")) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+};
+var safeJobId = (id) => {
+  if (!/^[a-zA-Z0-9._-]+$/.test(id) || id.includes("..")) {
+    throw new Error(`Invalid job id ${JSON.stringify(id)}.`);
+  }
+  return id;
+};
 var devCommand = async (options = {}) => {
   const config = await loadConfig(options.root ?? process.cwd());
   const context = async () => {
@@ -2384,6 +2693,10 @@ var devCommand = async (options = {}) => {
     middleware: (vite) => {
       vite.middlewares.use("/__odori", (request, response, next) => {
         const url = request.url ?? "/";
+        if (!isLocalRequest(request)) {
+          json(response, 403, { error: "This endpoint only answers same-origin requests from Studio on localhost." });
+          return;
+        }
         void (async () => {
           try {
             if (request.method === "POST" && url.startsWith("/still")) {
@@ -2401,8 +2714,7 @@ var devCommand = async (options = {}) => {
               );
               const frame = Number(body.frame ?? 0);
               const inline = body.inline === true;
-              const directory2 = inline ? config.outDir : config.exportDir;
-              const file = resolve18(config.root, `${directory2}/${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(
@@ -2418,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 });
@@ -2426,6 +2738,9 @@ var devCommand = async (options = {}) => {
             }
             if (request.method === "POST" && url.startsWith("/exports")) {
               const body = await readBody(request);
+              const format = resolveFormat(typeof body.format === "string" ? body.format : void 0, void 0);
+              const quality = resolveQuality(typeof body.quality === "string" ? body.quality : void 0);
+              const scale = resolveScale(typeof body.scale === "number" ? body.scale : void 0);
               const { graph, videos } = await context();
               const video = findVideo(videos, String(body.videoId));
               const input = body.input ?? {};
@@ -2437,8 +2752,11 @@ var devCommand = async (options = {}) => {
                 input,
                 { scenes: compiled.scenes, audio: compiled.audio }
               );
-              const output = resolve18(config.root, `${config.exportDir}/${outputName(video.entry.metadata.id)}.mp4`);
-              const record = await createJob(config, manifest, output);
+              const output = resolve19(
+                exportDestination(config),
+                `${outputName(video.entry.metadata.id)}${format.extension}`
+              );
+              const record = await createJob(config, manifest, output, { format: format.name, quality, scale });
               json(response, 202, record.job);
               void runJob(config, origin, record, video).catch((error) => {
                 log.error(`Export failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -2446,7 +2764,7 @@ var devCommand = async (options = {}) => {
               return;
             }
             if (request.method === "POST" && url.startsWith("/retry/")) {
-              const id = url.replace("/retry/", "").split("?")[0];
+              const id = safeJobId(url.replace("/retry/", "").split("?")[0]);
               const record = await readJob(config, id);
               const { videos } = await context();
               const video = findVideo(videos, record.manifest.videoId);
@@ -2457,16 +2775,34 @@ var devCommand = async (options = {}) => {
               return;
             }
             if (request.method === "POST" && url.startsWith("/cancel/")) {
-              const id = url.replace("/cancel/", "").split("?")[0];
+              const id = safeJobId(url.replace("/cancel/", "").split("?")[0]);
               const cancelled = cancelJob(id);
               json(response, cancelled ? 202 : 404, { id, cancelled });
               return;
             }
             if (request.method === "GET" && url.startsWith("/jobs/")) {
-              const id = url.replace("/jobs/", "").split("?")[0];
+              const id = safeJobId(url.replace("/jobs/", "").split("?")[0]);
               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;
@@ -2480,7 +2816,7 @@ var devCommand = async (options = {}) => {
     }
   });
   const origin = server.url;
-  const entry = `${origin}/videos`;
+  const entry = `${origin}/`;
   log.title("Odori Studio");
   log.info(`  ${entry}`);
   log.detail(`  ${server.graph.videos.length} videos, ${server.graph.previews.length} component previews`);
@@ -2491,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 existsSync15 } 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 relative5, 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",
@@ -2511,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 {
@@ -2523,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: existsSync15(videosDir) ? relative5(config.root, videosDir) + "/" : `no ${config.videosDir}/`,
-    ok: existsSync15(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 ? relative5(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
   });
@@ -2558,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 ${relative5(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;
 };
@@ -2584,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("");
@@ -2598,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 existsSync17 } from "fs";
-import { relative as relative7, 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 existsSync16 } from "fs";
-import { relative as relative6, 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";
@@ -2663,30 +3021,30 @@ ${closing}
 `;
 };
 var installedParts = async (config) => {
-  const componentsDir = resolve20(config.root, config.componentsDir);
-  if (!existsSync16(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 (existsSync16(file)) throw new Error(`${relative6(config.root, file)} already exists.`);
-  const hasLayout = existsSync16(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 ${relative6(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 @odori/title-reveal @odori/end-card");
+    log.detail("No registry components installed yet: odori add title-reveal end-card");
   }
   log.detail("Run odori dev to preview it.");
 };
@@ -2717,23 +3075,23 @@ 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 (existsSync17(file)) {
-      log.detail(`Kept existing ${relative7(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 ${relative7(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 @odori/title-reveal @odori/end-card, then odori dev.");
+  log.detail("Next: odori doctor, then odori add title-reveal end-card, then odori dev.");
 };
 
 // src/commands/inspect.ts
@@ -2822,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(
@@ -2844,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 existsSync18 } 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",
@@ -2924,8 +3283,8 @@ var checkAudioWindows = (cues, brand, videoId) => {
   return failures;
 };
 var checkInstalledContracts = async (config, videos) => {
-  const componentsDir = resolve23(config.root, config.componentsDir);
-  const onDisk = existsSync18(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 });
@@ -2934,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;
@@ -2946,9 +3305,9 @@ var checkInstalledContracts = async (config, videos) => {
 };
 
 // src/determinism.ts
-import { readdir as readdir7, readFile as readFile14 } from "fs/promises";
-import { existsSync as existsSync19 } from "fs";
-import { join as join7, relative as relative8, 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*\(/,
@@ -2989,11 +3348,11 @@ var walk2 = async (directory2, files = []) => {
   return files;
 };
 var checkDeterminism = async (config) => {
-  const root = resolve24(config.root, config.videosDir);
-  if (!existsSync19(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"), relative8(config.root, file)))
+    files.map(async (file) => scanSource(await readFile15(file, "utf8"), relative11(config.root, file)))
   );
   return findings.flat();
 };
@@ -3092,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("; ")}` });
@@ -3257,9 +3616,9 @@ 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", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-frame-skip", "retry"],
   jobs: [],
   help: []
 };
@@ -3320,15 +3679,19 @@ 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.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
-             [--preset <name>] [--format <name>] [--no-frame-skip] [--retry <job>]
+             [--preset <name>] [--format <name>] [--quality <tier>] [--scale <n>]
+             [--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.`,
+  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.`,
   jobs: `odori jobs
   List export jobs and their status.`
 };
@@ -3346,18 +3709,20 @@ 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
   --format <name>                  mp4, webm, prores, gif, or png
+  --quality <tier>                 studio, social, or web compression
+  --scale <n>                      Output size multiplier, 0.25 to 2
   --no-frame-skip                  Capture every frame, even unchanged ones
   --retry <job id>                 Re-run a recorded job from its frozen manifest
   --no-open                        Start dev without opening Studio in a browser
@@ -3428,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)
         });
@@ -3444,6 +3811,8 @@ var run2 = async (argv) => {
           input: parseInput(flags),
           concurrency: numberFlag(flags, "concurrency"),
           preset: typeof flags.preset === "string" ? flags.preset : void 0,
+          quality: typeof flags.quality === "string" ? flags.quality : void 0,
+          scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : void 0,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : void 0,
           retry: typeof flags.retry === "string" ? flags.retry : void 0
@@ -3478,6 +3847,7 @@ export {
   discoverProject,
   generateImports,
   writeGenerated,
+  startStudioServer,
   localCandidates,
   createIntegrityResolver,
   outputName,
@@ -3497,7 +3867,6 @@ export {
   findVideo,
   runPrepare,
   freezeManifest,
-  startStudioServer,
   resolveCueFile,
   buildAudioFilter,
   planChunks,
@@ -3533,7 +3902,7 @@ export {
   exportCommand,
   jobsCommand,
   devCommand,
-  stillCommand,
+  frameCommand,
   diffLines,
   countChanges,
   formatDiff,