@odori/cli 0.0.2 → 0.0.3

package/dist/cli.js

@@ -2,7 +2,7 @@ import {
   checkFlags,
   parseArgs,
   run
-} from "./chunk-7XJL2BYO.js";
+} from "./chunk-RXLB2CXH.js";
 export {
   checkFlags,
   parseArgs,

package/dist/index.d.ts

@@ -177,6 +177,16 @@ declare const freezeManifest: (video: LoadedVideo, graph: ProjectGraph, config:
  * concatenated without re-encoding. `chunked: false` says a format has to be
  * encoded in one pass, which is slower and correct.
  */
+/** Compression tiers, named for where the file is going. */
+type Quality = "studio" | "social" | "web";
+type EncodeOptions = {
+    /** x264-style speed preset. Orthogonal to quality: it trades time, not pixels. */
+    preset: string;
+    /** Compression tier. Codecs that are already lossless or mandated ignore it. */
+    quality: Quality;
+    /** Output scale multiplier. 1 is the composition's own size. */
+    scale: number;
+};
 type VideoFormat = {
     name: string;
     extension: string;
@@ -186,8 +196,8 @@ type VideoFormat = {
     chunked: boolean;
     /** Whether the container carries an audio track at all. */
     audio: boolean;
-    /** FFmpeg arguments for the video stream, given the requested preset. */
-    args: (preset: string) => string[];
+    /** FFmpeg arguments for the video stream. */
+    args: (options: EncodeOptions) => string[];
     description: string;
 };
 declare const FORMATS: Record<string, VideoFormat>;
@@ -254,6 +264,10 @@ type RenderTimings = {
 type RenderOptions = {
     concurrency?: number;
     preset?: string;
+    /** Compression tier. Defaults to studio, which is what the pipeline always was. */
+    quality?: Quality;
+    /** Output scale multiplier. Defaults to 1, the composition's own size. */
+    scale?: number;
     /** Container and codec. Defaults to H.264 in MP4. */
     format?: VideoFormat;
     skipUnchangedFrames?: boolean;
@@ -298,16 +312,24 @@ type CompileResult = {
 declare const compileInBrowser: (origin: string, target: RenderTarget, config: ResolvedConfig) => Promise<CompileResult>;
 declare const withServer: <Value>(config: ResolvedConfig, handler: (server: StudioServer) => Promise<Value>) => Promise<Value>;
 
+/** How a job should be encoded, frozen with it so a retry cannot drift. */
+type JobRender = {
+    format?: string;
+    quality?: string;
+    scale?: number;
+    preset?: string;
+};
 type JobRecord = {
     job: ExportJob;
     manifest: RenderManifest;
     output: string;
+    render?: JobRender;
 };
 /**
  * An export job records the frozen manifest, progress, attempts, and result,
  * so a retry reuses the approved inputs instead of resolving them again.
  */
-declare const createJob: (config: ResolvedConfig, manifest: RenderManifest, output: string) => Promise<JobRecord>;
+declare const createJob: (config: ResolvedConfig, manifest: RenderManifest, output: string, render?: JobRender) => Promise<JobRecord>;
 declare const readJob: (config: ResolvedConfig, id: string) => Promise<JobRecord>;
 declare const updateJob: (config: ResolvedConfig, job: ExportJob) => Promise<ExportJob>;
 declare const appendJobLog: (config: ResolvedConfig, id: string, message: string) => Promise<ExportJob>;
@@ -494,6 +516,8 @@ declare const cancelJob: (id: string) => boolean;
 declare const runJob: (config: ResolvedConfig, origin: string, record: JobRecord, video: LoadedVideo, options?: {
     concurrency?: number;
     preset?: string;
+    quality?: Quality;
+    scale?: number;
     format?: VideoFormat;
     skipUnchangedFrames?: boolean;
     signal?: AbortSignal;
@@ -504,6 +528,8 @@ declare const exportCommand: (id: string, options?: {
     input?: Record<string, unknown>;
     concurrency?: number;
     preset?: string;
+    quality?: string;
+    scale?: number;
     format?: string;
     skipUnchangedFrames?: boolean;
     retry?: string;

package/dist/index.js

@@ -75,7 +75,7 @@ import {
   withServer,
   writeGenerated,
   writePrepareCache
-} from "./chunk-7XJL2BYO.js";
+} from "./chunk-RXLB2CXH.js";
 export {
   CHROME_BUILD,
   FORMATS,

package/dist/{registry-snapshot-NIH2JMQ6.js → registry-snapshot-BDP6PVYB.js}

@@ -401,7 +401,7 @@ var registry_snapshot_default = {
     },
     {
       name: "brand-provider",
-      description: "Typed color, type, spacing, radius, and motion tokens.",
+      description: "The resolved brand rendered as a sheet: color, type, and motion.",
       registryDependencies: [],
       files: [
         {
@@ -411,7 +411,7 @@ var registry_snapshot_default = {
         },
         {
           path: "components/brand-provider/brand-provider.preview.tsx",
-          content: 'import {defineComponentPreview} from "odori/preview";\nimport {BrandProvider} from "./brand-provider";\n\nexport default defineComponentPreview({\n  title: "Brand provider",\n  category: "Foundation",\n  description: "Typed color, type, spacing, radius, and motion tokens.",\n  component: BrandProvider,\n  canvas: {width: 1920, height: 1080, duration: "4s"},\n  controls: {\n    title: {type: "text", defaultValue: "Brand tokens"},\n  },\n  examples: [\n    {name: "Everything", props: {}},\n    {name: "Colors only", props: {show: ["colors"], title: "Palette"}},\n  ],\n});\n',
+          content: 'import {defineComponentPreview} from "odori/preview";\nimport {BrandProvider} from "./brand-provider";\n\nexport default defineComponentPreview({\n  title: "Brand provider",\n  category: "Foundation",\n  description: "The resolved brand rendered as a sheet: color, type, and motion.",\n  component: BrandProvider,\n  canvas: {width: 1920, height: 1080, duration: "4s"},\n  controls: {\n    title: {type: "text", defaultValue: "Brand tokens"},\n  },\n  examples: [\n    {name: "Everything", props: {}},\n    {name: "Colors only", props: {show: ["colors"], title: "Palette"}},\n  ],\n});\n',
           target: "videos/components/brand-provider/brand-provider.preview.tsx"
         }
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odori/cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "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.3"
   },
   "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.3"
   },
   "publishConfig": {
     "access": "public"

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

@@ -86,7 +86,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   inspect: ["json", "input"],
   still: ["frame", "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: [],
 };
@@ -166,9 +166,12 @@ const USAGE: Record<string, string> = {
   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.`,
 };
@@ -199,6 +202,8 @@ Options
   --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
@@ -291,6 +296,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,7 @@ 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 {readProvenance, writeProvenance} from "./update";
 
 /**
@@ -14,7 +14,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;
@@ -47,18 +47,18 @@ export const addCommand = async (names: string[], options: {force?: boolean; dry
     }
 
     // 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 +71,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 {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,14 +196,14 @@ 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;
             }
@@ -148,9 +223,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/exportVideo.ts

@@ -4,7 +4,7 @@ import type {ResolvedConfig} from "../config";
 import {log} from "../log";
 import {JobQueue, appendJobLog, createJob, listJobs, readJob, updateJob, type JobRecord} from "../jobs";
 import {findVideo, freezeManifest, outputName, type LoadedVideo} from "../project";
-import {resolveFormat, type VideoFormat} from "../formats";
+import {resolveFormat, QUALITIES, type Quality, type VideoFormat} from "../formats";
 import {materializeCues} from "../cues";
 import {renderMovie} from "../render";
 import {compileInBrowser, createContext, targetFor, withServer} from "./shared";
@@ -33,6 +33,8 @@ export const runJob = async (
   options: {
     concurrency?: number;
     preset?: string;
+    quality?: Quality;
+    scale?: number;
     format?: VideoFormat;
     skipUnchangedFrames?: boolean;
     signal?: AbortSignal;
@@ -86,8 +88,12 @@ export const runJob = async (
         },
         {
           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 as Quality | undefined),
+          scale: options.scale ?? record.render?.scale,
+          format: options.format ?? (record.render?.format ? resolveFormat(record.render.format, record.output) : undefined),
           skipUnchangedFrames: options.skipUnchangedFrames,
           signal: controller.signal,
           onTimings: (timings) => {
@@ -119,6 +125,22 @@ export const runJob = async (
     }
   });
 
+/** A named tier, or a sentence naming the tiers. */
+export const resolveQuality = (requested: string | undefined): Quality => {
+  if (!requested) return "studio";
+  if ((QUALITIES as string[]).includes(requested)) return requested as Quality;
+  throw new Error(`Unknown quality "${requested}". Available: ${QUALITIES.join(", ")}`);
+};
+
+/** A sane multiplier: enough for a half-size preview and a 2x retina cut. */
+export const resolveScale = (requested: number | undefined): number => {
+  if (requested === undefined) 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;
+};
+
 export const exportCommand = async (
   id: string,
   options: {
@@ -126,6 +148,8 @@ export const exportCommand = async (
     input?: Record<string, unknown>;
     concurrency?: number;
     preset?: string;
+    quality?: string;
+    scale?: number;
     format?: string;
     skipUnchangedFrames?: boolean;
     retry?: string;
@@ -135,6 +159,8 @@ export const exportCommand = async (
   // Resolved before anything renders: an unknown format should cost a sentence,
   // not twenty minutes of capture.
   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
@@ -153,7 +179,12 @@ export const exportCommand = async (
             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);
@@ -166,7 +197,10 @@ export const exportCommand = async (
     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 === undefined ? undefined : quality,
+      scale: options.retry && options.scale === undefined ? undefined : scale,
+      format: options.retry ? undefined : format,
       skipUnchangedFrames: options.skipUnchangedFrames,
       onProgress: (next) => {
         if (next.status === "rendering" || next.status === "encoding") {

package/src/commands/init.ts

@@ -52,5 +52,5 @@ export const initCommand = async (root = process.cwd()) => {
     log.success(`Created ${relative(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.");
 };

package/src/commands/new.ts

@@ -120,7 +120,7 @@ export const newCommand = async (name: string, options: {blank?: boolean} = {})
   else if (options.blank !== true) {
     // Nothing to compose with is worth saying once, with the command that
     // changes it, rather than leaving the plain entry to imply this is the way.
-    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.");
 };

package/src/cues.ts

@@ -12,11 +12,12 @@ import {
   resolveEntryLayout,
   type Brand,
   type CueDefinition,
+  type VideoEntry,
+  type VideoLayout,
 } from "odori";
 import type {ResolvedConfig} from "./config";
 import type {ProjectGraph} from "./discovery";
 import {log} from "./log";
-import {loadVideos} from "./project";
 
 /** Where a rendered cue lands. Content addressed, so it is written once. */
 export const cueCacheDir = (config: ResolvedConfig) => resolve(config.root, config.outDir, "cues");
@@ -93,15 +94,22 @@ export const renderedCue = (url: string): Uint8Array | null => {
 const isBrand = (value: unknown): value is Brand =>
   typeof value === "object" && value !== null && (value as Brand).kind === "odori-brand";
 
+const isLayout = (value: unknown): value is VideoLayout =>
+  typeof value === "object" && value !== null && (value as VideoLayout).kind === "odori-layout";
+
+/** How registration reads a source module. The dev server supplies Vite. */
+export type ModuleLoader = (file: string) => Promise<Record<string, unknown>>;
+
 /**
- * Import a source file fresh.
+ * Import a source file fresh, for callers with no dev server.
  *
- * Node caches modules by URL for the life of the process, so a dev server that
- * re-reads a brand after an edit would otherwise keep the scores it saw at
- * boot. The file's mtime in the specifier makes an edited file a new module
- * and an untouched one a cache hit.
+ * Node caches modules by URL for the life of the process; the file's mtime in
+ * the specifier makes an edited file a new module and an untouched one a cache
+ * hit. What this cannot do is see through an import: a brand whose score lives
+ * in another file keeps that child cached, which is why the dev server loads
+ * through Vite's module graph instead — Vite invalidates the whole chain.
  */
-const importFresh = async (file: string): Promise<Record<string, unknown>> =>
+export const importFresh: ModuleLoader = async (file) =>
   (await import(`${pathToFileURL(file).href}?odori=${statSync(file).mtimeMs}`)) as Record<string, unknown>;
 
 /**
@@ -109,30 +117,35 @@ const importFresh = async (file: string): Promise<Record<string, unknown>> =>
  * one by content hash the moment Studio loads.
  *
  * Discovery is the source of truth on both halves. The brand modules are what
- * make a cue exist at all, including a brand no video has adopted yet, and
- * they are registered first at the default frame rate. The video entries are
- * then loaded for their layouts, because the frame rate decides how many
- * samples a cue occupies and only an entry knows its own. A project that
- * cannot be loaded — a half-written entry mid-edit — leaves the brand pass in
- * place rather than taking the server down.
+ * make a cue exist at all, including a brand no video has adopted yet. They
+ * register first at the default frame rate; any layout exported beside a brand
+ * then re-registers it at the rate that layout pins, because the frame rate
+ * decides how many samples a cue occupies. The video entries come last for the
+ * same reason: only an entry knows the layout it actually plays under. A file
+ * that cannot be loaded — half-written mid-edit — leaves the passes that
+ * succeeded in place rather than taking the server down.
  */
-export const registerProjectCues = async (graph: ProjectGraph): Promise<number> => {
+export const registerProjectCues = async (graph: ProjectGraph, load: ModuleLoader = importFresh): Promise<number> => {
   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 = resolveEntryLayout(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} as VideoEntry;
+      const layout = resolveEntryLayout(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;