@odori/cli 0.0.2

package/src/commands/shared.ts

@@ -0,0 +1,96 @@
+import {resolveEntryLayout, type AudioCue, type ManifestAudioCue, type Brand} from "odori";
+import {loadConfig, type ResolvedConfig} from "../config";
+import {registerCues} from "../cues";
+import {discoverProject, type ProjectGraph} from "../discovery";
+import {loadVideos, type LoadedVideo} from "../project";
+import {openRenderPage, readAudio, readTimeline, type RenderTarget} from "../render";
+import {startStudioServer, type StudioServer} from "../server";
+
+export type Context = {config: ResolvedConfig; graph: ProjectGraph; videos: LoadedVideo[]};
+
+export const createContext = async (root = process.cwd()): Promise<Context> => {
+  const config = await loadConfig(root);
+  const graph = await discoverProject(config);
+  const videos = await loadVideos(graph);
+  // Generated cues are served by their content hash, so the server has to know
+  // which scores exist before a preview asks for one.
+  const brands = new Map<string, Brand>();
+  for (const video of videos) {
+    const layout = resolveEntryLayout(video.entry);
+    brands.set(layout.brand.name, layout.brand);
+    registerCues([layout.brand], layout.format.fps);
+  }
+  return {config, graph, videos};
+};
+
+export const targetFor = (
+  video: LoadedVideo,
+  input?: Record<string, unknown>,
+  prepared?: unknown,
+  audio?: ManifestAudioCue[],
+  scenes?: Array<{id: string; start: number; durationInFrames: number}>,
+): RenderTarget => {
+  const layout = resolveEntryLayout(video.entry);
+  return {
+    videoId: video.entry.metadata.id,
+    width: layout.format.width,
+    height: layout.format.height,
+    fps: layout.format.fps,
+    durationInFrames: video.durationInFrames,
+    input,
+    prepared,
+    audio,
+    scenes,
+    targetLufs: layout.audio.targetLufs,
+  };
+};
+
+/**
+ * `metadata.duration` is authoritative. When it is absent, the compiled
+ * timeline reported by the runtime is used instead.
+ */
+export type CompileResult = {
+  durationInFrames: number;
+  scenes: Array<{id: string; start: number; durationInFrames: number}>;
+  audio: AudioCue[];
+};
+
+/**
+ * Compile the timeline and the audio track in the browser, where the runtime
+ * already knows how to lay both out. `metadata.duration` stays authoritative
+ * when it is declared.
+ */
+export const compileInBrowser = async (
+  origin: string,
+  target: RenderTarget,
+  config: ResolvedConfig,
+): Promise<CompileResult> => {
+  const {browser, page} = await openRenderPage(origin, target, config);
+  try {
+    const timeline = await readTimeline(page);
+    const track = await readAudio(page);
+    return {
+      durationInFrames: target.durationInFrames || timeline.durationInFrames,
+      scenes: timeline.scenes.map((scene) => ({
+        id: scene.id,
+        start: scene.start,
+        durationInFrames: scene.durationInFrames,
+      })),
+      audio: track.cues,
+    };
+  } finally {
+    await browser.close();
+  }
+};
+
+export const withServer = async <Value>(
+  config: ResolvedConfig,
+  handler: (server: StudioServer) => Promise<Value>,
+): Promise<Value> => {
+  const server = await startStudioServer(config, {port: 0});
+  try {
+    return await handler(server);
+  } finally {
+    await server.close();
+  }
+};

package/src/commands/still.ts

@@ -0,0 +1,40 @@
+import {resolve} from "node:path";
+import {log} from "../log";
+import {findVideo, freezeManifest, outputName} from "../project";
+import {renderStill} from "../render";
+import {compileInBrowser, createContext, targetFor, withServer} from "./shared";
+
+export const stillCommand = async (
+  id: string,
+  options: {frame?: number; output?: string; input?: Record<string, unknown>} = {},
+) => {
+  const frame = options.frame ?? 0;
+  // A frame is an index into the timeline. Checking it first means a typo
+  // costs nothing: no discovery, no dev server, no browser.
+  if (!Number.isInteger(frame) || frame < 0) {
+    throw new Error(`Frame must be a whole number of frames from the start, got ${String(frame)}.`);
+  }
+
+  const {config, graph, videos} = await createContext();
+  const video = findVideo(videos, id);
+
+  const output = await withServer(config, async (server) => {
+    const {durationInFrames, scenes, audio} = await compileInBrowser(server.url, targetFor(video, options.input), config);
+    const {manifest, input, prepared} = await freezeManifest(
+      {...video, durationInFrames},
+      graph,
+      config,
+      options.input ?? {},
+      {scenes, audio},
+    );
+    if (frame >= manifest.format.durationInFrames) {
+      throw new Error(`Frame ${frame} is past the last frame (${manifest.format.durationInFrames - 1}).`);
+    }
+    const target = targetFor({...video, durationInFrames: manifest.format.durationInFrames}, input, prepared);
+    const file = resolve(config.root, options.output ?? `${config.exportDir}/${outputName(id)}-${frame}.png`);
+    return renderStill(server.url, target, frame, file, config);
+  });
+
+  log.success(`Still frame ${frame} written to ${output}`);
+  return output;
+};

package/src/commands/test.ts

@@ -0,0 +1,265 @@
+import {isOdoriSchema, resolveEntryLayout} from "odori";
+import {log} from "../log";
+import {openRenderPage, readAudio, readTimeline, seekTo} from "../render";
+import {checkAudioWindows, checkInstalledContracts} from "../contracts";
+import {checkDeterminism} from "../determinism";
+import {createContext, targetFor, withServer} from "./shared";
+import type {LoadedVideo} from "../project";
+import type {ResolvedConfig} from "../config";
+
+type Failure = {video: string; message: string};
+
+type FrameReport = {overflow: string[]; small: string[]; empty: boolean; painted: number};
+
+/**
+ * A fingerprint of every canvas on the frame.
+ *
+ * A canvas is the one surface whose contents the DOM cannot describe, so the
+ * only way to know it drew what the frame asked for is to read the pixels. The
+ * hash is cheap and coarse — a sample grid, not the whole buffer — which is
+ * enough to catch the failure that matters: a canvas that paints something
+ * different the second time the same frame is rendered.
+ */
+const CANVAS_SCRIPT = `(() => {
+  var root = document.querySelector("[data-odori-video]");
+  if (!root) return [];
+
+  // Only canvases that are actually on screen. The runtime mounts every scene
+  // a second time, hidden, to collect audio cues, and a hidden copy is not
+  // what the export captures.
+  var canvases = Array.prototype.slice.call(root.querySelectorAll("canvas")).filter(function (canvas) {
+    var box = canvas.getBoundingClientRect();
+    if (box.width === 0 || box.height === 0) return false;
+    var style = getComputedStyle(canvas);
+    return style.visibility !== "hidden" && Number(style.opacity) > 0.02;
+  });
+
+  return canvases.map(function (canvas, index) {
+    var context = canvas.getContext("2d");
+    if (!context || canvas.width === 0 || canvas.height === 0) {
+      return {index: index, hash: "no-context", blank: true};
+    }
+    var data;
+    try {
+      data = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    } catch (error) {
+      return {index: index, hash: "tainted", blank: false};
+    }
+
+    // A prime stride over the whole buffer rather than a coarse grid: a grid
+    // steps over thin content and calls a drawn canvas blank, which is a
+    // failure report about the checker rather than about the video.
+    var pixels = canvas.width * canvas.height;
+    var stride = 97;
+    var hash = 5381;
+    var opaque = 0;
+    for (var pixel = 0; pixel < pixels; pixel += stride) {
+      var offset = pixel * 4;
+      if (data[offset + 3] > 8) opaque += 1;
+      hash =
+        ((hash << 5) + hash + data[offset] + data[offset + 1] * 3 + data[offset + 2] * 7 + data[offset + 3] * 11) | 0;
+    }
+    return {index: index, hash: String(hash), blank: opaque === 0};
+  });
+})()`;
+
+type CanvasReport = Array<{index: number; hash: string; blank: boolean}>;
+
+/**
+ * Evaluated as source in the page so no bundler helpers leak into the browser.
+ * Only content a viewer can actually read or see is worth flagging.
+ */
+const FRAME_SCRIPT = `(() => {
+  var root = document.querySelector("[data-odori-video]");
+  if (!root) return {overflow: [], small: [], empty: true, painted: 0};
+
+  var bounds = root.getBoundingClientRect();
+  var overflow = [];
+  var small = [];
+  var painted = 0;
+  var nodes = Array.prototype.slice.call(root.querySelectorAll("*"));
+
+  for (var index = 0; index < nodes.length; index += 1) {
+    var node = nodes[index];
+    var box = node.getBoundingClientRect();
+    if (box.width === 0 || box.height === 0) continue;
+    var style = getComputedStyle(node);
+    if (style.visibility === "hidden" || Number(style.opacity) < 0.02) continue;
+    painted += 1;
+
+    var media = ["IMG", "SVG", "CANVAS", "VIDEO"].indexOf(node.tagName) >= 0;
+    var text = "";
+    for (var child = 0; child < node.childNodes.length; child += 1) {
+      var childNode = node.childNodes[child];
+      if (childNode.nodeType === 3) text += childNode.textContent || "";
+    }
+    text = text.trim();
+    if (!media && text.length === 0) continue;
+
+    var label = text.length > 0 ? '"' + text.slice(0, 32) + '"' : "<" + node.tagName.toLowerCase() + ">";
+    if (
+      box.right > bounds.right + 1 ||
+      box.left < bounds.left - 1 ||
+      box.bottom > bounds.bottom + 1 ||
+      box.top < bounds.top - 1
+    ) {
+      if (overflow.indexOf(label) < 0) overflow.push(label);
+    }
+
+    // Normalize against the shorter side, the same reference useDesignScale
+    // uses, so a vertical cut is not judged as if it were letterboxed.
+    var reference = Math.min(bounds.width, bounds.height);
+    var relative = (parseFloat(style.fontSize) / reference) * 1080;
+    if (text.length > 0 && relative > 0 && relative < 20) {
+      var note = label + " at " + Math.round(relative) + "px";
+      if (small.indexOf(note) < 0) small.push(note);
+    }
+  }
+
+  return {overflow: overflow.slice(0, 5), small: small.slice(0, 5), empty: false, painted: painted};
+})()`;
+
+/**
+ * Contract checks plus representative frames: mount, sample, and look for
+ * empty frames and content that escapes the canvas.
+ */
+const testVideo = async (
+  origin: string,
+  video: LoadedVideo,
+  config: ResolvedConfig,
+  failures: Failure[],
+  quiet = false,
+): Promise<void> => {
+  const id = video.entry.metadata.id;
+  const layout = resolveEntryLayout(video.entry);
+
+  if (isOdoriSchema(video.entry.metadata.schema)) {
+    const result = video.entry.metadata.schema.safeParse(video.entry.metadata.defaultProps ?? {});
+    if (!result.success) failures.push({video: id, message: `defaultProps fail the schema: ${result.issues.join("; ")}`});
+  }
+
+  const {browser, page} = await openRenderPage(origin, targetFor(video), config);
+  try {
+    const timeline = await readTimeline(page);
+    // The track is compiled by the same pass the player and the encoder read,
+    // so a window that outlasts its sound is caught here rather than heard.
+    failures.push(...checkAudioWindows((await readAudio(page)).cues, layout.brand, id));
+    const total = video.durationInFrames || timeline.durationInFrames;
+    if (!total) {
+      failures.push({video: id, message: "No duration could be resolved."});
+      return;
+    }
+    if (video.durationInFrames && timeline.durationInFrames && video.durationInFrames !== timeline.durationInFrames) {
+      failures.push({
+        video: id,
+        message: `metadata.duration is ${video.durationInFrames} frames but scenes total ${timeline.durationInFrames}.`,
+      });
+    }
+
+    const samples = [0, Math.floor(total / 4), Math.floor(total / 2), Math.floor((total * 3) / 4), total - 1];
+    for (const frame of [...new Set(samples)]) {
+      await seekTo(page, frame);
+      const result = (await page.evaluate(FRAME_SCRIPT)) as FrameReport;
+      if (result.empty) failures.push({video: id, message: `Frame ${frame} rendered no video root.`});
+      if (!result.empty && result.painted < 2) {
+        failures.push({video: id, message: `Frame ${frame} is blank.`});
+      }
+      for (const item of result.overflow) {
+        failures.push({
+          video: id,
+          message: `Frame ${frame}: ${item} escapes the ${layout.format.width}x${layout.format.height} canvas.`,
+        });
+      }
+      for (const item of result.small) {
+        failures.push({video: id, message: `Frame ${frame}: ${item} is too small to read at 1080p.`});
+      }
+
+      // Canvas parity: the same frame, rendered twice, has to produce the same
+      // pixels. A canvas animated by requestAnimationFrame or a wall clock
+      // passes every other check here and then differs between the workers
+      // that render neighbouring chunks of the export.
+      const canvases = (await page.evaluate(CANVAS_SCRIPT)) as CanvasReport;
+      if (canvases.length > 0) {
+        // Seek away and back, so the second read is a real re-render rather
+        // than a second look at the same paint.
+        await seekTo(page, frame === 0 ? Math.min(total - 1, frame + 1) : frame - 1);
+        await seekTo(page, frame);
+        const again = (await page.evaluate(CANVAS_SCRIPT)) as CanvasReport;
+
+        for (const canvas of canvases) {
+          const second = again.find((item) => item.index === canvas.index);
+          if (canvas.blank) {
+            failures.push({video: id, message: `Frame ${frame}: canvas ${canvas.index} drew nothing.`});
+            continue;
+          }
+          if (canvas.hash === "tainted") {
+            failures.push({
+              video: id,
+              message: `Frame ${frame}: canvas ${canvas.index} is tainted by a cross-origin draw, so the export cannot read it. Serve the image from public/ or inline it as a data URL.`,
+            });
+            continue;
+          }
+          if (second && second.hash !== canvas.hash) {
+            failures.push({
+              video: id,
+              message:
+                `Frame ${frame}: canvas ${canvas.index} drew differently the second time. ` +
+                "A canvas must be a function of the frame: draw from useFrame() through useCanvas(), not from requestAnimationFrame or a clock.",
+            });
+          }
+        }
+      }
+    }
+    if (!quiet) log.success(`${id}: ${[...new Set(samples)].length} frames sampled across ${total} frames`);
+  } finally {
+    await browser.close();
+  }
+};
+
+export const testCommand = async (id?: string, options: {json?: boolean} = {}) => {
+  const {config, videos} = await createContext();
+  const selected = id ? videos.filter((video) => video.entry.metadata.id === id) : videos;
+  if (selected.length === 0) throw new Error(id ? `Unknown video "${id}".` : "No videos discovered.");
+
+  const failures: Failure[] = [];
+  // Contracts are checked before a browser starts: a missing cue is a fact
+  // about the project, not about a frame.
+  failures.push(...(await checkInstalledContracts(config, selected)));
+
+  // So is a wall clock in a composition. It would render fine here and differ
+  // on the next machine, which is the failure mode a test is for.
+  for (const finding of await checkDeterminism(config)) {
+    failures.push({
+      video: `${finding.file}:${finding.line}`,
+      message: `${finding.message}\n    ${finding.source}`,
+    });
+  }
+
+  await withServer(config, async (server) => {
+    for (const video of selected) await testVideo(server.url, video, config, failures, options.json === true);
+  });
+
+  if (options.json === true) {
+    // One object, so a CI step can read a result without scraping lines. It
+    // goes to stdout alone; everything human went to stderr or was suppressed.
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: failures.length === 0,
+          videos: selected.map((video) => video.entry.metadata.id),
+          failures,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    if (failures.length > 0) throw new Error(`${failures.length} check${failures.length === 1 ? "" : "s"} failed.`);
+    return;
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) log.error(`${failure.video}: ${failure.message}`);
+    throw new Error(`${failures.length} check${failures.length === 1 ? "" : "s"} failed.`);
+  }
+  log.success(`All checks passed for ${selected.length} video${selected.length === 1 ? "" : "s"}.`);
+};

package/src/commands/update.ts

@@ -0,0 +1,183 @@
+import {mkdir, readFile, writeFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {relative, resolve} from "node:path";
+import {hashString} from "odori";
+import {loadConfig, type ResolvedConfig} from "../config";
+import {countChanges, diffLines, formatDiff} from "../diff";
+import {normalizeComponentName, resolveItem, resolveRegistry} from "../registry-source";
+import {log} from "../log";
+
+export type Provenance = Record<
+  string,
+  {source: string; version: string; installedAt: string; hashes: Record<string, string>}
+>;
+
+export type ComponentState = "pristine" | "modified" | "outdated" | "diverged" | "missing";
+
+export type ComponentStatus = {
+  name: string;
+  state: ComponentState;
+  files: Array<{
+    file: string;
+    localPath: string;
+    /** Upstream source itself. The registry is documents now, not a directory. */
+    content: string;
+    local: string | null;
+    installed: string | null;
+    upstream: string;
+  }>;
+};
+
+const provenanceFile = (config: ResolvedConfig) => resolve(config.root, config.outDir, "components.json");
+
+export const readProvenance = async (config: ResolvedConfig): Promise<Provenance> => {
+  const file = provenanceFile(config);
+  if (!existsSync(file)) return {};
+  return JSON.parse(await readFile(file, "utf8")) as Provenance;
+};
+
+export const writeProvenance = async (config: ResolvedConfig, provenance: Provenance) => {
+  await mkdir(resolve(config.root, config.outDir), {recursive: true});
+  await writeFile(provenanceFile(config), `${JSON.stringify(provenance, null, 2)}\n`, "utf8");
+};
+
+/**
+ * Compare installed component source with the version that was installed and
+ * with the version the registry ships today.
+ *
+ * - pristine: identical everywhere
+ * - modified: the project edited it, upstream has not moved
+ * - outdated: upstream moved, the project did not edit it
+ * - diverged: both moved, so an update would overwrite local work
+ */
+export const componentStatus = async (config: ResolvedConfig, only?: string[]): Promise<ComponentStatus[]> => {
+  const {items: registry} = await resolveRegistry(config);
+  const provenance = await readProvenance(config);
+  const wanted = only?.map(normalizeComponentName);
+  const names = Object.keys(provenance).filter((name) => !wanted || wanted.includes(name));
+
+  const statuses: ComponentStatus[] = [];
+  for (const name of names) {
+    const component = registry.find((item) => item.name === name);
+    if (!component) continue;
+
+    // One document per component carries every file's contents, so upstream is
+    // read once here rather than opened per file.
+    const {item} = await resolveItem(config, name);
+    const upstreamFiles = new Map(item.files.map((file) => [file.path.split("/").pop() ?? file.path, file.content]));
+
+    const files = await Promise.all(
+      component.files.map(async (file) => {
+        const localPath = resolve(config.root, config.componentsDir, name, file);
+        const content = upstreamFiles.get(file);
+        if (content === undefined) throw new Error(`The registry document for "${name}" has no file named ${file}.`);
+        const local = existsSync(localPath) ? hashString(await readFile(localPath, "utf8")) : null;
+        return {
+          file,
+          localPath,
+          content,
+          local,
+          installed: provenance[name]?.hashes[file] ?? null,
+          upstream: hashString(content),
+        };
+      }),
+    );
+
+    const missing = files.some((file) => file.local === null);
+    const modified = files.some((file) => file.local !== null && file.local !== file.installed);
+    const outdated = files.some((file) => file.installed !== file.upstream);
+    const state: ComponentState = missing
+      ? "missing"
+      : modified && outdated
+        ? "diverged"
+        : modified
+          ? "modified"
+          : outdated
+            ? "outdated"
+            : "pristine";
+
+    statuses.push({name, state, files});
+  }
+  return statuses.sort((left, right) => left.name.localeCompare(right.name));
+};
+
+const LABELS: Record<ComponentState, string> = {
+  pristine: "up to date",
+  modified: "modified locally",
+  outdated: "update available",
+  diverged: "modified locally and updated upstream",
+  missing: "files missing",
+};
+
+export const diffCommand = async (names: string[], options: {full?: boolean} = {}) => {
+  const config = await loadConfig(process.cwd());
+  const statuses = await componentStatus(config, names.length > 0 ? names : undefined);
+  if (statuses.length === 0) {
+    log.detail("No registry components are installed yet. Run odori add first.");
+    return;
+  }
+
+  for (const status of statuses) {
+    log.title(`@odori/${status.name}  ${LABELS[status.state]}`);
+    for (const file of status.files) {
+      if (file.local === null) {
+        log.error(`  ${file.file} is missing from ${relative(config.root, resolve(file.localPath, ".."))}`);
+        continue;
+      }
+      if (file.local === file.upstream) {
+        log.detail(`  ${file.file} identical to upstream`);
+        continue;
+      }
+      const lines = diffLines(await readFile(file.localPath, "utf8"), file.content);
+      const {added, removed} = countChanges(lines);
+      log.info(`  ${file.file}  +${added} -${removed} against upstream`);
+      if (options.full) for (const line of formatDiff(lines)) log.detail(`    ${line}`);
+    }
+  }
+  if (!options.full) log.detail("Pass --full to print the diff.");
+};
+
+export const updateCommand = async (names: string[], options: {force?: boolean} = {}) => {
+  const config = await loadConfig(process.cwd());
+  const statuses = await componentStatus(config, names.length > 0 ? names : undefined);
+  if (statuses.length === 0) {
+    log.detail("No registry components are installed yet. Run odori add first.");
+    return;
+  }
+
+  const provenance = await readProvenance(config);
+  let updated = 0;
+  let skipped = 0;
+
+  for (const status of statuses) {
+    if (status.state === "pristine") {
+      log.detail(`@odori/${status.name} is up to date`);
+      continue;
+    }
+    if (status.state === "modified") {
+      log.detail(`@odori/${status.name} is modified locally, and upstream has not changed`);
+      continue;
+    }
+    if ((status.state === "diverged" || status.state === "missing") && !options.force) {
+      log.warn(`@odori/${status.name}: ${LABELS[status.state]}. Review with odori diff ${status.name}, then use --force.`);
+      skipped += 1;
+      continue;
+    }
+
+    for (const file of status.files) {
+      await mkdir(resolve(file.localPath, ".."), {recursive: true});
+      await writeFile(file.localPath, file.content, "utf8");
+    }
+    provenance[status.name] = {
+      source: `@odori/${status.name}`,
+      version: "0.1.0",
+      installedAt: new Date().toISOString(),
+      hashes: Object.fromEntries(status.files.map((file) => [file.file, file.upstream])),
+    };
+    updated += 1;
+    log.success(`@odori/${status.name} updated`);
+  }
+
+  await writeProvenance(config, provenance);
+  log.detail(`${updated} updated, ${skipped} left for review.`);
+};

package/src/config.ts

@@ -0,0 +1,84 @@
+import {existsSync} from "node:fs";
+import {resolve} from "node:path";
+import {pathToFileURL} from "node:url";
+
+export type OdoriConfig = {
+  /** Source root that contains video entries and video components. */
+  videosDir: string;
+  /** Generated output directory. Never edited or committed. */
+  outDir: string;
+  /** Where exports are written. */
+  exportDir: string;
+  /** Registry components are copied here. */
+  componentsDir: string;
+  /** Audio library, discovered so Studio can list and audition it. Served from public/. */
+  audioDir: string;
+  /** Studio dev server port. */
+  port: number;
+  /** Where Studio's docs link points. Defaults to the hosted docs site. */
+  docsUrl: string;
+  /** Open Studio in the default browser when `odori dev` starts. */
+  open?: boolean;
+  /** Chrome or Chromium executable used by the render worker. */
+  chromePath?: string;
+  /**
+   * FFmpeg executable used to encode. Set it to pin a build; leave it and
+   * Odori uses its own managed copy, which is what keeps two machines
+   * producing the same file.
+   */
+  ffmpegPath?: string;
+  /** Static asset references available to every video. */
+  assets?: Array<{reference: string; url: string}>;
+  /** Parallel render workers. Defaults to the machine's spare cores, capped at four. */
+  concurrency?: number;
+  /** x264 preset for exports. Defaults to medium. */
+  preset?: string;
+  /** Default container and codec: mp4, webm, prores, gif, or png. */
+  format?: string;
+  /**
+   * Where `odori add` fetches components from. Point it at a fork, a mirror,
+   * or a pinned version; `ODORI_REGISTRY` overrides it for one command.
+   */
+  registryUrl?: string;
+  /** Reuse the previous frame when the rendered picture is unchanged. Defaults to true. */
+  skipUnchangedFrames?: boolean;
+  /** Reuse encoded chunks whose frames still look identical. Defaults to true. */
+  cacheChunks?: boolean;
+};
+
+export const defaultConfig: OdoriConfig = {
+  videosDir: "videos",
+  outDir: ".odori",
+  exportDir: "out",
+  componentsDir: "videos/components",
+  audioDir: "public/audio",
+  port: 4300,
+  docsUrl: "https://odori.dev/docs",
+};
+
+const CHROME_CANDIDATES = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+];
+
+export const resolveChromePath = (configured?: string): string | undefined => {
+  const candidates = [configured, process.env.ODORI_CHROME, ...CHROME_CANDIDATES].filter(Boolean) as string[];
+  return candidates.find((candidate) => existsSync(candidate));
+};
+
+export type ResolvedConfig = OdoriConfig & {root: string; configPath?: string};
+
+export const loadConfig = async (root: string): Promise<ResolvedConfig> => {
+  for (const name of ["odori.config.ts", "odori.config.mjs", "odori.config.js"]) {
+    const configPath = resolve(root, name);
+    if (!existsSync(configPath)) continue;
+    const loaded = (await import(pathToFileURL(configPath).href)) as {default?: Partial<OdoriConfig>};
+    return {...defaultConfig, ...(loaded.default ?? {}), root, configPath};
+  }
+  return {...defaultConfig, root};
+};
+
+export const defineConfig = (config: Partial<OdoriConfig>): Partial<OdoriConfig> => config;