@odori/cli 0.0.2 → 0.0.4

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";
 
@@ -46,14 +46,28 @@ export type ComponentContract = {
   loops?: boolean;
 };
 
-export type RegistryKind = "component" | "cue";
+export type RegistryKind = "component" | "cue" | "asset";
+
+/** A produced file the registry publishes: sound synthesis cannot reach. */
+export type RegistryAsset = {
+  cue: string;
+  url: string;
+  target: string;
+  bytes: number;
+  integrity: string;
+};
 
 export type RegistryComponent = {
   name: string;
-  /** Components render pixels. Cues render samples. Both install as source. */
+  /**
+   * Components render pixels and cues render samples; both install as source.
+   * An asset installs as bytes into `public/` and is registered by URL.
+   */
   kind?: RegistryKind;
   /** Present on cues: the brand name it registers, and the factory to call. */
   cue?: {name: string; export: string};
+  /** Present on assets: the file to fetch and the cue name it answers to. */
+  asset?: RegistryAsset;
   namespaced: string;
   family: string;
   description: string;
@@ -65,6 +79,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 = {
@@ -87,6 +137,7 @@ type RegistryItemDocument = {
     namespaced?: string;
     contract?: RegistryComponent["contract"];
     cue?: {name: string; export: string};
+    asset?: RegistryAsset;
     integrity?: string;
   };
 };
@@ -96,6 +147,25 @@ const DEFAULT_URL = "https://odori.dev/r/v1";
 export const registryUrl = (config: ResolvedConfig): string =>
   (config.registryUrl ?? process.env.ODORI_REGISTRY ?? DEFAULT_URL).replace(/\/$/, "");
 
+/**
+ * The site the registry is served from, without its document path.
+ *
+ * Documents live under `/r/v1`; published media lives at the site root, the
+ * same absolute path a project will reference it by once it is installed. So
+ * an asset URL resolves against the origin rather than against the registry
+ * directory, and a self-hosted registry still finds its own files.
+ */
+export const registryOrigin = (config: ResolvedConfig): string => {
+  const url = registryUrl(config);
+  try {
+    return new URL(url).origin;
+  } catch {
+    // A relative or malformed registryUrl: keep everything before /r, which is
+    // where a mirror laid out like ours would put its media.
+    return url.replace(/\/r(\/v\d+)?$/, "");
+  }
+};
+
 /** One directory per origin URL, so two registries never share a cache. */
 const cacheDir = (url: string): string =>
   resolve(cacheRoot(), "registry", createHash("sha256").update(url).digest("hex").slice(0, 16));
@@ -113,6 +183,7 @@ const toComponent = (item: RegistryItemDocument): RegistryComponent => ({
   namespaced: item.meta?.namespaced ?? `@odori/${item.name}`,
   kind: (item.meta?.kind as RegistryComponent["kind"]) ?? "component",
   ...(item.meta?.cue ? {cue: item.meta.cue} : {}),
+  ...(item.meta?.asset ? {asset: item.meta.asset} : {}),
   family: item.meta?.family ?? "Uncategorized",
   description: item.description ?? "",
   files: item.files.map((file) => file.path.split("/").pop() ?? file.path),
@@ -208,6 +279,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 +317,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

@@ -93,6 +93,8 @@ const odoriProjectPlugin = (config: ResolvedConfig, getGraph: () => ProjectGraph
       `export const project = ${JSON.stringify({
         root: config.root,
         videosDir: config.videosDir,
+        componentsDir: config.componentsDir,
+        categories: graph.categories,
         exportDir: config.exportDir,
         audioDir: config.audioDir,
         docsUrl: config.docsUrl,
@@ -101,7 +103,11 @@ const odoriProjectPlugin = (config: ResolvedConfig, getGraph: () => ProjectGraph
         assets: config.assets ?? [],
         files: {
           videos: graph.videos.map((video) => ({id: video.slug, file: video.relativeFile})),
-          previews: graph.previews.map((preview) => ({id: preview.name, file: preview.relativeFile})),
+          previews: graph.previews.map((preview) => ({
+            id: preview.name,
+            file: preview.relativeFile,
+            usedBy: preview.usedBy ?? [],
+          })),
           brands: graph.brands.map((brand) => ({id: brand.name, file: brand.relativeFile})),
         },
       })};`,
@@ -124,11 +130,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 +212,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 +256,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 +280,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 +291,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>