@odori/cli 0.0.3 → 0.0.5

package/src/registry-source.ts

@@ -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;
@@ -123,6 +137,7 @@ type RegistryItemDocument = {
     namespaced?: string;
     contract?: RegistryComponent["contract"];
     cue?: {name: string; export: string};
+    asset?: RegistryAsset;
     integrity?: string;
   };
 };
@@ -132,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));
@@ -149,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),

package/src/render.ts

@@ -469,6 +469,13 @@ export type RenderOptions = {
   /** Container and codec. Defaults to H.264 in MP4. */
   format?: VideoFormat;
   skipUnchangedFrames?: boolean;
+  /**
+   * Mix the composition's cues into the file. Defaults to true, because the
+   * score is part of the video. Set false for a silent cut: a loop for a
+   * landing page, a clip going into an editor that has its own audio, or a
+   * reviewer who just wants the picture.
+   */
+  audio?: boolean;
   /** Reuse encoded chunks whose frames still look identical. */
   cache?: boolean;
   signal?: AbortSignal;
@@ -571,7 +578,7 @@ export const renderMovie = async (
     const captureMs = performance.now() - captureStart;
     onProgress?.(1, "encoding");
 
-    const mixInputs: MixInput[] = (target.audio ?? [])
+    const mixInputs: MixInput[] = (options.audio === false ? [] : (target.audio ?? []))
       .map((cue) => {
         const file = resolveCueFile(config, cue.src);
         if (!file) log.warn(`Skipping audio cue ${cue.src}: only project-local files can be encoded.`);

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})),
         },
       })};`,

package/studio/src/Studio.tsx

@@ -8,15 +8,11 @@ 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";
+import {Settings} from "./components/Settings";
+import {useTheme} 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];
@@ -48,7 +44,9 @@ export const Studio = () => {
   const routeRef = useRef(route);
   routeRef.current = route;
   const search = useRef<HTMLInputElement>(null);
-  const {theme, setTheme} = useTheme();
+  // Mounted here as well as in the menu so the stored theme is applied on
+  // load, whether or not anybody opens settings.
+  useTheme();
 
   const navigate = (view: StudioView, selection?: string | null) => {
     const next: Route = {view, selection: selection ?? null};
@@ -132,21 +130,7 @@ export const Studio = () => {
             />
             <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>
+          <Settings />
         </div>
       </header>
 

package/studio/src/components/ExportPanel.tsx

@@ -65,24 +65,82 @@ export const ExportPanel = ({
 }) => {
   const [job, setJob] = useState<JobState | null>(null);
   const [busy, setBusy] = useState(false);
+  /** Set when a job stops reporting progress, so a wedge reads as a wedge. */
+  const [stalled, setStalled] = useState(false);
+  /* Sound is part of the video, so it ships unless it is turned off. GIF has
+     no audio track at all and a still is one frame, so the choice only exists
+     where it means something. */
+  const [sound, setSound] = useState(true);
   const [format, setFormat] = useState<Format>("mp4");
   const [quality, setQuality] = useState<Quality>("studio");
   const [scale, setScale] = useState(1);
   const [notice, setNotice] = useState<string | null>(null);
 
+  /**
+   * Watch a job until it finishes, and say so if it does not.
+   *
+   * The old loop treated every unreadable response as "try again" and, after
+   * fifteen minutes of that, returned without a word. A dev server restarted
+   * mid-export takes its job records with it, so what you saw was a bar frozen
+   * at whatever percentage it had reached, no error, and no end: the export
+   * looked like it was still going hours later. A watcher that cannot see the
+   * job has to say the job is unwatchable.
+   */
   const poll = async (id: string) => {
-    for (let attempt = 0; attempt < 900; attempt += 1) {
+    let unreachable = 0;
+    let last = -1;
+    let stalledFor = 0;
+
+    for (let attempt = 0; attempt < 1800; attempt += 1) {
       await new Promise((wait) => setTimeout(wait, 1000));
-      const response = await fetch(`/__odori/jobs/${id}`);
-      if (!response.ok) continue;
-      const payload = (await response.json()) as JobState;
+      let payload: JobState | null = null;
+      try {
+        const response = await fetch(`/__odori/jobs/${id}`);
+        if (response.ok) payload = (await response.json()) as JobState;
+      } catch {
+        // Network error and 404 are the same thing here: no news about the job.
+      }
+
+      if (!payload) {
+        unreachable += 1;
+        // Ten seconds of silence is a server that went away, not a slow reply.
+        if (unreachable >= 10) {
+          setJob((current) => ({
+            ...(current ?? {id, progress: 0}),
+            status: "failed",
+            error:
+              "Lost contact with the dev server, so this export can no longer be tracked. It may still have finished; check the out directory, or run odori jobs.",
+          }));
+          return;
+        }
+        continue;
+      }
+
+      unreachable = 0;
       setJob(payload);
       if (payload.status === "ready" || payload.status === "failed") return;
+
+      /* A long render is normal; a silent one is the thing worth naming. The
+         encoder reports every five percent, so two minutes without a number
+         means something is wedged rather than slow. */
+      if (payload.progress === last) stalledFor += 1;
+      else {
+        stalledFor = 0;
+        last = payload.progress;
+      }
+      setStalled(stalledFor >= 120);
     }
+
+    setJob((current) => ({
+      ...(current ?? {id, progress: 0}),
+      status: "failed",
+      error: "Stopped watching after thirty minutes. Run odori jobs to see whether it is still going.",
+    }));
   };
 
   const post = async (path: string, body?: unknown) => {
     setBusy(true);
+    setStalled(false);
     setJob({id: "pending", status: "queued", progress: 0});
     try {
       const response = await fetch(path, {
@@ -135,7 +193,7 @@ export const ExportPanel = ({
   const run = async () => {
     setNotice(null);
     if (format === "frame") return post("/__odori/still", {videoId, input, frame});
-    return post("/__odori/exports", {videoId, input, format, quality, scale});
+    return post("/__odori/exports", {videoId, input, format, quality, scale, audio: hasSound ? sound : false});
   };
 
   const file = outputName(videoId);
@@ -143,6 +201,8 @@ export const ExportPanel = ({
   // video's layout and every frame number in the project depends on it.
   const still = format === "frame";
   const hasQuality = format === "mp4" || format === "webm";
+  /** GIF carries no audio track and a still is one frame. */
+  const hasSound = format !== "gif" && format !== "frame";
   const inFlight = job && job.status !== "ready" && job.status !== "failed";
   // The button names the file it will write - extension implied by the type
   // above it - and reports its own progress while writing it.
@@ -220,6 +280,22 @@ export const ExportPanel = ({
         </div>
       ) : null}
 
+      {hasSound ? (
+        <div className="export-row">
+          <span className="export-label">Sound</span>
+          <div className="export-options">
+            <Button variant="outline" active={sound} disabled={busy} onClick={() => setSound(true)}
+              title="Mix the brand's cues into the file">
+              On
+            </Button>
+            <Button variant="outline" active={!sound} disabled={busy} onClick={() => setSound(false)}
+              title="Write the picture with no audio track">
+              Off
+            </Button>
+          </div>
+        </div>
+      ) : null}
+
       <div className="export-actions">
         <Button
           variant="primary"
@@ -256,10 +332,18 @@ export const ExportPanel = ({
             </span>
           </div>
           {job.status === "rendering" || job.status === "encoding" ? (
-            <div className="progress">
+            <div className="progress" data-stalled={stalled ? "true" : undefined}>
               <span style={{width: `${Math.round((job.progress ?? 0) * 100)}%`}} />
             </div>
           ) : null}
+          {/* A bar that has not moved in two minutes looks exactly like one
+              that is about to. Saying which is the whole point. */}
+          {stalled ? (
+            <p className="hint" style={{marginTop: 6}}>
+              No progress for two minutes. It may be a slow frame, or the render may be wedged. Run{" "}
+              <code>odori jobs</code> to see the log, and the dev server terminal for the error.
+            </p>
+          ) : null}
         </>
       ) : null}
 

package/studio/src/components/Inspector.tsx

@@ -1,6 +1,7 @@
 import {useEffect, useState} from "react";
 import type {ReactNode} from "react";
 import {Icon} from "./ui";
+import {tokenize} from "../lib/highlight";
 
 /**
  * The right-hand pane, with its width and its presence under the reader's
@@ -29,14 +30,27 @@ const applyWidth = (value: number) => {
 export const Inspector = ({
   title,
   hint,
+  source,
   children,
 }: {
   /** What this pane is about, as a person names it. */
   title?: string;
   /** The longer form, one hover away - usually the source path. */
   hint?: string;
+  /**
+   * The files that produced what is on the stage, relative to the project.
+   * Given any, the pane offers to show them: the source is the truth here, so
+   * it should be one click from the frame rather than a path to go and find.
+   * More than one because a component is two files - what it draws and the
+   * fixture that plays it - and reading only the fixture answers the wrong
+   * question.
+   */
+  source?: string | string[];
   children: ReactNode;
 }) => {
+  const files = source === undefined ? [] : Array.isArray(source) ? source : [source];
+  const [showing, setShowing] = useState<"inspect" | "code">("inspect");
+  const [reading, setReading] = useState(0);
   const [collapsed, setCollapsed] = useState(() => window.localStorage.getItem(COLLAPSED_KEY) === "true");
 
   useEffect(() => {
@@ -104,6 +118,22 @@ export const Inspector = ({
           <span className="inspector-title" title={hint ?? title}>
             {title}
           </span>
+          {files.length > 0 ? (
+            <div className="inspector-views" role="tablist">
+              {(["inspect", "code"] as const).map((view) => (
+                <button
+                  key={view}
+                  type="button"
+                  role="tab"
+                  aria-selected={showing === view}
+                  data-active={showing === view ? "true" : undefined}
+                  onClick={() => setShowing(view)}
+                >
+                  {view === "inspect" ? "Inspect" : "Code"}
+                </button>
+              ))}
+            </div>
+          ) : null}
           <button
             type="button"
             className="inspector-toggle"
@@ -114,8 +144,78 @@ export const Inspector = ({
             <Icon name="sidebar" />
           </button>
         </div>
-        {children}
+        {files.length > 0 && showing === "code" ? (
+          <>
+            {/* One file is the file; several want naming, so the pane says
+                which of a component's two halves is on screen. */}
+            {files.length > 1 ? (
+              <div className="source-files" role="tablist">
+                {files.map((file, index) => (
+                  <button
+                    key={file}
+                    type="button"
+                    role="tab"
+                    aria-selected={index === reading}
+                    data-active={index === reading ? "true" : undefined}
+                    title={file}
+                    onClick={() => setReading(index)}
+                  >
+                    {file.split("/").pop()}
+                  </button>
+                ))}
+              </div>
+            ) : null}
+            <SourceView file={files[Math.min(reading, files.length - 1)]} />
+          </>
+        ) : (
+          children
+        )}
       </div>
     </aside>
   );
 };
+
+/**
+ * The file, as it is on disk. Read only on purpose: the editor is the editor,
+ * and what this answers is "what wrote this frame", which is a reading
+ * question. It refetches when the path changes, and the dev server reloads the
+ * page on every source edit, so what is shown is never stale.
+ */
+const SourceView = ({file}: {file: string}) => {
+  const [text, setText] = useState<string | null>(null);
+  const [failed, setFailed] = useState<string | null>(null);
+
+  useEffect(() => {
+    let live = true;
+    setText(null);
+    setFailed(null);
+    void fetch(`/__odori/source?file=${encodeURIComponent(file)}`)
+      .then(async (response) => {
+        if (!response.ok) throw new Error(await response.text());
+        return response.text();
+      })
+      .then((body) => live && setText(body))
+      .catch((error) => live && setFailed(error instanceof Error ? error.message : String(error)));
+    return () => {
+      live = false;
+    };
+  }, [file]);
+
+  if (failed) return <p className="hint">{failed}</p>;
+  if (text === null) return <p className="hint">Reading {file}</p>;
+  return (
+    <pre className="source">
+      <code>
+        {tokenize(text).map((token, index) =>
+          token.kind === "plain" ? (
+            token.text
+          ) : (
+            <span key={index} data-token={token.kind}>
+              {token.text}
+            </span>
+          ),
+        )}
+      </code>
+    </pre>
+  );
+};

package/studio/src/components/Navigator.tsx

@@ -0,0 +1,149 @@
+import {useEffect, useMemo, useRef, useState} from "react";
+import {Icon} from "./ui";
+
+/**
+ * The list of everything in a view, beside the thing you are looking at.
+ *
+ * Studio moved to gallery-then-detail so a narrow pane could give the stage
+ * its whole width, which is right when Studio sits beside an agent and wrong
+ * when you are working through a library: reaching the next component meant
+ * going back to the gallery, finding it, and clicking in. A session of that
+ * is a lot of round trips.
+ *
+ * So the list comes back as something you can put away. It collapses the way
+ * the inspector does, remembers that choice, and filters as you type, which
+ * is the part a gallery cannot do at all.
+ */
+const COLLAPSED_KEY = "odori-navigator-collapsed";
+
+export type NavigatorItem = {
+  id: string;
+  title: string;
+  /** The quieter second line: an id, a duration, a file. */
+  detail?: string;
+  /** A heading to sit under. Items with none come first, ungrouped. */
+  group?: string;
+};
+
+export const Navigator = ({
+  label,
+  items,
+  selected,
+  onSelect,
+}: {
+  /** What this list is of, for the header and the screen reader. */
+  label: string;
+  items: NavigatorItem[];
+  selected: string | null;
+  onSelect: (id: string) => void;
+}) => {
+  const [collapsed, setCollapsed] = useState(() => window.localStorage.getItem(COLLAPSED_KEY) === "true");
+  const [query, setQuery] = useState("");
+  const field = useRef<HTMLInputElement>(null);
+
+  // The grid in .main reads this, so opening the list costs no React layout.
+  useEffect(() => {
+    document.documentElement.dataset.navigator = collapsed ? "collapsed" : "open";
+    window.localStorage.setItem(COLLAPSED_KEY, String(collapsed));
+    return () => {
+      delete document.documentElement.dataset.navigator;
+    };
+  }, [collapsed]);
+
+  const matches = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    if (!needle) return items;
+    return items.filter((item) =>
+      [item.title, item.id, item.group].some((value) => value?.toLowerCase().includes(needle)),
+    );
+  }, [items, query]);
+
+  /* Headings come from the order the caller sorted, so a group is a run of
+     items rather than a bucket this has to invent an order for. */
+  const runs = useMemo(() => {
+    const out: Array<{group?: string; items: NavigatorItem[]}> = [];
+    for (const item of matches) {
+      const last = out.at(-1);
+      if (last && last.group === item.group) last.items.push(item);
+      else out.push({group: item.group, items: [item]});
+    }
+    return out;
+  }, [matches]);
+
+  if (collapsed) {
+    return (
+      <button
+        type="button"
+        className="navigator-reopen"
+        aria-label={`Show ${label.toLowerCase()}`}
+        title={`Show ${label.toLowerCase()}`}
+        onClick={() => setCollapsed(false)}
+      >
+        <Icon name="sidebar" />
+      </button>
+    );
+  }
+
+  return (
+    <aside className="navigator" aria-label={label}>
+      <div className="navigator-head">
+        <button
+          type="button"
+          className="navigator-toggle"
+          aria-label={`Hide ${label.toLowerCase()}`}
+          title={`Hide ${label.toLowerCase()}`}
+          onClick={() => setCollapsed(true)}
+        >
+          <Icon name="sidebar" />
+        </button>
+        <input
+          ref={field}
+          className="input navigator-search"
+          type="search"
+          placeholder={`Filter ${label.toLowerCase()}`}
+          value={query}
+          onChange={(event) => setQuery(event.currentTarget.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Escape") {
+              // The first press clears, the second gives the keys back to the
+              // transport: typing in here must not eat the space bar.
+              if (query) setQuery("");
+              else event.currentTarget.blur();
+            }
+          }}
+        />
+      </div>
+
+      <div className="navigator-scroll">
+        {matches.length === 0 ? (
+          <p className="hint navigator-empty">Nothing matches {query}.</p>
+        ) : (
+          runs.map((run) => (
+            /* Keyed by the first item, not by the group. A run without a group
+               used to key on a constant, so a list that goes ungrouped, then
+               grouped, then ungrouped again handed React two siblings with the
+               same key - which it is free to drop or duplicate. */
+            <div key={run.items[0].id}>
+              {run.group ? <h3 className="navigator-group">{run.group}</h3> : null}
+              <ul className="list">
+                {run.items.map((item) => (
+                  <li key={item.id}>
+                    <button
+                      type="button"
+                      className="list-item"
+                      data-active={item.id === selected ? "true" : undefined}
+                      onClick={() => onSelect(item.id)}
+                    >
+                      <strong>{item.title}</strong>
+                      {item.detail ? <span>{item.detail}</span> : null}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))
+        )}
+      </div>
+    </aside>
+  );
+};