@odori/cli 0.0.3 → 0.0.5

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" />

package/studio/src/lib/highlight.ts

@@ -0,0 +1,85 @@
+/**
+ * A small TypeScript and TSX tokenizer, for reading source in the inspector.
+ *
+ * Studio ships inside `@odori/cli`, so anything it imports is something every
+ * consumer downloads. A real highlighter is megabytes of grammars to colour a
+ * read-only panel, which is a bad trade for a dev tool; this is one pass of
+ * one regex over files we already know the shape of. It is deliberately not a
+ * parser: it does not resolve types, it will not know a word is a variable
+ * rather than a call, and it does not need to. What it has to get right is
+ * that a keyword inside a string stays a string, and a slash that opens a
+ * comment is not division, which ordering the alternation handles.
+ */
+export type Token = {text: string; kind: TokenKind};
+
+export type TokenKind =
+  | "plain"
+  | "comment"
+  | "string"
+  | "keyword"
+  | "number"
+  | "tag"
+  | "attr"
+  | "fn"
+  | "punct";
+
+const KEYWORDS = new Set([
+  "as", "async", "await", "break", "case", "catch", "class", "const", "continue", "declare", "default", "delete",
+  "do", "else", "enum", "export", "extends", "false", "finally", "for", "from", "function", "if", "implements",
+  "import", "in", "instanceof", "interface", "keyof", "let", "new", "null", "of", "readonly", "return", "satisfies",
+  "static", "super", "switch", "this", "throw", "true", "try", "type", "typeof", "undefined", "var", "void", "while",
+  "yield",
+]);
+
+/*
+ * Order is the whole design. Comments and strings come first so their contents
+ * are never read as code; the JSX tag rule follows, because `<Scene` is a tag
+ * and `a < b` is not; words and numbers come last.
+ */
+const PATTERN = new RegExp(
+  [
+    "(?<comment>//[^\\n]*|/\\*[\\s\\S]*?\\*/)",
+    "(?<string>`(?:\\\\.|[^`\\\\])*`|\"(?:\\\\.|[^\"\\\\\\n])*\"|'(?:\\\\.|[^'\\\\\\n])*')",
+    "(?<tag></?[A-Za-z][\\w.]*(?=[\\s/>]))",
+    "(?<number>\\b\\d[\\w.]*\\b)",
+    "(?<word>[A-Za-z_$][\\w$]*)",
+    "(?<punct>[{}()[\\].,;:=+\\-*/<>!?&|%^~]+)",
+  ].join("|"),
+  "g",
+);
+
+export const tokenize = (source: string): Token[] => {
+  const tokens: Token[] = [];
+  let last = 0;
+
+  const push = (text: string, kind: TokenKind) => {
+    if (text) tokens.push({text, kind});
+  };
+
+  for (const match of source.matchAll(PATTERN)) {
+    const groups = match.groups ?? {};
+    const index = match.index ?? 0;
+    push(source.slice(last, index), "plain");
+    last = index + match[0].length;
+
+    if (groups.comment) push(match[0], "comment");
+    else if (groups.string) push(match[0], "string");
+    else if (groups.tag) push(match[0], "tag");
+    else if (groups.number) push(match[0], "number");
+    else if (groups.punct) push(match[0], "punct");
+    else if (groups.word) {
+      const word = match[0];
+      // A word followed by `(` is being called; one followed by `=` inside a
+      // tag is an attribute. Both are guesses from the next character, which
+      // is as far as a tokenizer can honestly go.
+      const next = source[last];
+      if (KEYWORDS.has(word)) push(word, "keyword");
+      else if (next === "(") push(word, "fn");
+      else if (next === "=" && source[last + 1] !== "=") push(word, "attr");
+      else push(word, "plain");
+    }
+  }
+
+  push(source.slice(last), "plain");
+  return tokens;
+};

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]);
+};