@odori/cli 0.0.4 → 0.0.6

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,87 @@ 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 widest each readout will get, in characters. The transport is set in
+     the mono face, so a `ch` is exactly one column and this is a measurement
+     rather than an estimate. */
+  const digits = String(Math.max(0, durationInFrames - 1)).length;
+  const frameChars = "frame  of ".length + digits * 2;
+  const sceneChars =
+    scenes.length > 0
+      ? "scene ".length + Math.max(...scenes.map((scene) => (scene.name ?? scene.id).length))
+      : 0;
+
+  /*
+   * 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 +146,23 @@ export const Transport = ({
         <div
           className="track"
           ref={trackRef}
-          onPointerDown={(event) => {
-            scrubbing.current = true;
-            dragOrigin.current = event.clientX;
-            resumeAfterScrub.current = playback.playing;
-            playback.pause();
-            scrubTo(event.clientX);
+          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. A cut that is running
+               keeps running from where you pointed, which is what every player
+               does and what the audio guide already promised; a paused one
+               stays where you put it. */
+            playback.seek(next);
+            showPreview(null);
           }}
         >
           {scenes.length > 0 ? (
@@ -139,9 +182,22 @@ 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>
 
+        {/* Always present, the way the scene track always is.
+            It used to appear only once the runtime reported cues, which is
+            after the first paint, so the transport grew 26px and took them off
+            the stage on every load. A lane that is there and empty also says
+            something a missing one cannot: this video is silent. */}
         {track && track.cues.length > 0 ? (
           <div className="audio-track">
             {track.cues.map((cue) => {
@@ -171,7 +227,11 @@ export const Transport = ({
               );
             })}
           </div>
-        ) : null}
+        ) : (
+          <div className="audio-track" data-empty="true">
+            <span>{track ? "no audio" : "\u00a0"}</span>
+          </div>
+        )}
       </div>
 
       <div className="transport-row">
@@ -224,13 +284,31 @@ 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>
+        {/* Both of these change width as the cursor sweeps: the frame number
+            grows a digit at a time, and a scene called Resolution is half
+            again as wide as one called Proof. Tabular figures fix the digits
+            and do nothing for the count or the word, so each reserves the
+            widest it will ever need. Without that the row reflows under the
+            cursor and, in a pane narrow enough for it to wrap, takes a line
+            back from the stage while you are looking at it. */}
+        <span
+          className="timecode"
+          style={{minWidth: `${frameChars}ch`}}
+          data-preview={preview !== null ? "true" : undefined}
+        >
+          frame <b>{shown}</b> of {durationInFrames - 1}
         </span>
-        <span className="timecode">
-          frame <b>{frame}</b> of {durationInFrames - 1}
+        {/* Rendered even with no scene under the cursor, so a gap in the
+            timeline does not collapse the box and shuffle the row. */}
+        <span className="timecode" style={{minWidth: `${sceneChars}ch`}}>
+          {active ? <>scene <b>{active.name ?? active.id}</b></> : null}
         </span>
-        {active ? <span className="timecode">scene <b>{active.name ?? active.id}</b></span> : null}
       </div>
     </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,27 @@ 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" />,
+    /* The ordinary gear, on Lucide's 24 grid scaled to this 14 one. Drawing a
+       new one by eye is how you get a gear that reads as almost right; the
+       stroke is doubled so it comes out at the 1.2 everything else uses. */
+    settings: (
+      <g
+        transform="scale(0.5833)"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" />
+        <circle cx="12" cy="12" r="3" />
+      </g>
+    ),
     sun: (
       <>
         <circle cx="7" cy="7" r="2.5" fill="none" stroke="currentColor" strokeWidth="1.2" />

package/studio/src/settings.ts

@@ -0,0 +1,87 @@
+import {useCallback, useEffect, useState} from "react";
+
+/**
+ * Workspace preferences: the choices that belong to the person using Studio
+ * rather than to the project.
+ *
+ * They are deliberately not in `odori.config.ts`. A config file is checked in
+ * and shared, and "start muted" is a fact about someone's desk and how loud
+ * the room is, not about the video. Everything here is per browser, best
+ * effort, and safe to lose.
+ */
+export const STORAGE_PREFIX = "odori-studio-";
+
+/**
+ * Whether the transport starts with sound.
+ *
+ * Sound belongs on by default: a video with a score is not the same video
+ * without one, and a preview that silently drops half the work teaches you
+ * the wrong thing about it. But somebody working in an open office, or with
+ * Studio parked beside an agent all day, wants the opposite, and that is a
+ * setting rather than an argument.
+ */
+export type StartSound = "on" | "off";
+
+export const SETTINGS = {
+  sound: {key: "sound", values: ["on", "off"] as const, fallback: "on" as StartSound},
+} as const;
+
+const read = <T extends string>(key: string, values: readonly T[], fallback: T): T => {
+  try {
+    const stored = window.localStorage.getItem(`${STORAGE_PREFIX}${key}`);
+    return values.includes(stored as T) ? (stored as T) : fallback;
+  } catch {
+    // Private browsing and hardened profiles refuse storage. A preference is
+    // not worth failing a render over.
+    return fallback;
+  }
+};
+
+/** A single preference, persisted per browser. */
+export const usePreference = <T extends string>(
+  key: string,
+  values: readonly T[],
+  fallback: T,
+): [T, (next: T) => void] => {
+  const [value, setValue] = useState<T>(() =>
+    typeof window === "undefined" ? fallback : read(key, values, fallback),
+  );
+
+  const update = useCallback(
+    (next: T) => {
+      setValue(next);
+      try {
+        window.localStorage.setItem(`${STORAGE_PREFIX}${key}`, next);
+      } catch {
+        // Applied for this session either way.
+      }
+    },
+    [key],
+  );
+
+  return [value, update];
+};
+
+/** Read once, outside React, for state that has to be right on first render. */
+export const readStartSound = (): StartSound =>
+  typeof window === "undefined"
+    ? SETTINGS.sound.fallback
+    : read(SETTINGS.sound.key, SETTINGS.sound.values, SETTINGS.sound.fallback);
+
+export const useStartSound = () =>
+  usePreference<StartSound>(SETTINGS.sound.key, SETTINGS.sound.values, SETTINGS.sound.fallback);
+
+/**
+ * Other tabs of the same Studio should not disagree about a preference. The
+ * storage event fires only in the tabs that did not make the change, which is
+ * exactly the set that needs telling.
+ */
+export const useSettingsSync = (onChange: () => void) => {
+  useEffect(() => {
+    const listener = (event: StorageEvent) => {
+      if (event.key?.startsWith(STORAGE_PREFIX)) onChange();
+    };
+    window.addEventListener("storage", listener);
+    return () => window.removeEventListener("storage", listener);
+  }, [onChange]);
+};