@odori/cli 0.0.2

package/src/server.ts

@@ -0,0 +1,307 @@
+import {existsSync} from "node:fs";
+import {createRequire} from "node:module";
+import {fileURLToPath} from "node:url";
+import {createServer, type ViteDevServer} from "vite";
+import {registerProjectCues, renderedCue} from "./cues";
+import react from "@vitejs/plugin-react";
+import {readFile} from "node:fs/promises";
+import {dirname, resolve, sep} from "node:path";
+import {discoverProject, writeGenerated, type ProjectGraph} from "./discovery";
+import {loadConfig, type ResolvedConfig} from "./config";
+
+/**
+ * Studio is a directory of this package, not a package of its own.
+ *
+ * Both `src/` (in this repository) and `dist/` (once built) sit one level under
+ * the package root, so the same relative walk finds `studio/` from either.
+ */
+const cliRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const studioRoot = resolve(cliRoot, "studio");
+const studioEntry = resolve(studioRoot, "index.html");
+
+/**
+ * The tree this package is installed into: `node_modules` in a consumer, the
+ * repository root here. Vite is allowed to serve out of it because the runtime
+ * and the registry live beside this package rather than under it.
+ */
+const installRoot = resolve(cliRoot, "..", "..");
+
+const VIRTUAL_ID = "virtual:odori-project";
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+/**
+ * Where the runtime's source lives, when it is available as source.
+ *
+ * This used to be `studioRoot/../odori/src`, which is true in this repository
+ * and nowhere else: in a consumer, Studio sits at `node_modules/@odori/studio`
+ * and that path resolves to `node_modules/@odori/odori/src`, a directory that
+ * has never existed. Every install outside the monorepo failed on it.
+ *
+ * Resolving the package properly gives the right answer in both places, and
+ * the published package has no `src/index.tsx`, so a consumer gets `null` and
+ * the aliases below are simply not installed — Vite then resolves `odori`
+ * through its own exports map, which is what should happen.
+ */
+const runtimeSource = (root: string): string | null => {
+  for (const from of [resolve(root, "package.json"), import.meta.url]) {
+    try {
+      const manifest = createRequire(from).resolve("odori/package.json");
+      const src = resolve(manifest, "..", "src");
+      if (existsSync(resolve(src, "index.tsx"))) return src;
+    } catch {
+      // Not resolvable from here; try the next origin.
+    }
+  }
+  return null;
+};
+
+/**
+ * The project is injected as a virtual module of static imports. Studio itself
+ * stays a plain application: everything it knows comes from discovery.
+ */
+const odoriProjectPlugin = (config: ResolvedConfig, getGraph: () => ProjectGraph) => ({
+  name: "odori:project",
+  resolveId(id: string) {
+    return id === VIRTUAL_ID ? RESOLVED_ID : null;
+  },
+  load(id: string) {
+    if (id !== RESOLVED_ID) return null;
+    const graph = getGraph();
+    const fsPath = (file: string) => JSON.stringify(`/@fs${file}`);
+    return [
+      ...graph.videos.map(
+        (video) => `import ${video.identifier}, {metadata as ${video.identifier}Metadata} from ${fsPath(video.file)};`,
+      ),
+      ...graph.previews.map((preview) => `import ${preview.identifier} from ${fsPath(preview.file)};`),
+      ...graph.brands.map((brand) => `import * as ${brand.identifier} from ${fsPath(brand.file)};`),
+      "export const videos = [",
+      ...graph.videos.map(
+        (video) =>
+          `  {component: ${video.identifier}, metadata: {...${video.identifier}Metadata, id: ${video.identifier}Metadata.id || ${JSON.stringify(video.slug)}}},`,
+      ),
+      "];",
+      "export const componentPreviews = [",
+      ...graph.previews.map(
+        (preview) => `  {id: ${JSON.stringify(preview.name)}, preview: ${preview.identifier}.default ?? ${preview.identifier}},`,
+      ),
+      "];",
+      "export const brands = [",
+      ...graph.brands.map(
+        (brand) => `  ...Object.values(${brand.identifier}).filter((value) => value?.kind === "odori-brand"),`,
+      ),
+      "];",
+      `export const project = ${JSON.stringify({
+        root: config.root,
+        videosDir: config.videosDir,
+        exportDir: config.exportDir,
+        audioDir: config.audioDir,
+        docsUrl: config.docsUrl,
+        audio: graph.audio,
+        sourceHash: graph.sourceHash,
+        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})),
+          brands: graph.brands.map((brand) => ({id: brand.name, file: brand.relativeFile})),
+        },
+      })};`,
+    ].join("\n");
+  },
+});
+
+export type StudioServer = {
+  vite: ViteDevServer;
+  url: string;
+  graph: ProjectGraph;
+  close(): Promise<void>;
+};
+
+export const startStudioServer = async (
+  initialConfig: ResolvedConfig,
+  options: {port?: number; strictPort?: boolean; middleware?: (server: ViteDevServer) => void} = {},
+): Promise<StudioServer> => {
+  let config = initialConfig;
+  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,
+    configFile: false,
+    // Studio owns the fallback so an unknown asset can 404 instead of being
+    // answered with the app's HTML, which would only fail later at decode.
+    appType: "custom",
+    logLevel: "warn",
+    // The API middleware is installed through a plugin so it runs before
+    // Vite's own history fallback, which would otherwise answer with HTML.
+    plugins: [
+      react(),
+      odoriProjectPlugin(config, () => graph),
+      {name: "odori:api", configureServer: (server: ViteDevServer) => options.middleware?.(server)},
+      {
+        // Generated cues are rendered on demand and served from memory, so a
+        // preview hears the same bytes the encoder will mix. The URL carries a
+        // hash of the score, which makes it safe to cache forever.
+        name: "odori:generated-cues",
+        configureServer: (server: ViteDevServer) => () => {
+          server.middlewares.use((request, response, next) => {
+            const path = (request.url ?? "").split("?")[0];
+            if (!path.startsWith("/__odori/cue/")) return next();
+            const wav = renderedCue(path);
+            if (!wav) {
+              response.statusCode = 404;
+              response.setHeader("content-type", "text/plain");
+              response.end(`odori: no generated cue for ${path}`);
+              return;
+            }
+            response.statusCode = 200;
+            response.setHeader("content-type", "audio/wav");
+            response.setHeader("content-length", String(wav.byteLength));
+            response.setHeader("cache-control", "public, max-age=31536000, immutable");
+            response.end(Buffer.from(wav));
+          });
+        },
+      },
+      {
+        // A cue pointing at a file that is not there must fail as a missing
+        // file. Vite's history fallback would answer with the Studio's HTML,
+        // which an <audio> element accepts and then silently fails to decode,
+        // turning a typo in a brand's audio map into a preview with no sound
+        // and no error.
+        name: "odori:asset-404",
+        configureServer: (server: ViteDevServer) => () => {
+          server.middlewares.use((request, response, next) => {
+            const path = (request.url ?? "").split("?")[0];
+            const isAsset = /\.(?:mp3|m4a|wav|ogg|aac|flac|mp4|webm|mov|png|jpe?g|gif|webp|avif|svg|woff2?|ttf|otf)$/i.test(path);
+            if (!isAsset) return next();
+            response.statusCode = 404;
+            response.setHeader("content-type", "text/plain");
+            response.end(`odori: ${path} is not in public/`);
+          });
+        },
+      },
+    ],
+    // The project's public/ directory is served at the root, so brand fonts,
+    // logos, and footage resolve identically in preview and render.
+    publicDir: existsSync(resolve(config.root, "public")) ? resolve(config.root, "public") : false,
+    resolve: {
+      dedupe: ["react", "react-dom", "odori"],
+      // Only when the runtime is present as source. A consumer resolves the
+      // published package through its exports map instead.
+      alias: odoriSrc
+        ? [
+            {find: /^odori\/preview$/, replacement: resolve(odoriSrc, "preview.ts")},
+            {find: /^odori\/manifest$/, replacement: resolve(odoriSrc, "manifest.ts")},
+            {find: /^odori$/, replacement: resolve(odoriSrc, "index.tsx")},
+          ]
+        : [],
+    },
+    server: {
+      host: "127.0.0.1",
+      port: options.port ?? config.port,
+      strictPort: options.strictPort ?? false,
+      fs: {allow: [studioRoot, config.root, installRoot]},
+      watch: {ignored: [`${config.root}/${config.outDir}/**`]},
+    },
+    optimizeDeps: {include: ["react", "react-dom", "react/jsx-dev-runtime"]},
+  });
+
+  // Rediscover when video or preview entries appear or disappear.
+  const rediscover = async (file: string) => {
+    if (!file.startsWith(resolve(config.root, config.videosDir))) return;
+    const isEntry = file.endsWith("video.tsx") || file.endsWith(".preview.tsx") || file.includes(`${sep}brands${sep}`);
+    if (!isEntry) return;
+    try {
+      graph = await discoverProject(config);
+      await writeGenerated(config, graph);
+      await registerProjectCues(graph);
+    } 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.
+      vite.config.logger.warn(`[odori] rediscovery skipped: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    const module = vite.moduleGraph.getModuleById(RESOLVED_ID);
+    if (module) vite.moduleGraph.invalidateModule(module);
+    vite.ws.send({type: "full-reload"});
+  };
+  vite.watcher.on("add", (file) => void rediscover(file));
+  vite.watcher.on("unlink", (file) => void rediscover(file));
+  vite.watcher.add(resolve(config.root, config.videosDir));
+
+  // The config carries the asset map, so editing it changes which file a
+  // symbolic cue resolves to. Without this, a renamed asset keeps resolving to
+  // the URL the server read at startup, and the only symptom is silence.
+  const reloadConfig = async (file: string) => {
+    if (!/odori\.config\.(?:ts|mjs|js)$/.test(file)) return;
+    try {
+      config = await loadConfig(config.root);
+      graph = await discoverProject(config);
+      await writeGenerated(config, graph);
+      await registerProjectCues(graph);
+    } catch (error) {
+      vite.config.logger.warn(`[odori] config reload skipped: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    const module = vite.moduleGraph.getModuleById(RESOLVED_ID);
+    if (module) vite.moduleGraph.invalidateModule(module);
+    vite.ws.send({type: "full-reload"});
+  };
+  // 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);
+  };
+  vite.watcher.on("change", (file) => void refreshCues(file));
+
+  vite.watcher.on("change", (file) => void reloadConfig(file));
+  for (const name of ["odori.config.ts", "odori.config.mjs", "odori.config.js"]) {
+    vite.watcher.add(resolve(config.root, name));
+  }
+
+  // Routes are real paths, so anything that is not a file and not an internal
+  // Vite request renders the app.
+  vite.middlewares.use(async (request, response, next) => {
+    const url = (request.url ?? "/").split("?")[0];
+    // A path with a file extension is an asset request. If nothing served it by
+    // now the file is missing, and a 404 is more useful than the app's HTML.
+    const routable =
+      request.method === "GET" &&
+      !url.startsWith("/@") &&
+      !url.startsWith("/__odori") &&
+      !/\.[a-zA-Z0-9]+$/.test(url);
+
+    if (!routable) {
+      next();
+      return;
+    }
+
+    try {
+      const html = await readFile(studioEntry, "utf8");
+      response.statusCode = 200;
+      response.setHeader("content-type", "text/html");
+      response.end(await vite.transformIndexHtml(url, html));
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  await vite.listen();
+
+  const address = vite.resolvedUrls?.local[0] ?? `http://127.0.0.1:${options.port ?? config.port}`;
+  return {
+    vite,
+    url: address.replace(/\/$/, ""),
+    graph,
+    close: async () => {
+      await vite.close();
+    },
+  };
+};

package/studio/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Odori Studio</title>
+    <!--
+      Inlined, not a file: the dev server serves the *project*'s public/ at the
+      root (see odori-cli/src/server.ts), so a /icon.svg here would 404. A 128px
+      PNG rather than the mark's SVG, which is a hand-drawn trace and an order of
+      magnitude larger inline.
+    -->
+    <link rel="icon" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAARGVYSWZNTQAqAAAACAABh2kABAAAAAEAAAAaAAAAAAADoAEAAwAAAAEAAQAAoAIABAAAAAEAAACAoAMABAAAAAEAAACAAAAAAEiOBHcAAAGdaVRYdFhNTDpjb20uYWRvYmUueG1wAAAAAAA8eDp4bXBtZXRhIHhtbG5zOng9ImFkb2JlOm5zOm1ldGEvIiB4OnhtcHRrPSJYTVAgQ29yZSA2LjAuMCI+CiAgIDxyZGY6UkRGIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5vcmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyI+CiAgICAgIDxyZGY6RGVzY3JpcHRpb24gcmRmOmFib3V0PSIiCiAgICAgICAgICAgIHhtbG5zOmV4aWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20vZXhpZi8xLjAvIj4KICAgICAgICAgPGV4aWY6UGl4ZWxYRGltZW5zaW9uPjUxMjwvZXhpZjpQaXhlbFhEaW1lbnNpb24+CiAgICAgICAgIDxleGlmOlBpeGVsWURpbWVuc2lvbj41MTI8L2V4aWY6UGl4ZWxZRGltZW5zaW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KuC9IVwAAGapJREFUeAHtnQWwHEUTgCcEd3cJbsEJHtxdgwaCS3B3dy9ck8Ld3QMUEDzBLbi7O8zfX9c/j3uX3buZ9Xvvuupq7/ZmZ0d6etqnhxUwbei2IzBKt+15u+M6Am0E6OaI0EaANgJ08xHo5t1vU4A2AnTzEejm3W9TgDYCdPMR6Obdb1OAbo4Ao3b1/v/zzz/ml19+Md988435+uuvzccff2y++uor88cffxj+69GjhxljjDHMuOOOa8Ybbzwz0UQTmfHHH18/7nvPnj277DB1KQRgkt966y3z4osvmldeecW8//775rPPPjOff/65+f77783vv//uPZEgxQQTTGCmm24606dPHzP//PObJZdc0swxxxxm1FG7zrD1aGVbABP65JNPmscee8w89dRTZvjw4eaLL77oNMlM1iSTTGImnXRSvU422WRmwgkn1BU/5phj6mRiDoEiQClAlC+//FI/IA5UwwEUYZpppjFzzz23IsPSSy9t5p13XqUirkyrXVsOAX788Ufz8MMPm/vvv9888sgj5o033ugY86mnntrMMssspnfv3vqZffbZzfTTT28mnnhiJe+jjTZaR9lmX/7++29Fhg8++ECpCpTlhRdeME8//XQnJFtqqaXM2WefrZQBhGo1aBkEeOedd8w111xjLr/8csN3YK655tLVuPLKK5tFF11UJxuynSd8++23iggPPfSQIuCrr75q+vXrZ9Zee22lMOOMM45ZYIEF8mxCtnWzBVQZhMTb/v37W2HSMFvbUUYZxcpebC+55BL722+/ldr0f//91w4bNswOGDDAbrTRRla2Gm3jCiusYG+++WYrW1Sp7fN5ufEpVEaZZ5991m644YY6oEy8kHG7yy67WCHDloGvGvz000+KlLL6O9oszKMdOnRo1ZraqT2VQ4ARI0bYnXfe2QoXrgMpXLg94YQT7Icfftip4VX9wapn9cuWYGeYYQY7xRRT2OWWW84Kz1LJJlcGAf766y97xhlnWOHWdeJFFrfHHHOMFTGukgPn0yiRIOyll15qV1ppJbvFFltYkVLsp59+6vNoYWUqwQTK6ja77babuf3225XB2Wyzzcxhhx2mnHW2HE85tb322mvm5ZdfNu+++64qpFZffXWz/PLLl9OY+rcWhmoxLxoyZIideeaZddXPM8889u67744p2fq3L7zwQqVqoouwAwcOtKKzKL1TpW4BgwYNsmOPPbZO/nbbbWdFk1f6gOTdANFbWFEgaZ9Fq2ife+65vF/ZsP5SEAAuHsZOqJEye+eff37DRna1P5EYdtxxR+0/vA58QllQCgJcddVV2nnR3Nl77rmnrL6X/l6kBcRbFsKBBx5oRftYeJtKQYBNNtlEO73sssvajz76qPBOV+mFolq2M800k47H1ltvXbhyqxQEeP75561TmLACjjjiCAtZzAtOPPFEe9111+VVfep6RTqwYlNQJFh33XXtDz/8kLpO3wpKQQAaJzZ5u++++3YofBgAsej5tjuo3J577qnKmKCHCi7MeKDiZjtYbbXVrFglC2lBaQjgeseksxXQcTHd2kMOOSRzMnjTTTdZMePmSmVcf9JcURKJ34GOxcYbb2zF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" />
+    <script>
+      // Resolve the theme before the first paint, so a reload never flashes the
+      // opposite background while the bundle loads.
+      (function () {
+        var stored = null;
+        try {
+          stored = localStorage.getItem("odori-studio-theme");
+        } catch (error) {
+          stored = null;
+        }
+        var theme =
+          stored === "light" || stored === "dark"
+            ? stored
+            : matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light";
+        var root = document.documentElement;
+        root.dataset.theme = theme;
+        root.style.colorScheme = theme;
+        root.style.background = theme === "dark" ? "#000000" : "#ffffff";
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/studio/src/Studio.tsx

@@ -0,0 +1,192 @@
+import {useEffect, useRef, useState} from "react";
+import {componentPreviews, project, videos} from "virtual:odori-project";
+import {VideosView} from "./views/VideosView";
+import {ComponentsView} from "./views/ComponentsView";
+import {BrandsView} from "./views/BrandsView";
+import {AssetsView} from "./views/AssetsView";
+import {HomeView} from "./views/HomeView";
+import {CommandPalette} from "./components/CommandPalette";
+import {Wordmark} from "./components/Wordmark";
+import {Button, Icon, Kbd} from "./components/ui";
+import {useTheme, type Theme} from "./theme";
+
+const VIEWS = ["videos", "components", "brands", "assets"] as const;
+
+const THEMES: Array<{id: Theme; label: string; icon: "display" | "sun" | "moon"}> = [
+  {id: "system", label: "System", icon: "display"},
+  {id: "light", label: "Light", icon: "sun"},
+  {id: "dark", label: "Dark", icon: "moon"},
+];
+export type StudioView = (typeof VIEWS)[number] | "home";
+
+const ROUTES: readonly string[] = ["home", ...VIEWS];
+
+type Route = {view: StudioView; selection: string | null};
+
+/**
+ * Routes are real paths. The dev server serves the project's public directory
+ * at the root, so a request for an existing file still wins; anything else
+ * falls back to this app.
+ */
+const readRoute = (): Route => {
+  const [view, ...rest] = window.location.pathname.replace(/^\/+/, "").split("/");
+  return {
+    view: ROUTES.includes(view) ? (view as StudioView) : "home",
+    // A video id can contain a slash, so the remainder is the selection.
+    selection: rest.length > 0 ? decodeURIComponent(rest.join("/")) : null,
+  };
+};
+
+const pathFor = (view: StudioView, selection?: string | null): string =>
+  view === "home" ? "/" : `/${view}${selection ? `/${selection.split("/").map(encodeURIComponent).join("/")}` : ""}`;
+
+export const Studio = () => {
+  const [route, setRoute] = useState<Route>(readRoute);
+  const [paletteOpen, setPaletteOpen] = useState(false);
+  const [mode, setMode] = useState<"player" | "gallery">("player");
+  const search = useRef<HTMLInputElement>(null);
+  const {theme, setTheme} = useTheme();
+
+  const navigate = (view: StudioView, selection?: string | null) => {
+    const next: Route = {view, selection: selection ?? null};
+    const path = pathFor(view, next.selection);
+    // Keep the query, so a render-mode or debugging parameter survives a click.
+    if (path !== window.location.pathname) window.history.pushState(null, "", `${path}${window.location.search}`);
+    setRoute(next);
+  };
+
+  useEffect(() => {
+    const onPopState = () => setRoute(readRoute());
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        setPaletteOpen((value) => !value);
+      }
+      if ((event.metaKey || event.ctrlKey) && ["1", "2", "3", "4"].includes(event.key)) {
+        event.preventDefault();
+        navigate(VIEWS[Number(event.key) - 1]);
+      }
+      const target = event.target as HTMLElement | null;
+      const typing = Boolean(target && ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName));
+      if (typing || event.metaKey || event.ctrlKey) return;
+
+      if (event.key === "/") {
+        event.preventDefault();
+        search.current?.focus();
+      }
+      if (event.key.toLowerCase() === "g") {
+        setMode((value) => (value === "player" ? "gallery" : "player"));
+      }
+    };
+    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");
+
+  return (
+    <div className="studio">
+      <header className="topbar">
+        <button
+          type="button"
+          className="wordmark"
+          aria-label="Project overview"
+          data-active={route.view === "home" ? "true" : undefined}
+          onClick={() => navigate("home")}
+        >
+          <Wordmark />
+        </button>
+        <div className="views">
+          {VIEWS.map((view) => (
+            <Button key={view} active={view === route.view} onClick={() => navigate(view)}>
+              {view}
+            </Button>
+          ))}
+        </div>
+        <div className="topbar-right">
+          <div className="search">
+            <input
+              ref={search}
+              className="input"
+              placeholder="Search"
+              value=""
+              readOnly
+              onFocus={() => setPaletteOpen(true)}
+              onKeyDown={(event) => {
+                if (event.key === "Escape") event.currentTarget.blur();
+              }}
+            />
+            <Kbd>⌘K</Kbd>
+          </div>
+          <div className="tabs" role="group" aria-label="Theme">
+            {THEMES.map((option) => (
+              <Button
+                key={option.id}
+                icon
+                active={theme === option.id}
+                aria-pressed={theme === option.id}
+                aria-label={option.label}
+                title={`${option.label} theme`}
+                onClick={() => setTheme(option.id)}
+              >
+                <Icon name={option.icon} />
+              </Button>
+            ))}
+          </div>
+        </div>
+      </header>
+
+      <main className="main" data-single={singleColumn ? "true" : undefined}>
+        {route.view === "videos" ? (
+          <VideosView selection={route.selection} onSelect={(id) => navigate("videos", id)} mode={mode} />
+        ) : null}
+        {route.view === "components" ? (
+          <ComponentsView
+           
+            selection={route.selection}
+            onSelect={(id) => navigate("components", id)}
+            mode={mode}
+          />
+        ) : null}
+        {route.view === "brands" ? <BrandsView /> : null}
+        {route.view === "assets" ? <AssetsView /> : null}
+        {route.view === "home" ? <HomeView onOpen={(view, selection) => navigate(view, selection)} /> : null}
+      </main>
+
+      <footer className="statusbar">
+        <span>source {project.sourceHash.slice(0, 10)}</span>
+        <a className="statusbar-link" href={project.docsUrl} target="_blank" rel="noreferrer">
+          Documentation
+          <Icon name="external" />
+        </a>
+        <span className="spacer" />
+        <span>space play</span>
+        <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);
+        }}
+        onView={(view) => navigate(view as StudioView)}
+      />
+    </div>
+  );
+};

package/studio/src/components/AudioClip.tsx

@@ -0,0 +1,64 @@
+import {useEffect, useRef, useState} from "react";
+import {Waveform, useAudioPeaks} from "./Waveform";
+import {Button, Icon} from "./ui";
+
+/** Seconds, at the precision a short cue actually needs. */
+export const clipLength = (seconds: number) => (seconds >= 10 ? `${seconds.toFixed(0)}s` : `${seconds.toFixed(2)}s`);
+
+/**
+ * Audition one file without leaving Studio.
+ *
+ * The element is created on demand rather than per row, so a library of
+ * hundreds of sounds costs nothing until something is played.
+ */
+export const AudioClip = ({url, label, shape}: {url: string; label?: string; shape?: boolean}) => {
+  const element = useRef<HTMLAudioElement | null>(null);
+  const [playing, setPlaying] = useState(false);
+  const {duration} = useAudioPeaks(url);
+
+  useEffect(
+    () => () => {
+      element.current?.pause();
+      element.current = null;
+    },
+    [],
+  );
+
+  const toggle = () => {
+    if (!element.current) {
+      element.current = new window.Audio(url);
+      element.current.addEventListener("ended", () => setPlaying(false));
+    }
+    if (playing) {
+      element.current.pause();
+      setPlaying(false);
+      return;
+    }
+    void element.current.play().then(
+      () => setPlaying(true),
+      // Autoplay policy rejects until the page has been interacted with. The
+      // click that got here is that interaction, so a failure is a real one.
+      () => setPlaying(false),
+    );
+  };
+
+  const control = (
+    <Button icon aria-label={playing ? `Pause ${label ?? url}` : `Play ${label ?? url}`} onClick={toggle}>
+      <Icon name={playing ? "pause" : "play"} />
+    </Button>
+  );
+
+  if (!shape) return control;
+
+  // A third of a second at low level is over before the button finishes
+  // changing, so the clip shows its own shape and length.
+  return (
+    <div className="clip">
+      {control}
+      <div className="clip-shape">
+        <Waveform url={url} />
+      </div>
+      {duration > 0 ? <span className="clip-length">{clipLength(duration)}</span> : null}
+    </div>
+  );
+};