@odori/cli 0.0.2 → 0.0.4

package/package.json

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

package/src/assets.ts

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

package/src/brand-file.ts

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

package/src/chunk-cache.ts

@@ -12,6 +12,10 @@ export type ChunkIdentity = {
   height: number;
   fps: number;
   preset: string;
+  /** Compression tier the chunk was encoded at. Changes the bytes. */
+  quality?: string;
+  /** Scale multiplier the chunk was encoded at. Changes the dimensions. */
+  scale?: number;
   /** The browser build that captured the frames. See `chunkKey`. */
   renderer?: string;
   /** The codec the chunk was encoded with, which decides what it can join. */
@@ -49,6 +53,8 @@ export const chunkKey = (identity: ChunkIdentity): string =>
     height: identity.height,
     fps: identity.fps,
     preset: identity.preset,
+    quality: identity.quality ?? null,
+    scale: identity.scale ?? null,
     input: identity.input ?? null,
   });
 

package/src/cli.ts

@@ -10,7 +10,7 @@ import {initCommand} from "./commands/init";
 import {inspectCommand} from "./commands/inspect";
 import {listCommand} from "./commands/list";
 import {newCommand} from "./commands/new";
-import {stillCommand} from "./commands/still";
+import {frameCommand} from "./commands/frame";
 import {testCommand} from "./commands/test";
 
 type Flags = Record<string, string | boolean>;
@@ -84,9 +84,9 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   update: ["force"],
   list: [],
   inspect: ["json", "input"],
-  still: ["frame", "output", "input"],
+  frame: ["at", "output", "input"],
   test: ["json"],
-  export: ["output", "input", "concurrency", "preset", "format", "no-frame-skip", "retry"],
+  export: ["output", "input", "concurrency", "preset", "format", "quality", "scale", "no-frame-skip", "retry"],
   jobs: [],
   help: [],
 };
@@ -160,15 +160,19 @@ const USAGE: Record<string, string> = {
   Print discovered video ids and formats.`,
   inspect: `odori inspect <id> [--json] [--input <json>]
   Show resolved layout, inputs, scenes, and assets.`,
-  still: `odori still <id> --frame <n> [--output <path>] [--input <json>]
-  Render one deterministic frame.`,
+  frame: `odori frame <id> --at <time> [--output <path>] [--input <json>]
+  Render one deterministic frame to a PNG. --at is a duration: 4s, 500ms, or
+  120f for frame 120. A bare number is seconds.`,
   test: `odori test [id] [--json]
   Validate contracts and representative frames. --json emits one object per
   check, for CI.`,
   export: `odori export <id> [--output <path>] [--input <json>] [--concurrency <n>]
-             [--preset <name>] [--format <name>] [--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.`,
 };
@@ -187,18 +191,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
@@ -275,9 +281,11 @@ export const run = async (argv: string[]): Promise<number> => {
       case "inspect":
         await inspectCommand(positionals[0] ?? "", {json: flags.json === true, input: parseInput(flags)});
         return 0;
-      case "still":
-        await stillCommand(positionals[0] ?? "", {
-          frame: numberFlag(flags, "frame") ?? 0,
+      case "frame":
+        await frameCommand(positionals[0] ?? "", {
+          // A duration, so "4s" and "120f" both work; a bare number is
+          // seconds, the way every other time value in Odori reads.
+          at: typeof flags.at === "string" ? flags.at : (numberFlag(flags, "at") ?? 0),
           output: typeof flags.output === "string" ? flags.output : undefined,
           input: parseInput(flags),
         });
@@ -291,6 +299,8 @@ export const run = async (argv: string[]): Promise<number> => {
           input: parseInput(flags),
           concurrency: numberFlag(flags, "concurrency"),
           preset: typeof flags.preset === "string" ? flags.preset : undefined,
+          quality: typeof flags.quality === "string" ? flags.quality : undefined,
+          scale: numberFlag(flags, "scale"),
           format: typeof flags.format === "string" ? flags.format : undefined,
           skipUnchangedFrames: flags["no-frame-skip"] === true ? false : undefined,
           retry: typeof flags.retry === "string" ? flags.retry : undefined,

package/src/commands/add.ts

@@ -5,7 +5,8 @@ import {hashString} from "odori";
 import {loadConfig} from "../config";
 import {log} from "../log";
 import {registerCueInBrand} from "../brand-file";
-import {normalizeComponentName, registryUrl, resolveItem, resolveRegistry, verifyIntegrity} from "../registry-source";
+import {assertSafeName, normalizeComponentName, registryUrl, resolveItem, resolveRegistry, resolveWithinRoot, verifyIntegrity} from "../registry-source";
+import {installAsset} from "../assets";
 import {readProvenance, writeProvenance} from "./update";
 
 /**
@@ -14,7 +15,7 @@ import {readProvenance, writeProvenance} from "./update";
  * replaced without an explicit decision.
  */
 export const addCommand = async (names: string[], options: {force?: boolean; dryRun?: boolean} = {}) => {
-  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;
@@ -46,19 +47,43 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
       else log.warn(`${component.namespaced} needs a "${cue}" cue and no registry entry provides one.`);
     }
 
+    // An asset is bytes, not source: it is fetched, verified, and written into
+    // public/, then registered by URL. Nothing about it is a file to edit, so
+    // it never goes through the copy-and-record path below.
+    if (component.kind === "asset" && component.asset) {
+      const written = await installAsset(config, component, {dryRun: options.dryRun, force: options.force});
+      if (!options.dryRun && written) {
+        installed.push(component.name);
+        const registered = await registerCueInBrand(
+          config,
+          {name: component.asset.cue, url: component.asset.url},
+          component.name,
+        );
+        if (registered?.already) {
+          log.detail(`  "${component.asset.cue}" is already registered in ${registered.file}`);
+        } else if (registered) {
+          log.detail(`  registered "${component.asset.cue}" in ${registered.file}`);
+        } else {
+          log.warn(`  No brand with an audio.cues block found. Add it yourself:`);
+          log.detail(`    audio: {cues: {"${component.asset.cue}": "${component.asset.url}"}}`);
+        }
+      }
+      continue;
+    }
+
     // The item document carries the file contents; the index does not.
-    const {item} = await resolveItem(config, component.name);
+    const {item, origin} = await resolveItem(config, component.name);
     // Before anything is written: the bytes have to be the bytes the registry
-    // said it was serving.
-    verifyIntegrity(item);
+    // said it was serving, and a fetched document has to say so at all.
+    verifyIntegrity(item, origin);
 
-    const target = resolve(config.root, config.componentsDir, component.name);
+    const target = resolve(config.root, config.componentsDir, assertSafeName(component.name));
     const hashes: Record<string, string> = {};
 
     // What will be written, listed before it is. Installing source into
     // somebody's repository should never be the first they hear of a path.
     for (const file of item.files) {
-      const destination = resolve(config.root, file.target);
+      const destination = resolveWithinRoot(config.root, file.target);
       const exists = existsSync(destination);
       log.detail(`  ${exists ? "replace" : "create "} ${relative(config.root, destination)}`);
     }
@@ -71,7 +96,7 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
 
     for (const file of item.files) {
       const name = file.path.split("/").pop() ?? file.path;
-      const destination = resolve(config.root, file.target);
+      const destination = resolveWithinRoot(config.root, file.target);
       hashes[name] = hashString(file.content);
 
       if (existsSync(destination) && !options.force) {

package/src/commands/dev.ts

@@ -1,4 +1,6 @@
-import {resolve} from "node:path";
+import {relative, resolve} from "node:path";
+import {homedir} from "node:os";
+import {existsSync} from "node:fs";
 import {readFile} from "node:fs/promises";
 import type {IncomingMessage, ServerResponse} from "node:http";
 import {loadConfig} from "../config";
@@ -6,10 +8,11 @@ import {log} from "../log";
 import {createJob, listJobs, readJob} from "../jobs";
 import {discoverProject} from "../discovery";
 import {findVideo, freezeManifest, loadVideos, outputName} from "../project";
+import {resolveFormat} from "../formats";
 import {renderStill} from "../render";
 import {openInBrowser, shouldOpenBrowser} from "../open";
 import {startStudioServer} from "../server";
-import {cancelJob, runJob} from "./exportVideo";
+import {cancelJob, resolveQuality, resolveScale, runJob} from "./exportVideo";
 import {compileInBrowser, targetFor} from "./shared";
 
 const readBody = async (request: IncomingMessage): Promise<Record<string, unknown>> => {
@@ -25,6 +28,65 @@ const json = (response: ServerResponse, status: number, payload: unknown) => {
   response.end(JSON.stringify(payload));
 };
 
+/**
+ * Where a Studio export lands: the Downloads folder, like any app that hands
+ * you a file. The CLI keeps writing into the project's export directory - a
+ * build artifact belongs to the build - but a file made by clicking a button
+ * belongs where files made by clicking buttons go.
+ */
+const exportDestination = (config: {root: string; exportDir: string}): string => {
+  const downloads = resolve(homedir(), "Downloads");
+  return existsSync(downloads) ? downloads : resolve(config.root, config.exportDir);
+};
+
+/**
+ * These endpoints spawn a browser and an encoder and write files, so they are
+ * not the harmless read-only surface a dev server usually exposes. The server
+ * binds to 127.0.0.1, which keeps other machines out, but a page open in the
+ * developer's own browser can still reach a loopback port — directly, or by
+ * rebinding a hostname it controls to 127.0.0.1 and POSTing to it.
+ *
+ * So a request has to look like it came from Studio itself: its Host must be a
+ * loopback name, and a cross-site fetch (which the browser stamps with an
+ * Origin) must be same-origin. A same-origin XHR from Studio carries neither a
+ * foreign Origin nor a foreign Host and passes; a drive-by page fails both.
+ */
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+
+const hostOf = (value: string | undefined): string | null => {
+  if (!value) return null;
+  // Strip a port without tripping over an IPv6 literal's own colons.
+  const withoutPort = value.startsWith("[") ? value.slice(0, value.indexOf("]") + 1) : value.split(":")[0];
+  return withoutPort || null;
+};
+
+export const isLocalRequest = (request: IncomingMessage): boolean => {
+  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;
+};
+
+/**
+ * A job id is minted as `job-<hash>-<base36>` and then read straight back as a
+ * filename, so it is confined to the characters that mint it. This keeps a
+ * crafted id like `../../etc/passwd` from ever reaching the filesystem, even
+ * though the local-origin guard already stands in front of it.
+ */
+export const safeJobId = (id: string): string => {
+  if (!/^[a-zA-Z0-9._-]+$/.test(id) || id.includes("..")) {
+    throw new Error(`Invalid job id ${JSON.stringify(id)}.`);
+  }
+  return id;
+};
+
 /**
  * Studio previews without encoding. These endpoints exist so an explicit
  * export action in the browser reaches the same queue and render worker the
@@ -42,6 +104,10 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
     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")) {
@@ -61,8 +127,9 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
               // A clipboard grab is transient, so it renders into the generated
               // directory instead of littering the export directory.
               const inline = body.inline === true;
-              const directory = inline ? config.outDir : config.exportDir;
-              const file = resolve(config.root, `${directory}/${outputName(video.entry.metadata.id)}-${frame}.png`);
+              const file = inline
+                ? resolve(config.root, config.outDir, `${outputName(video.entry.metadata.id)}-${frame}.png`)
+                : resolve(exportDestination(config), `${outputName(video.entry.metadata.id)}-${frame}.png`);
               await renderStill(
                 origin,
                 targetFor(
@@ -87,6 +154,11 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
 
             if (request.method === "POST" && url.startsWith("/exports")) {
               const body = await readBody(request);
+              // Validated before compiling: a wrong option should cost a
+              // sentence, not a browser launch.
+              const format = resolveFormat(typeof body.format === "string" ? body.format : undefined, undefined);
+              const quality = resolveQuality(typeof body.quality === "string" ? body.quality : undefined);
+              const scale = resolveScale(typeof body.scale === "number" ? body.scale : undefined);
               const {graph, videos} = await context();
               const video = findVideo(videos, String(body.videoId));
               const input = (body.input ?? {}) as Record<string, unknown>;
@@ -98,8 +170,11 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
                 input,
                 {scenes: compiled.scenes, audio: compiled.audio},
               );
-              const output = resolve(config.root, `${config.exportDir}/${outputName(video.entry.metadata.id)}.mp4`);
-              const record = await createJob(config, manifest, output);
+              const output = resolve(
+                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) => {
@@ -109,7 +184,7 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
             }
 
             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);
@@ -121,18 +196,45 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
             }
 
             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;
             }
 
+            /**
+             * The source that produced the frame you are looking at.
+             *
+             * Studio shows the path already; a path you cannot read is a
+             * riddle. Reading is confined to source files inside the project,
+             * because this serves whatever a query string asks for and the
+             * only safe answer to "../../.ssh/id_rsa" is no.
+             */
+            if (request.method === "GET" && url.startsWith("/source")) {
+              const asked = new URL(url, "http://localhost").searchParams.get("file") ?? "";
+              const file = resolve(config.root, asked);
+              const inside = relative(config.root, file);
+              const readable = /\.(tsx?|jsx?|css|json|md)$/.test(file);
+              if (!inside || inside.startsWith("..") || !readable) {
+                json(response, 400, {error: `Refusing to read ${asked}.`});
+                return;
+              }
+              try {
+                response.statusCode = 200;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end(await readFile(file, "utf8"));
+              } catch {
+                json(response, 404, {error: `${asked} is not there.`});
+              }
+              return;
+            }
+
             if (request.method === "GET" && url.startsWith("/jobs")) {
               json(response, 200, await listJobs(config));
               return;
@@ -148,9 +250,9 @@ export const devCommand = async (options: {port?: number; root?: string; open?:
   });
 
   const origin = server.url;
-  // Views are routable, so name the one Studio starts on rather than leaving a
-  // bare origin that silently resolves to it.
-  const entry = `${origin}/videos`;
+  // Studio opens on the home overview: what the project contains, each card
+  // playing, with every deeper view one click in.
+  const entry = `${origin}/`;
   log.title("Odori Studio");
   log.info(`  ${entry}`);
   log.detail(`  ${server.graph.videos.length} videos, ${server.graph.previews.length} component previews`);

package/src/commands/doctor.ts

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