@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/header/Header.tsx

@@ -1,110 +1,572 @@
-// The floating header: which document, what state it is in, and the transport.
+// The top bar: which document, which workspace, and what state it is in.
 //
 // Everything here reads the store and writes through it. No panel holds a copy
 // of the document, so there is no second place for the open document's identity
 // to live and drift.
-import { useEffect } from "react";
+//
+// ── NO TRANSPORT UP HERE ─────────────────────────────────────────────────
+//
+// It used to carry a play button and a `frame / total` readout that were the
+// timeline dock's, character for character (TimelineDock.tsx's `.dock-play` and
+// `DockReadout`). The dock's head strip is OUTSIDE `.dock-body`, and only the
+// body takes the `hidden` attribute on collapse, so both stay on screen at
+// every moment the header's pair did. Two controls that cannot disagree are
+// still two controls to find.
+//
+// What did NOT move to the dock is the playback CLOCK, which was living in that
+// transport bar and is not chrome at all. See `usePlaybackClock`.
+import { useEffect, useRef, type ReactNode } from "react";
+import { PanelBoundary, SegmentedControl } from "@dailies-studio/ui";
+import { frameToPx } from "@dailies-studio/timeline";
+import { DEFAULT_SHOT_FPS } from "@dailies-studio/shot/doc";
+import { defClockFrames, playbackLoops, playbackWindow } from "../../state/types.js";
+import type { ShotEditorState } from "../../state/types.js";
+// Re-exported where it has always been imported from; see `playbackWindow`.
+export { playbackWindow };
+import { refreshAgentCredentials } from "../../state/agentActions.js";
+import { agentInEditor } from "../agent/agentGate.js";
 import { useShotEditor, useStore } from "../../state/context.js";
-import { DocSwitcher } from "./DocSwitcher.js";
+import { shortcutHint } from "../../state/shortcuts.js";
+import { VIEW_ONLY, exportBlocker, workspaceOf } from "../../state/workspace.js";
+import { COMPONENT_ICON, DOWNLOAD_ICON, STORYBOARD_ICON, STUDIO_ICON } from "../../icons.js";
+import { useCodeBufferGuard } from "../code/codeBufferGuard.js";
+import { EYE_ICON } from "../comments/parts.js";
+import { InboxButton } from "../comments/InboxButton.js";
+import { AccountAvatar } from "./AccountAvatar.js";
+import { AgentChip } from "./AgentChip.js";
+import { AppMenu } from "./AppMenu.js";
 import { HistoryControls } from "./HistoryControls.js";
-import { StatusBadges } from "./StatusBadges.js";
-import { TransportBar } from "./TransportBar.js";
-import { ZoomControls } from "./ZoomControls.js";
+import { PresenceStack } from "./PresenceStack.js";
+import { ProjectTitle } from "./ProjectTitle.js";
+import { SaveBadges } from "./StatusBadges.js";
+import { ShareButton } from "./ShareButton.js";
+import { SyncRenamedNote } from "./SyncDeletedDialog.js";
 
 export function Header() {
   const store = useStore();
   useEffect(() => {
-    void store.refreshShots();
+    // The agent probe, from the header because the header is mounted for the
+    // whole session: the right column's Agent tab is gated on its answer, and
+    // a probe that ran only once the drawer opened could not answer that. One
+    // request per session either way, since the drawer's own effect finds the
+    // answer already in the store. No drawer, no probe.
+    if (agentInEditor()) void refreshAgentCredentials(store);
   }, [store]);
 
+  usePlaybackClock();
+
   const name = useShotEditor((s) => s.name);
+  // The Library is an aria-modal Dialog that starts BELOW this bar
+  // (styles/library.css), so the bar stays in sight but must not stay live: a
+  // menu opened here would paint under the dialog (--z-menu 1000 against
+  // --z-dialog 1100), and a click here would move focus out of its trap, where
+  // Escape and Tab no longer reach it. `inert` takes the bar out of pointer,
+  // focus and the accessibility tree together, which is what aria-modal claims.
+  const libraryOpen = useShotEditor((s) => s.libraryBrowserOpen);
+  // The role's verdict: a version preview is read only too, but not a viewer.
+  const readOnly = useShotEditor((s) => s.versionPreview?.roleReadOnly ?? s.readOnly);
 
   return (
-    <header className="shell-header" data-testid="shot-header">
-      <DocSwitcher />
-      <HistoryControls />
-      {name === null ? null : <TransportBar />}
-      <div className="shell-header-spacer" />
-      {name === null ? null : <PanelToggles />}
-      <ZoomControls />
-      <StatusBadges />
-      <AgentToggle />
-      {name !== null && <ExportButton />}
+    <header className="shell-header" data-testid="shot-header" inert={libraryOpen}>
+      {/* INSIDE the positioned container, per the boundary's placement rule:
+          a catch swaps the contents for the card, never the header's box. */}
+      {/* THREE COLUMNS, Paper's top bar:
+
+            menu │ Projects › Project › Shot │ history ··· Studio | Storyboard ··· saved  Export  Agent  avatar
+
+          The switch sits in the MIDDLE track of a 1fr auto 1fr grid, so it is
+          centred on the window whatever the two ends hold.
+
+          The Agent chip is the outside agent's door (MCP health and the
+          connect rows, AgentChip.tsx), in a boundary of its own so a crash in
+          it leaves the bar standing.
+
+          WHAT IS NOT HERE. The panel toggles are on the canvas bar
+          (PanelToggles.tsx), the in-app Agent is the right column's tab, and
+          the Library opens from View > Panels and the Storyboard. Zoom and the
+          stage's badges are in the canvas bar too, over the picture they
+          describe. The monitor meter is in the timeline's meters cell. */}
+      <PanelBoundary label="Header">
+        <div className="header-start">
+          <AppMenu />
+          <span className="header-sep" aria-hidden="true" />
+          <ProjectTitle />
+          {/* "Renamed to X by Maya" (R10), for a few seconds. */}
+          <SyncRenamedNote />
+          {/* A Viewer's standing note (Paper page 21, "View only"): an edit
+              attempt says the same thing in a toast (ViewOnlyToast). */}
+          {readOnly && name !== null ? (
+            <span className="view-only-pill" data-testid="view-only-pill" title={VIEW_ONLY}>
+              {EYE_ICON}
+              View only
+            </span>
+          ) : null}
+          <span className="header-sep" aria-hidden="true" />
+          <HistoryControls />
+        </div>
+        <div className="header-center">{name === null ? null : <WorkspaceSwitch />}</div>
+        <div className="header-end">
+          <SaveBadges />
+          {/* Who else is here (Paper page 21), live sync only. */}
+          <PresenceStack />
+          <ShareButton />
+          {name !== null && <ExportButton />}
+          <AgentChip />
+          <InboxButton />
+          <AccountAvatar />
+        </div>
+      </PanelBoundary>
     </header>
   );
 }
 
 /**
- * Show and hide the three panels.
- *
- * IN THE HEADER, and not on the panels themselves, for one reason: a control
- * that lives on the thing it hides disappears with it. A chevron on the left
- * rail can collapse the rail and then has nowhere to be, which is how these
- * end up needing a second floating "reopen" affordance nobody finds. The
- * header never moves, so one button per panel is the whole story, and each is
- * `aria-pressed` so its state is readable rather than inferred from the glyph.
+ * Playback: WALL TIME IN, INTEGER FRAMES OUT.
+ *
+ * It never accumulates frames per tick. `frame++` per rAF makes playback speed
+ * a function of the monitor's refresh rate (a 120Hz laptop plays a 30fps shot
+ * at double speed) and makes one dropped frame permanently shift everything
+ * after it. Deriving the frame from elapsed time instead plays at the
+ * document's own rate on any display, drops frames under load rather than
+ * slowing down, and puts the same integer frame on screen that the export will
+ * render, because the seek target is `floor(elapsed * fps)` at 1x — see
+ * `playbackTargetFrame`, which owns that arithmetic and the shuttle's rate
+ * along with it.
+ *
+ * ── THE WALL TIME IS THE REFRESH'S, NOT THE CALLBACK'S ───────────────────
+ *
+ * A tick reads its time from rAF's own timestamp, the start of the refresh
+ * it draws for, on `performance.now()`'s timeline like `playOrigin.at`, and
+ * never from `performance.now()` inside the callback. The callback runs late
+ * by whatever the frame did before it (a median of 0.3 to 0.7 ms and up to
+ * 17.6 ms in the benchmark's headless Chrome), so a frame boundary that fell
+ * a few ms after a refresh landed before the reading on one tick and after
+ * it on the next: a healthy film skipped a frame and repeated the next,
+ * which the render scale controller read as late frames
+ * (renderScaleController.ts `presented`). Elapsed time is clamped at zero,
+ * since a refresh can begin before the origin it is the first tick of.
+ *
+ * ── AND THE BOUNDARIES BETWEEN REFRESHES ──────────────────────────────────
+ *
+ * The timestamps themselves sit 0.05 to 0.35 ms off the display's grid,
+ * coarsened to 0.1 ms, so a boundary on a refresh, or that near one, still
+ * fell either side of it from tick to tick. A frame period of p/q refreshes
+ * meets the refreshes at q phases R/q apart, and `placedBase` moves the
+ * boundaries to the middle of those gaps, R/(2q) from the nearest refresh:
+ * half a refresh at 60 and 30 fps on 60 Hz, a quarter at 24. A display whose
+ * rate drifts against the document's (the headless lane's 59.978 Hz against
+ * 60 fps) carries them back toward a refresh, where the wander made a run
+ * of skips and repeats of each crossing; so they are kept in the middle,
+ * and the drift costs one slip of a refresh at a time instead. The refresh
+ * is measured over a run's latest ticks (`refreshOf`) and kept for the next
+ * run, so a page's first run places at its `REFRESH_STAMPS`th tick and every
+ * later run at its second, once its first interval agrees with the refresh
+ * kept (the window may be on another display). The base stays within half a
+ * refresh of the origin the sound counts from too (`playOrigin`), and the
+ * audio's drift check allows the picture its refresh (audio/preview.ts).
+ *
+ * IN THE HEADER, which renders none of it. The loop needs a mount that lasts
+ * the whole session: it used to ride the header's transport bar, and the
+ * obvious home for it now would be the timeline dock, whose play button is the
+ * one that starts it. That dock is collapsible, and a clock that unmounts with
+ * a panel is a play button that stops working.
+ *
+ * The window, the fps and the shuttle rate are subscribed as NUMBERS, never as
+ * `doc`. This runs inside the header, and a `doc` subscription would re-render
+ * every control up there on each keystroke of an edit.
  */
-function PanelToggles() {
-  const store = useStore();
-  const rail = useShotEditor((s) => s.railCollapsed);
-  const inspector = useShotEditor((s) => s.inspectorCollapsed);
-  const dock = useShotEditor((s) => s.dockCollapsed);
-  const rows: ReadonlyArray<{ on: boolean; glyph: string; label: string; key: string; run: () => void }> = [
-    { on: !rail, glyph: "▙", label: "Left panel", key: "[", run: () => store.setRailCollapsed(!rail) },
-    { on: !dock, glyph: "▄", label: "Timeline", key: "", run: () => store.setDockCollapsed(!dock) },
-    {
-      on: !inspector,
-      glyph: "▟",
-      label: "Right panel",
-      key: "]",
-      run: () => store.setInspectorCollapsed(!inspector),
-    },
-  ];
+/**
+ * The frame a tick should land on: wall time in, integer frame out, wrapped
+ * into the window being played.
+ *
+ * Extracted from the rAF loop so the arithmetic can be tested without a clock.
+ * The loop's own half, which instant a tick reads and where its boundaries
+ * sit, is held by header.test.tsx through a fake `requestAnimationFrame`.
+ *
+ * ── FLOOR, NOT ROUND ─────────────────────────────────────────────────────
+ *
+ * `Math.floor` is what the shipped player (`player/src/stage.ts`) and the
+ * legacy editor both use, and this loop was the only transport in the tree
+ * rounding instead. Rounding shows frame N from half a frame BEFORE frame N's
+ * instant, so the preview ran a consistent half-frame ahead of the same
+ * document's export — small, invisible in isolation, and exactly the kind of
+ * disagreement that costs an afternoon when someone finally A/Bs a preview
+ * against an MP4. Every frame it draws was always exact; only which instant
+ * chose it has changed.
+ *
+ * ── OFFSET-FORM WRAP ─────────────────────────────────────────────────────
+ *
+ * A bare `target % total` is right only for a window that begins at 0: inside a
+ * shot at [90, 120) it wraps frame 95 to 5, which is a different shot — and
+ * `seek`'s clamp would then pin the playhead on frame 90 forever, so playback
+ * would look frozen rather than wrong. The same form is what lets a REVERSE
+ * rate wrap off the front of the window onto its last frame instead of running
+ * to a negative one the clamp would freeze on.
+ *
+ * ── AND THE START HAS TO BE IN THE WINDOW FOR THAT FORM TO MEAN ANYTHING ─
+ *
+ * The wrap is a modulus, so it answers for ANY start frame — including one
+ * outside the window entirely, which is the ordinary case for a WORK AREA: the
+ * bracket is set with ⌥I/⌥O and the playhead is then free to wander off it. Hit
+ * play with the playhead at frame 10 and a bracket of [100, 140) and the first
+ * tick landed on `100 + ((10 - 100) mod 40)` = frame 130, which is an arbitrary
+ * frame three quarters of the way through the loop. It looked like the
+ * transport had jumped somewhere random, because it had.
+ *
+ * So a start OUTSIDE the window becomes the window's IN POINT, which is what
+ * pressing play on a bracket means in every editor that has one. A start
+ * already inside is untouched, so the shot and definition arms — whose windows
+ * always contain the clock they are driving — are unchanged frame for frame.
+ *
+ * ── THE RATE IS APPLIED TO THE MAGNITUDE, THEN THE SIGN ──────────────────
+ *
+ * `floor(elapsed * fps * rate)` would be wrong in reverse and silently so:
+ * flooring a negative product is `-ceil(|product|)`, which steps back a frame
+ * the instant the clock moves at all, so reverse would run a consistent frame
+ * AHEAD of forward over the same wall time. Flooring the magnitude and then
+ * applying the sign keeps every frame shown from its own instant in both
+ * directions, which is the property the floor was chosen for.
+ *
+ * The default of 1 is not politeness: every caller that is not the shuttle —
+ * and every existing test — means 1x, and a required argument would let a new
+ * one guess.
+ *
+ * ── WITH THE LOOP OFF (`loop: false`, the Project context's Loop button) ──
+ *
+ * The target is CLAMPED to the window instead of wrapped, and the clock stops
+ * once it reads the far edge (`playbackEndFrame`). A start already ON that far
+ * edge plays again from the opposite one, which is what Play means on a
+ * transport that stopped at the end.
+ */
+export function playbackTargetFrame(
+  startedFrame: number,
+  windowStart: number,
+  windowFrames: number,
+  fps: number,
+  elapsedSeconds: number,
+  rate: number = 1,
+  loop: boolean = true,
+): number {
+  const steps = Math.floor(elapsedSeconds * fps * Math.abs(rate));
+  const last = windowStart + windowFrames - 1;
+  // See the header: outside the window, playback begins at the in point.
+  let from =
+    startedFrame >= windowStart && startedFrame < windowStart + windowFrames
+      ? startedFrame
+      : windowStart;
+  if (!loop && from === playbackEndFrame(windowStart, windowFrames, rate)) {
+    from = rate < 0 ? last : windowStart;
+  }
+  const target = from + (rate < 0 ? -steps : steps);
+  if (!loop) return Math.min(last, Math.max(windowStart, target));
   return (
-    <div className="panel-toggles" role="group" aria-label="Panels">
-      {rows.map(({ on, glyph, label, key, run }) => (
-        <button
-          key={label}
-          type="button"
-          className={`btn btn-icon${on ? " is-active" : ""}`}
-          aria-pressed={on}
-          title={`${on ? "Hide" : "Show"} ${label.toLowerCase()}${key === "" ? "" : ` (${key})`}`}
-          onClick={run}
-        >
-          {glyph}
-        </button>
-      ))}
-      <button
-        type="button"
-        className="btn btn-icon"
-        title="Hide every panel (.)"
-        onClick={() => store.togglePanels()}
-      >
-        ⛶
-      </button>
-    </div>
+    windowStart +
+    ((((target - windowStart) % windowFrames) + windowFrames) % windowFrames)
   );
 }
 
-/** Opens the drawer, which REPLACES the inspector rather than sitting beside
- *  it. One right rail: the shell grid has one column there, and a second
- *  floating panel over a 3D stage is a panel that covers the thing being
- *  discussed. */
-function AgentToggle() {
+/** The frame a non-looping run stops on: the window's last frame forward, its
+ *  first in reverse. */
+export function playbackEndFrame(
+  windowStart: number,
+  windowFrames: number,
+  rate: number = 1,
+): number {
+  return rate < 0 ? windowStart : windowStart + windowFrames - 1;
+}
+
+/** The latest tick timestamps of a run `refreshOf` measures over. */
+export const REFRESH_STAMPS = 16;
+/** An interval between two ticks this long, ms, is a stall or a hidden tab,
+ *  and measuring starts again after it. */
+const REFRESH_GAP_MS = 100;
+/** How near a run's own interval must come to the refresh an earlier run
+ *  measured, as a share of it, before that refresh places this run's
+ *  boundaries: the window may be on another display now. */
+const REFRESH_AGREES = 0.05;
+/** The largest q `boundaryGap` looks for in a frame period of p/q refreshes:
+ *  past it the gaps are too narrow for the timestamps' wander. */
+const PATTERN_MAX = 5;
+/** How far the measured ratio may sit from p/q, as a share of it, and still
+ *  be that pattern: room for a rate a thousandth off its nominal (29.97 fps,
+ *  a 59.94 Hz display) and for `refreshOf`'s own error. */
+const PATTERN_TOLERANCE = 0.003;
+/** The narrowest gap, as a share of the refresh, whose boundaries are kept
+ *  clear as the display drifts (q up to 2): a narrower gap's quarter is
+ *  within the timestamps' wander, and a ratio the estimate took for such a
+ *  pattern may be none (25 fps on 144 Hz, 5.76 refreshes, is within 0.2% of
+ *  23/4), and keeping it clear would slip it again and again. */
+const KEPT_GAP = 0.5;
+
+/**
+ * The display's refresh interval, ms, from a run's latest tick timestamps:
+ * their span over the whole number of refreshes in it, counted with the
+ * median interval (one refresh, unless the main thread missed most). Null
+ * until there are `REFRESH_STAMPS` of them: one interval carries a
+ * timestamp's wander, 2% of a 165 Hz refresh, where fifteen carry a
+ * fifteenth of it.
+ */
+export function refreshOf(stamps: readonly number[]): number | null {
+  if (stamps.length < REFRESH_STAMPS) return null;
+  const intervals = stamps.slice(1).map((at, i) => at - stamps[i]!).sort((a, b) => a - b);
+  const span = stamps[stamps.length - 1]! - stamps[0]!;
+  return span / Math.round(span / intervals[intervals.length >> 1]!);
+}
+
+/** The gap, ms, between the phases at which the boundaries of a frame period
+ *  of p/q refreshes meet the refreshes, R/q, or null for a ratio that is no
+ *  such fraction with q up to `PATTERN_MAX`: its boundaries take every phase
+ *  in turn, and no shift keeps them clear. */
+export function boundaryGap(refreshMs: number, periodMs: number): number | null {
+  const ratio = periodMs / refreshMs;
+  for (let q = 1; q <= PATTERN_MAX; q += 1) {
+    if (Math.abs(ratio - Math.round(ratio * q) / q) <= PATTERN_TOLERANCE * ratio) return refreshMs / q;
+  }
+  return null;
+}
+
+const mod = (value: number, by: number): number => ((value % by) + by) % by;
+
+/**
+ * Where a run's frame boundaries sit after a tick at `tickAt`, a refresh:
+ * the instant the run counts its frames from, `base`, null until placed.
+ *
+ * Placed in the middle of the gaps (`boundaryGap`), R/(2q) from the nearest
+ * refresh, and kept there for q up to 2: a display whose rate drifts against
+ * the document's carries them back toward a refresh, so once one comes
+ * within a quarter of a gap they go back to the middle. Neither move takes a
+ * boundary across a refresh, so neither changes a frame on screen. The base
+ * stays within half a refresh of the origin: when the drift has used that
+ * up, the move goes the other way and the boundaries slip a whole refresh,
+ * once, which is the two rates' own skip.
+ */
+export function placedBase(base: number | null, originAt: number, tickAt: number, refreshMs: number, periodMs: number): number | null {
+  const gap = boundaryGap(refreshMs, periodMs);
+  if (gap === null) return base;
+  const from = base ?? originAt;
+  // From the boundary nearest the tick, so the refresh estimate's error is
+  // not multiplied by the run's length.
+  const nearest = from + periodMs * Math.round((tickAt - from) / periodMs);
+  let centre = mod(gap / 2 - mod(nearest - tickAt, gap), gap);
+  if (centre > gap / 2) centre -= gap;
+  if (base !== null && (gap < KEPT_GAP * refreshMs || Math.abs(centre) <= gap / 4)) return base;
+  const next = from + centre;
+  return next - Math.round((next - originAt) / refreshMs) * refreshMs;
+}
+
+/**
+ * THE WORK AREA, DRAWN. The bracket over the ruler that says what a press of
+ * Space will actually loop.
+ *
+ * ── IT HAD NO REPRESENTATION AT ALL ──────────────────────────────────────
+ *
+ * ⌥I / ⌥O / ⌥X wrote `workArea`, `playbackWindow` read it, the shortcuts manual
+ * described it, and NOTHING on screen showed it. So the only evidence an author
+ * had that they had bracketed anything was that playback stopped going where
+ * they expected, which reads as a broken transport rather than as a feature
+ * they turned on — and ⌥X, the way out, is only findable if you already know
+ * the thing exists.
+ *
+ * ── IN THIS FILE BECAUSE THE NUMBERS ARE ─────────────────────────────────
+ *
+ * It draws `playbackWindow(s)` and not `s.workArea`. Those differ: the window
+ * is CLAMPED to the document on every read (a trim can shorten the film under
+ * a bracket nobody touched) and falls back to the whole film when the clamp
+ * leaves nothing. A bracket painted from the raw field would be a bracket the
+ * transport does not honour, which is worse than none — so the two come off the
+ * one function, in the one file, and cannot disagree. The dock mounts it into
+ * its ruler; see `TimelineDock`.
+ *
+ * WITHHELD OUTSIDE THE SCENE CONTEXT, the same rule `playbackWindow` and
+ * `setWorkAreaEdge` both keep: an entered shot and a component definition each
+ * own the transport's window already, so a bracket visible in either would name
+ * a loop nothing is running.
+ */
+export function WorkAreaBracket(props: { ppf: number }) {
+  const area = useShotEditor((s) => s.workArea);
+  const owned = useShotEditor((s) => defClockFrames(s) !== null || s.enteredScene !== null);
+  const start = useShotEditor((s) => playbackWindow(s).start);
+  const frames = useShotEditor((s) => playbackWindow(s).frames);
+  if (area === null || owned || frames <= 0) return null;
+  return (
+    <span
+      className="dock-work-area"
+      data-testid="work-area-bracket"
+      aria-hidden="true"
+      style={{ left: frameToPx(start, props.ppf), width: frameToPx(frames, props.ppf) }}
+    />
+  );
+}
+
+function usePlaybackClock(): void {
   const store = useStore();
-  const open = useShotEditor((s) => s.agentOpen);
-  const running = useShotEditor((s) => s.agentRunning);
+  const playing = useShotEditor((s) => s.playing);
+  // The COMPONENT CONTEXT swaps the whole triple (unify P2): total, the seek
+  // verb and the starting frame become def-local together, so the same loop
+  // wraps a definition's own duration and never touches master time — the
+  // scene render, the audio preview and every playhead-paired verb keep the
+  // master frame they were on.
+  // EITHER SUBJECT, one bit: a definition and a code component both put the
+  // stage in the component context, so both swap the triple. `defClockFrames`
+  // is the one answer, and it is what `seekDefTo` clamps on too.
+  const inDef = useShotEditor((s) => defClockFrames(s) !== null);
+  // ── AND THE WINDOW IT LOOPS INSIDE ────────────────────────────────────
+  //
+  // Two NUMBERS, never `doc` — this file's own rule, and the reason is that a
+  // `doc` subscription here re-renders every control in the header on each
+  // keystroke of an edit. Both come off ONE function (`playbackWindow`), so a
+  // start and a length can never be read from two different subjects, and both
+  // are in the effect's deps, so a trim of the entered shot or a moved work
+  // area restarts the loop against the window it actually has now.
+  const windowStart = useShotEditor((s) => playbackWindow(s).start);
+  const total = useShotEditor((s) => playbackWindow(s).frames);
+  const fps = useShotEditor((s) =>
+    s.doc === null
+      ? DEFAULT_SHOT_FPS.num / DEFAULT_SHOT_FPS.den
+      : s.doc.fps.num / s.doc.fps.den,
+  );
+  // THE SHUTTLE'S SPEED, read here and nowhere else in the picture lane: the
+  // stage is seeked frame by frame either way, so a rate never reaches it and
+  // the bridge needs no new message. `setPlaying(true)` resets this to 1, so
+  // the loop that a Space bar starts is always 1x.
+  const rate = useShotEditor((s) => s.playRate);
+  // WRAP OR STOP at the window's end. Always a wrap inside a shot or a
+  // definition; the Project context follows the dock's Loop button.
+  const loop = useShotEditor(playbackLoops);
+  // ── ONE CLOCK FOR PICTURE AND SOUND ────────────────────────────────────
+  //
+  // `playOrigin` is where and when the transport started, set by the same
+  // write that sets `playing`. The audio session anchors on it too
+  // (audio/preview.ts), so the loop starts from it rather than from this
+  // effect, which runs a React commit later, its boundaries placed at most
+  // half a refresh off it. ONCE per origin: a restart for the window, the
+  // rate or the loop anchors on its own reading, as before.
+  const origin = useShotEditor((s) => s.playOrigin);
+  const startedFrom = useRef<ShotEditorState["playOrigin"]>(null);
+  // The display's refresh as the last run measured it (`refreshOf`), so a
+  // run after the first places its boundaries at its second tick, once its
+  // first interval agrees.
+  const refresh = useRef<number | null>(null);
+
+  useEffect(() => {
+    // Taken even by a run that cannot start (an empty window), which would
+    // find it stale by the time one could.
+    const fresh = origin === startedFrom.current ? null : origin;
+    startedFrom.current = origin;
+    if (!playing || total <= 0) return;
+    const startedAt = fresh?.at ?? performance.now();
+    const startedFrame = fresh?.frame ?? (inDef ? store.getState().defFrame : store.getState().frame);
+    const periodMs = 1000 / (fps * Math.abs(rate));
+    let raf = 0;
+    const stamps: number[] = [];
+    // The instant the run counts from: the origin's own until its boundaries
+    // are placed (`placedBase`), at its first tick with a refresh it trusts.
+    let base: number | null = null;
+    // An earlier run's refresh places this one's boundaries once an interval
+    // of this run agrees with it (`REFRESH_AGREES`). Placed on the grid of
+    // the display the window was on (60 Hz, a run now on 144 Hz), a base
+    // would move by more than a tick, and the playhead step back a frame.
+    let trusted = false;
+    const tick = (now: number): void => {
+      if (stamps.length > 0 && now - stamps[stamps.length - 1]! >= REFRESH_GAP_MS) stamps.length = 0;
+      stamps.push(now);
+      if (stamps.length > REFRESH_STAMPS) stamps.shift();
+      const measured = refreshOf(stamps);
+      if (measured !== null) refresh.current = measured;
+      const interval = stamps.length > 1 ? now - stamps[stamps.length - 2]! : null;
+      trusted ||=
+        measured !== null ||
+        (interval !== null && refresh.current !== null && Math.abs(interval - refresh.current) <= REFRESH_AGREES * refresh.current);
+      if (trusted && refresh.current !== null) base = placedBase(base, startedAt, now, refresh.current, periodMs);
+      const elapsed = Math.max(0, now - (base ?? startedAt)) / 1000;
+      const wrapped = playbackTargetFrame(
+        startedFrame,
+        windowStart,
+        total,
+        fps,
+        elapsed,
+        rate,
+        loop,
+      );
+      if (inDef) store.seekDef(wrapped);
+      else store.seek(wrapped);
+      // The end of a run that does not loop: hold the last frame and stop,
+      // through `setPlaying` like every other pause.
+      if (!loop && wrapped === playbackEndFrame(windowStart, total, rate)) {
+        store.setPlaying(false);
+        return;
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [playing, origin, total, fps, store, inDef, windowStart, rate, loop]);
+}
+
+/** Studio | Storyboard | Components, the workspaces a Project has, centred in
+ *  the bar.
+ *
+ *  Storyboard is never disabled: from any mode it HANDS OVER
+ *  (`setStoryboardOpen` closes the material nodes, then leaves Components,
+ *  each through the exit that records or restores its work), and the one
+ *  thing that hand-over could lose, Code Studio's unsaved buffers, is asked
+ *  about first. Components is disabled WITH THE REASON under the material
+ *  nodes. Studio is always open: it is where every other mode returns to.
+ *  Primitive subscriptions rather than one derived object, the shell's
+ *  rule. */
+function WorkspaceSwitch() {
+  const store = useStore();
+  const open = useShotEditor((s) => s.storyboardOpen);
+  const materialWorkspace = useShotEditor((s) => s.materialWorkspace);
+  const inComponents = useShotEditor((s) => workspaceOf(s) === "components");
+  const componentsBlocker = materialWorkspace === null ? null : "Close the material nodes before opening Components.";
+  // Leaving Components drops a code component's buffers, so unsaved text
+  // there asks.
+  const { guard, dialog } = useCodeBufferGuard();
+  const label = (glyph: ReactNode, word: string): ReactNode => (
+    <>
+      <span className="header-glyph" aria-hidden="true">
+        {glyph}
+      </span>
+      {word}
+    </>
+  );
   return (
-    <button
-      type="button"
-      className={`btn${open ? " is-active" : ""}`}
-      aria-label="Agent"
-      aria-pressed={open}
-      title="Agent — describe the scene you want"
-      onClick={() => store.setAgentOpen(!open)}
-    >
-      {running ? "Agent…" : "Agent"}
-    </button>
+    <>
+      {dialog}
+      <SegmentedControl
+        ariaLabel="Workspace"
+        className="is-accent workspace-switch"
+        value={open ? "storyboard" : inComponents ? "components" : "studio"}
+        options={[
+          { value: "studio", label: label(STUDIO_ICON, "Studio"), testId: "workspace-studio" },
+          {
+            value: "storyboard",
+            label: label(STORYBOARD_ICON, "Storyboard"),
+            title: `Storyboard${shortcutHint("ctx.storyboard")}`,
+            testId: "workspace-storyboard",
+          },
+          {
+            value: "components",
+            label: label(COMPONENT_ICON, "Components"),
+            title: componentsBlocker ?? "Components",
+            disabled: componentsBlocker !== null,
+            testId: "workspace-components",
+          },
+        ]}
+        onChange={(next) => {
+          // The leave sits INSIDE the guard, so Discard drops the buffers
+          // before the store's own unsaved-code check runs.
+          const toBoard = (): void => {
+            store.leaveComponents();
+            store.setStoryboardOpen(true);
+          };
+          if (next === "storyboard") guard(toBoard);
+          else if (next === "components") guard(() => void store.openComponents());
+          else guard(() => (inComponents ? store.leaveComponents("stage") : store.setStoryboardOpen(false)));
+        }}
+      />
+    </>
   );
 }
 
@@ -115,17 +577,35 @@ function AgentToggle() {
  *  runs, so a button that forgot would be the only place the progress lived. */
 function ExportButton() {
   const store = useStore();
-  const job = useShotEditor((s) => s.renderJob);
-  const running = job?.phase === "running";
-  const pct = running && job.total > 0 ? Math.round((job.done / job.total) * 100) : null;
+  // THE LOCK, not the server job: an in-browser export is just as much a
+  // render in progress, and the header used to show nothing at all for one.
+  const exportLock = useShotEditor((s) => s.exportLock);
+  const running = exportLock !== null;
+  const blocked = useShotEditor(exportBlocker);
+  const pct =
+    running && exportLock.total > 0
+      ? Math.round((exportLock.done / exportLock.total) * 100)
+      : null;
   return (
     <button
       type="button"
       className={`btn is-primary header-export${running ? " is-running" : ""}`}
       aria-label="Export"
-      title="Export (⌘E)"
+      // A running export stays reachable: the button is its progress.
+      disabled={!running && blocked !== null}
+      title={!running && blocked !== null ? blocked : `Export${shortcutHint("file.export")}`}
+      // The render's own progress, painted into the button that started it, so
+      // a closed export dialog is not the only place the number lived. Two
+      // stops off the SAME accent: still one primary control in one colour,
+      // not a second signal hue competing with it.
+      {...(pct === null
+        ? {}
+        : { style: { "--export-pct": pct } as React.CSSProperties })}
       onClick={() => store.setExportOpen(true)}
     >
+      <span className="header-glyph" aria-hidden="true">
+        {DOWNLOAD_ICON}
+      </span>
       {pct === null ? "Export" : `Exporting ${pct}%`}
     </button>
   );