@odori/cli 0.0.2 → 0.0.3

package/src/discovery.ts

@@ -108,11 +108,13 @@ export const discoverProject = async (config: ResolvedConfig): Promise<ProjectGr
   const previews: DiscoveredPreview[] = [];
   const brands: DiscoveredBrandModule[] = [];
   const hashParts: string[] = [];
+  const componentsRoot = resolve(config.root, config.componentsDir);
 
   for (const file of files) {
     const relativeFile = relative(config.root, file);
+    let contents = "";
     if (/\.(tsx|ts|css|json)$/.test(file)) {
-      const contents = await readFile(file, "utf8");
+      contents = await readFile(file, "utf8");
       hashParts.push(`${relativeFile}:${hashString(contents)}`);
     }
 
@@ -127,13 +129,30 @@ export const discoverProject = async (config: ResolvedConfig): Promise<ProjectGr
         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 + sep) &&
+      (file.split(sep).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(
+          `${relative(videosRoot, file).replace(/\.tsx?$/, "").split(sep).join("-")}-module`,
+          "brands",
+        ),
       });
     } else if (base.endsWith(".preview.tsx")) {
       const name = base.replace(/\.preview\.tsx$/, "");

package/src/formats.ts

@@ -11,6 +11,29 @@
  * 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. */
+export type Quality = "studio" | "social" | "web";
+
+export const QUALITIES: Quality[] = ["studio", "social", "web"];
+
+export 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;
+};
+
+/**
+ * A scale filter that lands on even dimensions, which yuv420p requires.
+ * Lanczos, because a product video is text and lines more than it is grain.
+ */
+const scaleFilter = (scale: number): string =>
+  `scale=trunc(iw*${scale}/2)*2:trunc(ih*${scale}/2)*2:flags=lanczos`;
+
+const scaleArgs = (scale: number): string[] => (scale === 1 ? [] : ["-vf", scaleFilter(scale)]);
+
 export type VideoFormat = {
   name: string;
   extension: string;
@@ -20,8 +43,8 @@ export 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;
 };
 
@@ -33,7 +56,17 @@ export const FORMATS: Record<string, VideoFormat> = {
     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"],
+    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",
@@ -43,7 +76,19 @@ export const FORMATS: Record<string, VideoFormat> = {
     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"],
+    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",
@@ -52,7 +97,19 @@ export const FORMATS: Record<string, VideoFormat> = {
     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"],
+    // 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",
@@ -63,9 +120,11 @@ export const FORMATS: Record<string, VideoFormat> = {
     chunked: false,
     audio: false,
     description: "An animated GIF, palette optimised. Silent, by the format.",
-    args: () => [
+    // 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",
-      "split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3",
+      `${scale === 1 ? "" : `${scaleFilter(scale)},`}split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3`,
       "-loop",
       "0",
     ],
@@ -77,7 +136,7 @@ export const FORMATS: Record<string, VideoFormat> = {
     chunked: false,
     audio: false,
     description: "A numbered PNG sequence, with alpha. For a compositor.",
-    args: () => ["-c:v", "png", "-pix_fmt", "rgba"],
+    args: ({scale}) => [...scaleArgs(scale), "-c:v", "png", "-pix_fmt", "rgba"],
   },
 };
 

package/src/jobs.ts

@@ -4,7 +4,10 @@ import {join, resolve} from "node:path";
 import type {ExportJob, RenderManifest} from "odori";
 import type {ResolvedConfig} from "./config";
 
-export type JobRecord = {job: ExportJob; manifest: RenderManifest; output: string};
+/** How a job should be encoded, frozen with it so a retry cannot drift. */
+export type JobRender = {format?: string; quality?: string; scale?: number; preset?: string};
+
+export type JobRecord = {job: ExportJob; manifest: RenderManifest; output: string; render?: JobRender};
 
 const buildsDir = (config: ResolvedConfig) => resolve(config.root, config.outDir, "builds");
 const jobFile = (config: ResolvedConfig, id: string) => join(buildsDir(config), `${id}.json`);
@@ -17,6 +20,7 @@ export const createJob = async (
   config: ResolvedConfig,
   manifest: RenderManifest,
   output: string,
+  render?: JobRender,
 ): Promise<JobRecord> => {
   await mkdir(buildsDir(config), {recursive: true});
   const now = new Date().toISOString();
@@ -31,7 +35,7 @@ export const createJob = async (
     createdAt: now,
     updatedAt: now,
   };
-  const record: JobRecord = {job, manifest, output};
+  const record: JobRecord = {job, manifest, output, ...(render ? {render} : {})};
   await writeFile(jobFile(config, job.id), `${JSON.stringify(record, null, 2)}\n`, "utf8");
   return record;
 };

package/src/registry-snapshot.json

@@ -400,7 +400,7 @@
     },
     {
       "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": [
         {
@@ -410,7 +410,7 @@
         },
         {
           "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/src/registry-source.ts

@@ -1,7 +1,7 @@
 import {createHash} from "node:crypto";
 import {existsSync} from "node:fs";
 import {mkdir, readFile, writeFile} from "node:fs/promises";
-import {dirname, resolve} from "node:path";
+import {dirname, isAbsolute, relative, resolve, sep} from "node:path";
 import {cacheRoot} from "./binaries";
 import type {ResolvedConfig} from "./config";
 
@@ -65,6 +65,42 @@ export type RegistryComponent = {
 /** `@odori/title-reveal` and `title-reveal` name the same component. */
 export const normalizeComponentName = (name: string): string => name.replace(/^@odori\//, "");
 
+/**
+ * A registry name becomes a URL path segment, a cache filename, and a directory
+ * on disk. The index that supplies it is fetched, so it is not ours to trust:
+ * a plain slug is the only thing any real entry ever is, and anything else is a
+ * malformed or hostile registry trying to reach out of its lane.
+ */
+export const assertSafeName = (name: string): string => {
+  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;
+};
+
+/**
+ * Confine a fetched write to the project.
+ *
+ * A registry item dictates its own `target`, and integrity proves the bytes,
+ * not the intent — a compromised or malicious origin can publish a matching
+ * hash for a document whose target is `../../etc/...` or an absolute path. So
+ * every destination is resolved and checked against the root before a single
+ * byte is written, and a target that climbs out is refused rather than trusted.
+ */
+export const resolveWithinRoot = (root: string, target: string): string => {
+  const destination = resolve(root, target);
+  const rel = relative(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;
+};
+
 export type RegistryOrigin = "network" | "cache" | "bundled";
 
 export type RegistrySource = {
@@ -208,6 +244,7 @@ export const resolveItem = async (
   name: string,
   options: {allowNetwork?: boolean} = {},
 ): Promise<{item: RegistryItemDocument; origin: RegistryOrigin}> => {
+  assertSafeName(name);
   const url = registryUrl(config);
   const cache = resolve(cacheDir(url), `${name}.json`);
 
@@ -245,9 +282,19 @@ export const resolveItem = async (
  * catches truncation, a stale proxy, and a corrupted cache, which are the
  * failures that actually happen.
  */
-export const verifyIntegrity = (item: RegistryItemDocument): void => {
+export const verifyIntegrity = (item: RegistryItemDocument, origin: RegistryOrigin = "network"): void => {
   const expected = item.meta?.integrity;
-  if (!expected) return;
+  if (!expected) {
+    // The snapshot ships inside the npm tarball and is covered by its checksum,
+    // so it carries no hash of its own. Anything fetched must: a document that
+    // arrives over the wire with no integrity is one where the field was
+    // dropped, and trusting it would defeat the check entirely.
+    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))) {

package/src/render.ts

@@ -10,7 +10,7 @@ import {chunkFrames, planChunks, type FrameChunk} from "./chunks";
 import {chunkKey, readChunkRecord, signaturesMatch, useChunkRecord, writeChunkRecord} from "./chunk-cache";
 import {type ResolvedConfig} from "./config";
 import {installBrowser, installFfmpeg, resolveBrowser, resolveFfmpeg} from "./binaries";
-import {FORMATS, type VideoFormat} from "./formats";
+import {FORMATS, type EncodeOptions, type Quality, type VideoFormat} from "./formats";
 import {log} from "./log";
 
 export type RenderTarget = {
@@ -270,17 +270,34 @@ const sequencePattern = (output: string): string => {
   return join(stem, `%05d${extension}`);
 };
 
+/**
+ * The intermediate for formats that must see every frame at once. FFV1 is
+ * genuinely lossless, so the palette or the sequence is computed from the
+ * pixels the browser drew — not from an H.264 generation of them, which is
+ * what the requested format's own args would have produced here. Scale and
+ * quality deliberately do not apply: they belong to the final pass, once.
+ */
+const LOSSLESS: VideoFormat = {
+  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"],
+};
+
 const openChunkEncoder = (
   ffmpeg: string,
   file: string,
   fps: number,
-  preset: string,
+  encode: EncodeOptions,
   format: VideoFormat,
   signal?: AbortSignal,
 ) => {
   const child = spawn(
     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"]},
   );
 
@@ -307,7 +324,7 @@ const openChunkEncoder = (
 type LaneOptions = {
   skipUnchanged: boolean;
   signal?: AbortSignal;
-  preset: string;
+  encode: EncodeOptions;
   format: VideoFormat;
   /** The resolved encoder, so a lane never guesses at what is on PATH. */
   ffmpeg: string;
@@ -368,7 +385,7 @@ const captureLane = async (
       }
 
       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: string[] = [];
       let previousSignature: string | null = null;
       let previousFrame: Buffer | null = null;
@@ -445,6 +462,10 @@ export type RenderTimings = {
 export 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;
@@ -474,12 +495,19 @@ export const renderMovie = async (
   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: EncodeOptions = {
+    preset: options.preset ?? config.preset ?? "medium",
+    quality: options.quality ?? "studio",
+    scale: options.scale ?? 1,
+  };
   const format = options.format ?? FORMATS.mp4;
   // A palette or a still sequence is computed across the whole animation, so
   // it cannot be assembled from independently encoded chunks. One lane, one
   // pass: slower, and the only way the output is correct.
   const chunkable = format.chunked;
+  // What a lane encodes: the requested codec when chunks can be joined by
+  // stream copy, the lossless intermediate when the format needs one pass.
+  const chunkFormat = chunkable ? format : LOSSLESS;
   const skipUnchanged = options.skipUnchangedFrames ?? config.skipUnchangedFrames ?? true;
   const cache = options.cache ?? config.cacheChunks ?? true;
 
@@ -511,8 +539,8 @@ export const renderMovie = async (
         captureLane(origin, target, config, lane, stats, {
           skipUnchanged,
           signal: options.signal,
-          preset,
-          format,
+          encode,
+          format: chunkFormat,
           ffmpeg,
           workDir: work,
           chunkFile,
@@ -521,11 +549,17 @@ export const renderMovie = async (
                 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 : undefined,
+                scale: chunkable ? encode.scale : undefined,
                 input: target.input,
               })
             : undefined,
@@ -557,15 +591,16 @@ export const renderMovie = async (
       await run(ffmpeg, ["-y", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", silent], options.signal);
     }
 
-    // A format that cannot be chunked was captured losslessly and is encoded
-    // here in one pass, where a palette or a sequence can see every frame.
+    // A format that cannot be chunked was captured to the lossless
+    // intermediate and is encoded here in one pass, where a palette or a
+    // sequence can see every frame of the real pixels.
     if (!chunkable) {
       // A sequence is many files. Given one path it writes beside it, using
       // the name as the directory, rather than overwriting a single frame 270
       // times and reporting success.
       const destination = format.name === "png" && !output.includes("%") ? sequencePattern(output) : output;
       if (destination !== output) await mkdir(dirname(destination), {recursive: true});
-      await run(ffmpeg, ["-y", "-i", silent, ...format.args(preset), destination], options.signal);
+      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.`);
       }

package/src/server.ts

@@ -124,11 +124,6 @@ export const startStudioServer = async (
   const odoriSrc = runtimeSource(config.root);
   let graph = await discoverProject(config);
   await writeGenerated(config, graph);
-  // The cue middleware below answers out of this registry, so it has to be
-  // filled before the first preview plays and refilled whenever discovery
-  // runs again: a brand added or edited while the server is up declares
-  // sounds the server has never seen.
-  await registerProjectCues(graph);
 
   const vite = await createServer({
     root: studioRoot,
@@ -211,6 +206,42 @@ export const startStudioServer = async (
     optimizeDeps: {include: ["react", "react-dom", "react/jsx-dev-runtime"]},
   });
 
+  /**
+   * Source modules load through Vite, not Node. Node caches a module for the
+   * life of the process and busting the entry does not reach its imports, so
+   * a brand whose score lives one file away kept serving the old sound. Vite
+   * owns a module graph that invalidates the whole chain on every change —
+   * the same reason the browser preview is always current.
+   */
+  const loadModule = (file: string) => vite.ssrLoadModule(`/@fs${file}`) as Promise<Record<string, unknown>>;
+
+  // The cue middleware answers out of the registry filled here, so it has to
+  // be full before the first preview plays and refilled whenever a source
+  // change can redefine a sound.
+  await registerProjectCues(graph, loadModule);
+
+  /**
+   * Cue refresh is debounced and serialized. `odori add` writes several files
+   * in one gesture and an editor save can fire twice; each burst settles into
+   * one refresh, and refreshes never interleave. Old registrations stay: the
+   * URLs are content addressed, so an entry can never mean a different sound.
+   */
+  let refreshTimer: ReturnType<typeof setTimeout> | undefined;
+  let refreshChain: Promise<unknown> = Promise.resolve();
+  const enqueueRefresh = <Value,>(task: () => Promise<Value>): Promise<Value> => {
+    const next = refreshChain.then(task, task);
+    refreshChain = next.catch(() => undefined);
+    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);
+  };
+
   // Rediscover when video or preview entries appear or disappear.
   const rediscover = async (file: string) => {
     if (!file.startsWith(resolve(config.root, config.videosDir))) return;
@@ -219,7 +250,7 @@ export const startStudioServer = async (
     try {
       graph = await discoverProject(config);
       await writeGenerated(config, graph);
-      await registerProjectCues(graph);
+      await enqueueRefresh(() => registerProjectCues(graph, loadModule));
     } catch (error) {
       // A watcher event can arrive after the source root is gone, for example
       // during a branch switch. Keep the last good graph and stay alive.
@@ -243,7 +274,7 @@ export const startStudioServer = async (
       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;
@@ -254,12 +285,17 @@ export const startStudioServer = async (
   };
   // Rediscovery is driven by files appearing and disappearing, but a cue is
   // edited in place: the score changes, its content hash changes with it, and
-  // the preview then asks for a URL the registry has never heard of.
-  const refreshCues = async (file: string) => {
-    if (!file.startsWith(resolve(config.root, config.videosDir)) || !file.split(sep).includes("brands")) return;
-    await registerProjectCues(graph);
+  // the preview then asks for a URL the registry has never heard of. The
+  // guard is deliberately broad — the scaffold's brand lives in
+  // videos/layout.tsx and a score can live in a file the brand imports, so
+  // any source change under the videos root schedules a refresh and the
+  // debounce keeps the cost of that breadth to one pass per burst.
+  const refreshCues = (file: string) => {
+    if (!file.startsWith(resolve(config.root, config.videosDir) + sep)) 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"]) {

package/studio/src/Studio.tsx

@@ -43,7 +43,10 @@ const pathFor = (view: StudioView, selection?: string | null): string =>
 export const Studio = () => {
   const [route, setRoute] = useState<Route>(readRoute);
   const [paletteOpen, setPaletteOpen] = useState(false);
-  const [mode, setMode] = useState<"player" | "gallery">("player");
+  // The keydown listener registers once; the ref keeps it reading the live
+  // route instead of the one from its first render.
+  const routeRef = useRef(route);
+  routeRef.current = route;
   const search = useRef<HTMLInputElement>(null);
   const {theme, setTheme} = useTheme();
 
@@ -80,15 +83,20 @@ export const Studio = () => {
         search.current?.focus();
       }
       if (event.key.toLowerCase() === "g") {
-        setMode((value) => (value === "player" ? "gallery" : "player"));
+        // From a detail back to its gallery; already-gallery routes stay put.
+        const current = routeRef.current;
+        if (current.selection && current.view !== "home") navigate(current.view);
       }
     };
     window.addEventListener("keydown", onKeyDown);
     return () => window.removeEventListener("keydown", onKeyDown);
   }, []);
 
-  const galleryCapable = route.view === "videos" || route.view === "components";
-  const singleColumn = route.view === "assets" || route.view === "home" || (galleryCapable && mode === "gallery");
+  // The list pages are galleries; a selection is that item's detail, which
+  // shows the stage and the inspector with no list beside them. What used to
+  // be a modal "gallery mode" is now just the route with no selection.
+  const detailCapable = route.view === "videos" || route.view === "components" || route.view === "brands";
+  const singleColumn = !detailCapable || route.selection === null;
 
   return (
     <div className="studio">
@@ -144,17 +152,14 @@ export const Studio = () => {
 
       <main className="main" data-single={singleColumn ? "true" : undefined}>
         {route.view === "videos" ? (
-          <VideosView selection={route.selection} onSelect={(id) => navigate("videos", id)} mode={mode} />
+          <VideosView selection={route.selection} onSelect={(id) => navigate("videos", id)} />
         ) : null}
         {route.view === "components" ? (
-          <ComponentsView
-           
-            selection={route.selection}
-            onSelect={(id) => navigate("components", id)}
-            mode={mode}
-          />
+          <ComponentsView selection={route.selection} onSelect={(id) => navigate("components", id)} />
+        ) : null}
+        {route.view === "brands" ? (
+          <BrandsView selection={route.selection} onSelect={(name) => navigate("brands", name)} />
         ) : null}
-        {route.view === "brands" ? <BrandsView /> : null}
         {route.view === "assets" ? <AssetsView /> : null}
         {route.view === "home" ? <HomeView onOpen={(view, selection) => navigate(view, selection)} /> : null}
       </main>
@@ -170,21 +175,13 @@ export const Studio = () => {
         <span>arrows step</span>
         <span>- = speed</span>
         <span>[ ] scene</span>
-        <span>s safe area</span>
-        <span>g gallery</span>
       </footer>
 
       <CommandPalette
         open={paletteOpen}
         onClose={() => setPaletteOpen(false)}
-        onOpenVideo={(id) => {
-          setMode("player");
-          navigate("videos", id);
-        }}
-        onOpenComponent={(id) => {
-          setMode("player");
-          navigate("components", id);
-        }}
+        onOpenVideo={(id) => navigate("videos", id)}
+        onOpenComponent={(id) => navigate("components", id)}
         onView={(view) => navigate(view as StudioView)}
       />
     </div>