@odori/cli 0.0.4 → 0.0.5

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/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/Navigator.tsx

@@ -119,7 +119,11 @@ export const Navigator = ({
           <p className="hint navigator-empty">Nothing matches {query}.</p>
         ) : (
           runs.map((run) => (
-            <div key={run.group ?? "."}>
+            /* 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) => (

package/studio/src/components/Settings.tsx

@@ -0,0 +1,109 @@
+import {useEffect, useRef, useState} from "react";
+import {Button, Icon} from "./ui";
+import {useStartSound} from "../settings";
+import {useTheme, type Theme} from "../theme";
+
+/**
+ * The workspace preferences, behind one control in the header.
+ *
+ * This replaced a three-button theme switcher. Theme was the only preference
+ * Studio had, so spending a permanent row of chrome on it was fine right up
+ * until there was a second one; three more buttons for sound would have made
+ * the header a settings panel that never closes. A gear says "there are
+ * choices here" in the space one of the old buttons used.
+ */
+const THEMES: Array<{id: Theme; label: string; hint: string}> = [
+  {id: "system", label: "System", hint: "Follow the operating system"},
+  {id: "light", label: "Light", hint: "Always light"},
+  {id: "dark", label: "Dark", hint: "Always dark"},
+];
+
+const SOUNDS = [
+  {id: "on" as const, label: "On", hint: "Play the score with the video"},
+  {id: "off" as const, label: "Off", hint: "Open every video muted"},
+];
+
+export const Settings = () => {
+  const [open, setOpen] = useState(false);
+  const {theme, setTheme} = useTheme();
+  const [sound, setSound] = useStartSound();
+  const wrapper = useRef<HTMLDivElement>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    const onPointerDown = (event: PointerEvent) => {
+      if (!wrapper.current?.contains(event.target as Node)) setOpen(false);
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      setOpen(false);
+      // Closing with the keyboard has to put the focus somewhere, and the
+      // control that opened the menu is the only place that is not a surprise.
+      trigger.current?.focus();
+    };
+    // Capture, so a click that also does something else still closes the menu.
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  return (
+    <div className="settings" ref={wrapper}>
+      <Button
+        ref={trigger}
+        icon
+        active={open}
+        aria-label="Settings"
+        aria-expanded={open}
+        aria-haspopup="menu"
+        title="Settings"
+        onClick={() => setOpen((value) => !value)}
+      >
+        <Icon name="settings" />
+      </Button>
+
+      {open ? (
+        <div className="menu settings-menu" role="menu" aria-label="Settings">
+          <p className="menu-heading">Theme</p>
+          {THEMES.map((option) => (
+            <button
+              key={option.id}
+              type="button"
+              role="menuitemradio"
+              aria-checked={theme === option.id}
+              className="menu-item"
+              data-selected={theme === option.id ? "true" : undefined}
+              onClick={() => setTheme(option.id)}
+            >
+              <span>{option.label}</span>
+              <span className="menu-hint">{option.hint}</span>
+            </button>
+          ))}
+
+          <p className="menu-heading">Sound</p>
+          {SOUNDS.map((option) => (
+            <button
+              key={option.id}
+              type="button"
+              role="menuitemradio"
+              aria-checked={sound === option.id}
+              className="menu-item"
+              data-selected={sound === option.id ? "true" : undefined}
+              onClick={() => setSound(option.id)}
+            >
+              <span>{option.label}</span>
+              <span className="menu-hint">{option.hint}</span>
+            </button>
+          ))}
+          {/* Changing it now would mute or unmute the video being watched,
+              which is not what a default is. */}
+          <p className="menu-note">Applies to the next video you open.</p>
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/studio/src/components/Transport.tsx

@@ -1,10 +1,20 @@
-import {useEffect, useRef} from "react";
+import {useEffect, useRef, useState} from "react";
 import {formatTimecode, type AudioTrack, type CompiledTimeline, type Playback} from "odori";
 import {Button, Icon} from "./ui";
 
 /**
  * Transport plus a scene-aware timeline. The track is the scene structure the
  * runtime compiled, not a decorative bar.
+ *
+ * The playhead is not draggable. Dragging one is a commitment: the pointer is
+ * captured, so a release outside the window can be missed and leave the
+ * transport stuck mid-scrub, and every intermediate frame is a real seek, which
+ * is what made scrubbing sound like a stuck record. Hovering costs nothing and
+ * answers the same question - what is at this moment - so the track previews
+ * under the cursor and a click is what actually moves the playhead.
+ *
+ * Preview is a paused-only affordance. A second marker chasing the cursor while
+ * the video plays is two playheads disagreeing about where you are.
  */
 export const RATES = [0.25, 0.5, 1, 1.5, 2, 4];
 
@@ -22,7 +32,7 @@ export const Transport = ({
   onToggleLoop,
   onToggleMuted,
   onSoloCue,
-  onScrubbing,
+  onPreview,
   rate = 1,
   onRate,
 }: {
@@ -41,65 +51,77 @@ export const Transport = ({
   onToggleLoop: () => void;
   onToggleMuted?: () => void;
   onSoloCue?: (id: string | null) => void;
-  onScrubbing?: (scrubbing: boolean) => void;
+  /**
+   * The frame under the cursor, or null when the cursor is off the track. The
+   * stage renders this instead of the playhead frame, so hovering shows the
+   * moment without committing to it.
+   */
+  onPreview?: (frame: number | null) => void;
   rate?: number;
   onRate?: (rate: number) => void;
 }) => {
   const trackRef = useRef<HTMLDivElement>(null);
-  const scrubbing = useRef(false);
-  // Scrubbing pauses the clock so the drag owns the playhead, then hands
-  // playback back in the state it was in. Picking a frame is not a request to
-  // stop.
-  const resumeAfterScrub = useRef(false);
-  // A click picks a frame; only a drag auditions. Audio waits for movement so
-  // choosing a frame while paused stays silent.
-  const dragOrigin = useRef(0);
-  const auditioning = useRef(false);
+  const [preview, setPreview] = useState<number | null>(null);
+  /* How much room the track has, so the ruler can be drawn for it rather than
+     for an assumed window. Studio is used docked beside an agent as often as
+     it is used full width. */
+  const [width, setWidth] = useState(0);
   const {frame} = playback;
 
-  const scrubTo = (clientX: number) => {
+  /** The frame under a given client x, or null if the track has no box yet. */
+  const frameAt = (clientX: number): number | null => {
     const element = trackRef.current;
-    if (!element) return;
+    if (!element) return null;
     const bounds = element.getBoundingClientRect();
+    if (bounds.width === 0) return null;
     const ratio = Math.max(0, Math.min(1, (clientX - bounds.left) / bounds.width));
-    playback.seek(Math.round(ratio * (durationInFrames - 1)));
+    return Math.round(ratio * (durationInFrames - 1));
   };
 
   useEffect(() => {
-    const move = (event: PointerEvent) => {
-      if (!scrubbing.current) return;
-      if (!auditioning.current && Math.abs(event.clientX - dragOrigin.current) > 3) {
-        auditioning.current = true;
-        onScrubbing?.(true);
-      }
-      scrubTo(event.clientX);
-    };
-    const up = () => {
-      if (!scrubbing.current) return;
-      scrubbing.current = false;
-      if (auditioning.current) {
-        auditioning.current = false;
-        onScrubbing?.(false);
-      }
-      if (resumeAfterScrub.current) {
-        resumeAfterScrub.current = false;
-        playback.play();
-      }
-    };
-    window.addEventListener("pointermove", move);
-    window.addEventListener("pointerup", up);
-    return () => {
-      window.removeEventListener("pointermove", move);
-      window.removeEventListener("pointerup", up);
-    };
-  });
+    const element = trackRef.current;
+    if (!element) return undefined;
+    const observer = new ResizeObserver(([entry]) => setWidth(entry?.contentRect.width ?? 0));
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  const showPreview = (next: number | null) => {
+    setPreview(next);
+    onPreview?.(next);
+  };
+
+  /* Playing is the one state with no preview, so starting playback while the
+     cursor rests on the track clears the marker it left behind. In an effect,
+     not in render: the parent owns the previewed frame and telling it during
+     our own render would be a write into somebody else's component. */
+  const playing = playback.playing;
+  useEffect(() => {
+    if (playing) {
+      setPreview(null);
+      onPreview?.(null);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [playing]);
 
+  /** What the stage is showing: the previewed frame wins while hovering. */
+  const shown = preview ?? frame;
   const scenes = timeline?.scenes ?? [];
-  const active = scenes.find((scene) => frame >= scene.start && frame < scene.start + scene.durationInFrames);
+  const active = scenes.find((scene) => shown >= scene.start && shown < scene.start + scene.durationInFrames);
+
+  /*
+   * The ruler is drawn to the width it actually has. A fixed twelve marks is
+   * fine in a wide window and unreadable in a narrow one, where "10.0s" next
+   * to "11.0s" in eighteen pixels is a smear rather than a scale - and where
+   * two marks could round to the same frame, which React counted as a
+   * duplicate key. Roughly fifty pixels is what one label needs to stand
+   * alone.
+   */
   const seconds = Math.max(1, Math.round(durationInFrames / fps));
-  const ticks = Array.from({length: Math.min(seconds, 12) + 1}, (_, index) =>
-    Math.round((index * durationInFrames) / Math.min(seconds, 12)),
-  );
+  const divisions = Math.max(1, Math.min(seconds, Math.floor(width / 52) || 1, 12));
+  const ticks = [...new Set(
+    Array.from({length: divisions + 1}, (_, index) => Math.round((index * durationInFrames) / divisions)),
+  )];
 
   return (
     <div className="transport">
@@ -114,12 +136,22 @@ export const Transport = ({
         <div
           className="track"
           ref={trackRef}
-          onPointerDown={(event) => {
-            scrubbing.current = true;
-            dragOrigin.current = event.clientX;
-            resumeAfterScrub.current = playback.playing;
+          data-preview={preview !== null ? "true" : undefined}
+          onPointerMove={(event) => {
+            // Touch reports a move before its tap, and a marker that appears
+            // under a finger and stays there is worse than none.
+            if (playing || event.pointerType === "touch") return;
+            showPreview(frameAt(event.clientX));
+          }}
+          onPointerLeave={() => showPreview(null)}
+          onClick={(event) => {
+            const next = frameAt(event.clientX);
+            if (next === null) return;
+            // Picking a frame is not a request to stop, but it is a request to
+            // look at that frame, and the clock would move off it immediately.
             playback.pause();
-            scrubTo(event.clientX);
+            playback.seek(next);
+            showPreview(null);
           }}
         >
           {scenes.length > 0 ? (
@@ -139,6 +171,14 @@ export const Transport = ({
               continuous timeline
             </div>
           )}
+          {preview !== null && preview !== frame ? (
+            <div
+              className="playhead"
+              data-preview="true"
+              aria-hidden="true"
+              style={{left: `${(preview / Math.max(1, durationInFrames - 1)) * 100}%`}}
+            />
+          ) : null}
           <div className="playhead" style={{left: `${(frame / Math.max(1, durationInFrames - 1)) * 100}%`}} />
         </div>
 
@@ -224,11 +264,14 @@ export const Transport = ({
           </Button>
         ) : null}
 
-        <span className="timecode" style={{marginLeft: 8}}>
-          <b>{formatTimecode(frame, fps)}</b> / {formatTimecode(durationInFrames - 1, fps)}
+        {/* The readout follows the picture, not the playhead: while hovering,
+            the stage is showing the previewed frame and a counter reporting
+            some other number is just wrong. */}
+        <span className="timecode" style={{marginLeft: 8}} data-preview={preview !== null ? "true" : undefined}>
+          <b>{formatTimecode(shown, fps)}</b> / {formatTimecode(durationInFrames - 1, fps)}
         </span>
-        <span className="timecode">
-          frame <b>{frame}</b> of {durationInFrames - 1}
+        <span className="timecode" data-preview={preview !== null ? "true" : undefined}>
+          frame <b>{shown}</b> of {durationInFrames - 1}
         </span>
         {active ? <span className="timecode">scene <b>{active.name ?? active.id}</b></span> : null}
       </div>

package/studio/src/components/ui.tsx

@@ -1,4 +1,4 @@
-import type {ButtonHTMLAttributes, ReactNode} from "react";
+import type {ButtonHTMLAttributes, ReactNode, Ref} from "react";
 
 export const Button = ({
   variant = "ghost",
@@ -10,6 +10,8 @@ export const Button = ({
   variant?: "ghost" | "outline" | "primary";
   active?: boolean;
   icon?: boolean;
+  /** React 19 passes ref as an ordinary prop; the type has to say so. */
+  ref?: Ref<HTMLButtonElement>;
 }) => (
   <button
     type="button"
@@ -69,10 +71,23 @@ export const Icon = ({
     | "display"
     | "external"
     | "sidebar"
+    | "settings"
     | "search";
 }) => {
   const paths: Record<string, ReactNode> = {
     play: <path d="M4.5 2.8v8.4l7-4.2z" fill="currentColor" />,
+    settings: (
+      <>
+        <circle cx="7" cy="7" r="2.1" fill="none" stroke="currentColor" strokeWidth="1.2" />
+        <path
+          d="M7 1.3l.85 1.5a4.7 4.7 0 0 1 1.2.5l1.7-.3.85 1.47-1 1.36c.08.2.14.4.18.62l1.53.72v1.7l-1.53.72c-.04.21-.1.42-.18.62l1 1.36-.85 1.47-1.7-.3a4.7 4.7 0 0 1-1.2.5L7 12.7l-.85-1.5a4.7 4.7 0 0 1-1.2-.5l-1.7.3-.85-1.47 1-1.36a4.7 4.7 0 0 1-.18-.62L1.7 6.83v-1.7l1.52-.72c.05-.21.11-.42.19-.62l-1-1.36.85-1.47 1.7.3c.37-.21.78-.38 1.2-.5z"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.1"
+          strokeLinejoin="round"
+        />
+      </>
+    ),
     sun: (
       <>
         <circle cx="7" cy="7" r="2.5" fill="none" stroke="currentColor" strokeWidth="1.2" />