@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/viewport.ts

@@ -0,0 +1,234 @@
+// WHICH PIXELS OF THE DOCK ARE ON SCREEN RIGHT NOW.
+//
+// A dock-local store, read by the filmstrip canvases and by nothing else. It
+// exists for one reason: a video row's bar can be a hundred thousand pixels
+// wide at a deep zoom, and a strip that drew and fetched all of it would spend
+// a scrub's worth of work on pixels nobody is looking at, and would ask for a
+// canvas past the width a browser will allocate.
+//
+// ── WHY THIS IS NOT THE SHOT STORE ────────────────────────────────────────
+//
+// Nothing here is document state, nothing here survives a reload, and nothing
+// outside this lane may read it. Putting a scroll position in the shot store
+// would put a value that changes at scroll rate on a channel every panel in the
+// chrome subscribes to. The hot channel is worse still: `useShotEditorHot` is
+// the FRAME, its contract is "the smallest leaf that must repaint every tick",
+// and a scroll position is neither the frame nor on the frame's schedule.
+// See `useLive.ts`'s header for the rule this one obeys.
+//
+// ── THE QUANTUM IS THE POINT ──────────────────────────────────────────────
+//
+// `scrollLeft` moves in single pixels, so an unquantised store would notify
+// every subscriber on every pixel of a pan and a filmstrip would redraw sixty
+// times a second while a hand is on the trackpad. Rounded out to a 64 px grid,
+// a subscriber hears about a scroll once every 64 px and the strip it draws is
+// stable in between. The range is rounded OUTWARD (floor the left, ceil the
+// right), so the quantised range always CONTAINS the real one: a coarser grid
+// can cost an extra column of work, never a missing one.
+//
+// ── AND THE MARGIN IS WHY A QUANTUM IS ENOUGH ─────────────────────────────
+//
+// Work is admitted for the visible range plus `DOCK_VIEWPORT_MARGIN_PX` on each
+// side, which is eight quanta. So a bar that scrolls into view was already
+// drawn before it arrived, and the strip is never caught blank at the leading
+// edge of a pan.
+
+/** The grid the visible range is rounded onto, in content pixels. */
+export const DOCK_VIEWPORT_QUANTUM_PX = 64;
+
+/** How far outside the visible range a bar still draws and still fetches. */
+export const DOCK_VIEWPORT_MARGIN_PX = 512;
+
+/** The scroller this lane measures. One selector, spelled once, because a
+ *  filmstrip finds its own scroller by walking up from its canvas rather than
+ *  being handed one: the dock's row tree is owned by other components and this
+ *  lane must not make them thread a ref through it. */
+export const DOCK_SCROLLER_SELECTOR = ".dock-scroll";
+
+/**
+ * The visible slice of the dock's scrolled content, in CONTENT pixels.
+ *
+ * Content pixels and not client pixels: content x 0 is the left edge of the
+ * scrolled content, which is where the sticky label column sits, so a bar's
+ * content x is `labelWidth + itsLaneLeft` and needs no layout read to know.
+ */
+export interface DockViewport {
+  left: number;
+  right: number;
+}
+
+/**
+ * Nothing has been measured.
+ *
+ * An empty range rather than a zero-width one at the origin, and the
+ * difference matters: `visibleSlice` reads `right <= left` as "no answer" and
+ * admits the bar, because a strip that drew nothing until a scroll event
+ * arrived would be blank on every first paint and permanently blank in any
+ * environment with no layout at all (jsdom measures every element at zero).
+ * A viewport that cannot be measured must not be able to hide a row.
+ */
+export const DOCK_VIEWPORT_UNMEASURED: DockViewport = Object.freeze({ left: 0, right: 0 });
+
+/**
+ * How much of a bar an UNMEASURED viewport admits, in bar-local pixels.
+ *
+ * ponytail: a flat ceiling rather than a second measurement path. It exists so
+ * that "we do not know what is visible" cannot mean "allocate a canvas as wide
+ * as the bar", which at 60 px/frame over a fifty-second film is six figures of
+ * pixels and no browser's problem to solve. Roughly a laptop dock's width, so
+ * a real browser that has not scrolled yet still draws a full screen of strip.
+ */
+export const DOCK_VIEWPORT_UNMEASURED_PX = 2048;
+
+interface Entry {
+  /** Replaced only when the QUANTISED range moves, because `useSyncExternalStore`
+   *  compares snapshots by identity and a fresh object per read is an infinite
+   *  render loop. */
+  view: DockViewport;
+  listeners: Set<() => void>;
+  /** The one coalescing slot. Non-null means a measure is already booked for
+   *  the next frame, so a burst of scroll events costs one measurement. */
+  raf: number | null;
+  detach: () => void;
+}
+
+const entries = new WeakMap<HTMLElement, Entry>();
+
+function quantise(el: HTMLElement): DockViewport {
+  const q = DOCK_VIEWPORT_QUANTUM_PX;
+  const from = el.scrollLeft;
+  const to = from + el.clientWidth;
+  // A scroller with no width has not been laid out. Reporting `{0, 0}` here is
+  // what routes it to the unmeasured branch rather than to "nothing is visible".
+  if (!(to > from) || !Number.isFinite(from) || !Number.isFinite(to)) return DOCK_VIEWPORT_UNMEASURED;
+  return { left: Math.floor(from / q) * q, right: Math.ceil(to / q) * q };
+}
+
+function measure(el: HTMLElement, entry: Entry): void {
+  const next = quantise(el);
+  if (next.left === entry.view.left && next.right === entry.view.right) return;
+  entry.view = next;
+  for (const fn of [...entry.listeners]) {
+    try {
+      fn();
+    } catch {
+      // One subscriber throwing must not stop the others hearing about it.
+      // Same posture as the filmstrip loader's `notify`: this lane is
+      // decoration and may not fail an edit.
+    }
+  }
+}
+
+function schedule(el: HTMLElement, entry: Entry): void {
+  if (entry.raf !== null) return;
+  if (typeof requestAnimationFrame !== "function") {
+    measure(el, entry);
+    return;
+  }
+  entry.raf = requestAnimationFrame(() => {
+    entry.raf = null;
+    measure(el, entry);
+  });
+}
+
+function entryFor(el: HTMLElement): Entry {
+  const existing = entries.get(el);
+  if (existing !== undefined) return existing;
+  const entry: Entry = {
+    view: DOCK_VIEWPORT_UNMEASURED,
+    listeners: new Set(),
+    raf: null,
+    detach: () => {},
+  };
+  const onChange = (): void => schedule(el, entry);
+  // PASSIVE: this listener never calls `preventDefault`, and saying so keeps it
+  // off the critical path of the dock's own wheel handling, which is
+  // deliberately non-passive (see TimelineDock's shift-pan).
+  el.addEventListener("scroll", onChange, { passive: true });
+  // A resize changes the visible range without a scroll event: collapsing the
+  // inspector widens the dock and uncovers bars nothing scrolled to.
+  const ro = typeof ResizeObserver === "function" ? new ResizeObserver(onChange) : null;
+  ro?.observe(el);
+  entry.detach = () => {
+    el.removeEventListener("scroll", onChange);
+    ro?.disconnect();
+    if (entry.raf !== null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(entry.raf);
+    entry.raf = null;
+    entries.delete(el);
+  };
+  entries.set(el, entry);
+  // Measured once up front, so the first subscriber does not have to wait for a
+  // scroll that may never come.
+  entry.view = quantise(el);
+  return entry;
+}
+
+/** The scroller a dock element lives in, or null when it is not in one. */
+export function dockScrollerOf(el: Element | null): HTMLElement | null {
+  if (el === null) return null;
+  try {
+    return el.closest<HTMLElement>(DOCK_SCROLLER_SELECTOR);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The current snapshot. Stable by identity between changes.
+ *
+ * A PURE READ: it never creates an entry and never attaches a listener, because
+ * `useSyncExternalStore` calls its getter during render and a getter with a
+ * side effect is a listener attached from a render React may throw away.
+ * Subscribing is what starts measuring, and React re-reads immediately after
+ * subscribing, so the first measurement is never missed.
+ */
+export function readDockViewport(el: HTMLElement | null): DockViewport {
+  if (el === null) return DOCK_VIEWPORT_UNMEASURED;
+  return entries.get(el)?.view ?? DOCK_VIEWPORT_UNMEASURED;
+}
+
+/** Subscribe to a scroller's quantised range. Returns the unsubscribe, which
+ *  tears the listeners down with the last subscriber: this store holds a DOM
+ *  node, so an entry that outlived its dock would pin a detached tree. */
+export function subscribeDockViewport(el: HTMLElement | null, onChange: () => void): () => void {
+  if (el === null) return () => {};
+  const entry = entryFor(el);
+  entry.listeners.add(onChange);
+  return () => {
+    entry.listeners.delete(onChange);
+    if (entry.listeners.size === 0) entry.detach();
+  };
+}
+
+/** Test hook, and the one way to drop an entry without a subscriber churn. */
+export function resetDockViewport(el: HTMLElement | null): void {
+  if (el === null) return;
+  entries.get(el)?.detach();
+}
+
+/**
+ * The slice of a bar worth drawing, in BAR-LOCAL pixels, or null when the bar
+ * is far enough off screen that neither its pixels nor its tiles are worth
+ * asking for.
+ *
+ * ONE function for the whole rule, so "is this row visible" and "which part of
+ * it do I draw" cannot answer differently: the skip is exactly the case where
+ * the intersection is empty, rather than a second threshold beside it.
+ *
+ * @param barContentX  The bar's left edge in CONTENT pixels (`labelWidth`
+ *                     plus its lane-local left), which the caller already
+ *                     computed to place the bar and must not recompute here.
+ */
+export function visibleSlice(
+  view: DockViewport,
+  barContentX: number,
+  barWidthPx: number,
+): { fromPx: number; toPx: number } | null {
+  if (!(barWidthPx > 0) || !Number.isFinite(barContentX)) return null;
+  if (!(view.right > view.left)) {
+    return { fromPx: 0, toPx: Math.min(barWidthPx, DOCK_VIEWPORT_UNMEASURED_PX) };
+  }
+  const fromPx = Math.max(0, view.left - DOCK_VIEWPORT_MARGIN_PX - barContentX);
+  const toPx = Math.min(barWidthPx, view.right + DOCK_VIEWPORT_MARGIN_PX - barContentX);
+  return toPx > fromPx ? { fromPx, toPx } : null;
+}

package/src/panels/toolbar/BackChip.tsx

@@ -0,0 +1,116 @@
+// The way out of whatever the author is inside, over the canvas they are
+// looking at.
+//
+// ── WHY ANOTHER ONE ─────────────────────────────────────────────────────
+//
+// The rail's back row and the header's shot crumb also climb a level, but the
+// rail collapses under `[` and neither is over the picture. The author's eyes
+// and pointer are on the canvas; the exit belongs there too. The timeline's
+// corner names the place and is not a way out (TimelineDock.tsx).
+//
+// FIRST IN THE CANVAS BAR (CanvasBar.tsx), which is where a back control goes
+// in every editor that has one, and it reads left to right with the rest of
+// the bar: where am I, which pane, how that pane is drawn.
+//
+// ── ABSENT INSIDE AN ISOLATION ──────────────────────────────────────────
+//
+// There the canvas bar shows the isolation trail instead (IsolationTrail.tsx),
+// which names every level and climbs to any of them. `backTarget` below still
+// answers one level up for the rail's back row, which is the Escape ladder's
+// rule (keymap.ts).
+//
+// ── AND IT NAMES NO KEY, BECAUSE ESCAPE IS NOT THIS CLICK ───────────────
+//
+// Never inside a component: an open definition is the Components workspace
+// (`workspaceOf`), so the stage's bar (`StageBar` in CanvasBar.tsx) is not
+// rendered there and Components brings its own way back.
+//
+// The shot title carries no hint, and that is a judgement rather than an
+// oversight. A single Escape from an entered shot DOES run `leaveScene`
+// — but only after the ladder's earlier rungs decline it, so with anything
+// selected, the first press deselects and the shot stays open. This click
+// never deselects. A hint that holds only when the canvas is empty is the same
+// defect one sentence weaker.
+//
+// ABSENT IN THE PROJECT CONTEXT, not disabled. Same call the tool dock makes,
+// for the same reason: at the top of the tree a back control points at nothing,
+// and a permanently dead button is worse than no button.
+import { parentOf } from "@dailies-studio/shot/doc";
+import { CHEVRON_LEFT_ICON } from "../../icons.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+import type { ShotEditorStore } from "../../state/store.js";
+import type { ShotEditorState } from "../../state/types.js";
+import { isSceneContext } from "../../state/viewMode.js";
+
+/**
+ * ONE LEVEL UP, FROM WHEREVER THE AUTHOR IS: the destination's name and the
+ * verb that goes there. This chip and the rail's back row (FilePanel.tsx) both
+ * read it, so the two controls cannot disagree about where "back" is.
+ *
+ * `label` is null when the destination is the Project. Inside a definition
+ * (only the rail's back row reads that branch) it is the Components home.
+ * Isolation climbs with
+ * `exitIsolation`, the store's own one-level verb and the one Escape runs, so
+ * the parent is read the way that verb reads it: from `sceneId`'s scene.
+ */
+export function backTarget(s: ShotEditorState): {
+  label: string | null;
+  run: (store: ShotEditorStore) => void;
+} | null {
+  if (s.doc === null) return null;
+  if (s.editingDef !== null) {
+    return { label: "All components", run: (store) => void store.openComponents() };
+  }
+  const scene = s.sceneId === null ? undefined : s.doc.scenesById[s.sceneId];
+  if (s.isolation !== null && scene?.layersById[s.isolation] !== undefined) {
+    const parent = parentOf(scene, s.isolation);
+    return {
+      label:
+        parent === null
+          ? scene.name
+          : (scene.layersById[parent]?.label ?? parent),
+      run: (store) => store.exitIsolation(),
+    };
+  }
+  if (s.enteredScene === null) return null;
+  // `leaveScene` already clears the isolation, the selection and the armed
+  // tool (see twoContexts.test.ts), so there is no exit chain to repeat here.
+  return { label: null, run: (store) => store.leaveScene() };
+}
+
+export function BackChip() {
+  const store = useStore();
+  const open = useShotEditor((s) => s.name !== null);
+  // The project context, which is where this chip has nothing to point at.
+  // `isSceneContext` also asks `doc !== null`, which costs nothing here: the
+  // store writes `name` and `doc` together, so `open` above already said it.
+  const inScene = useShotEditor(isSceneContext);
+  const isolated = useShotEditor(
+    (s) => s.editingDef === null && s.isolation !== null,
+  );
+  // INSIDE AN ISOLATION THE TRAIL IS THE WAY OUT (IsolationTrail.tsx): it
+  // names every level and climbs to any of them, so a one-level chip beside
+  // it would be a second, shorter copy.
+  if (!open || inScene || isolated) return null;
+
+  const label = "Shots";
+  const title = "Back to all shots, to arrange the project";
+
+  // A plain 28px control in the docked canvas bar. It used to sit in an island
+  // wrapper of its own (`.back-bar`), which went with the floating panels.
+  return (
+    <button
+      type="button"
+      className="back-chip"
+      data-testid="strip-back"
+      title={title}
+      aria-label={title}
+      onClick={() => backTarget(store.getState())?.run(store)}
+    >
+      <span className="tool-icon" aria-hidden="true">
+        {CHEVRON_LEFT_ICON}
+      </span>
+      <span className="back-chip-label">{label}</span>
+    </button>
+  );
+}

package/src/panels/toolbar/CameraViewBar.tsx

@@ -1,70 +1,139 @@
-// The camera verbs that belong to the WORKING PANE, floating over it.
+// The camera verbs, as ONE menu button over the stage.
 //
-// ── WHY THESE THREE ARE TOGETHER, AND WHY THEY ARE HERE ─────────────────
+// ── WHY A MENU WITH WORDS, AND NOT THREE GLYPHS ─────────────────────────
 //
-// A frustum you can look at but not act on is decoration. What makes a free
-// view worth having is the ROUND TRIP between it and the camera, and the round
-// trip is exactly these: point the camera at what I am looking at, keep
-// pointing it there while I move, and frame this selection. They sit over the
-// pane they act on rather than in the inspector, because the pane is where the
-// author's eyes and pointer already are.
+// This bar was three unlabelled icon buttons (a camera, a link, a fit) whose
+// sentences lived in `title` tooltips, and the founder's verdict was "I don't
+// know what these options are, when they apply, or whether they are good". The
+// words had been cut for 310px of control-strip budget. A menu button costs
+// one control's width, keeps every word on a row an author can read, and has a
+// CAPTION: the one sentence that names the two cameras, which nothing on
+// screen had ever said.
 //
-// Mounted only while the working pane is on screen: in camera mode there is no
-// "this view" to align to, and a control that is present but meaningless is
-// worse than one that is absent.
+// THE WORD "Camera" IS THE GROUP'S, not the trigger's. The canvas bar labels
+// each pane's group with the pane's own word (CanvasBar.tsx), right before
+// this button, so the trigger is a glyph square like the shading one beside
+// the "3D" word. A word on both would read "Camera Camera".
 //
-// ── THE FOLLOW TOGGLE IS NOT CALLED A LOCK ──────────────────────────────
+// Every word comes from `state/cameraVerbs.ts`, which the View menu and the
+// shortcut manual read too. This file decides only what is disabled and why.
 //
-// Blender's long-running complaint about the equivalent toggle is that its name
-// says the opposite of what it does — nothing is locked, the camera is being
-// moved by every orbit — and that it is easy to forget it is on. So it is named
-// for what happens, it is `aria-pressed`, and the affordance that stops it
-// being forgotten is drawn INSIDE the pane (see Overlays' FollowBadge). A
-// checkbox in a panel nobody is looking at while they orbit is how the Blender
-// version gets forgotten.
+// ── SHOWN WHEREVER THE CAMERA PANE IS ───────────────────────────────────
 //
-// A FLOATING SIBLING of the stage, never a wrapper. See App.tsx's header.
+// CanvasBar mounts it in the camera pane's group, so it is on screen in the
+// Camera and Split layouts, which is where a document OPENS and where Pilot
+// does its work. In the 3D layout the camera pane is not on screen and
+// neither is this menu: its verbs are in the View menu, "Move camera to
+// view" included. Hidden inside a component definition (no shot camera) and
+// under Video (no furniture on a finished picture).
+//
+// The menu portals through `Popover`, exactly as `ShadingBar` does and for its
+// reasons: it closes on an outside press and on Escape, flips when the window
+// is short, and clamps on-screen.
+import { useRef, useState } from "react";
+import { Popover } from "@dailies-studio/ui";
 import { useShotEditor, useStore } from "../../state/context.js";
+import { inDefinition, videoView } from "../../state/viewMode.js";
+import { shortcutHint } from "../../state/shortcuts.js";
+import { CAMERA_VERB_KEYS, TWO_CAMERAS, cameraVerb } from "../../state/cameraVerbs.js";
+import type { CameraVerb } from "../../state/cameraVerbs.js";
+import { CAMERA_ICON } from "../../icons.js";
 
 export function CameraViewBar() {
   const store = useStore();
-  const mode = useShotEditor((s) => s.stageLayout.mode);
-  const follows = useShotEditor((s) => s.cameraFollowsView);
-  const hasSelection = useShotEditor((s) => s.selection.length > 0);
   const open = useShotEditor((s) => s.name !== null);
-  if (!open || mode === "camera") return null;
+  const pilot = useShotEditor((s) => s.pilot);
+  const driver = useShotEditor((s) => s.cameraDriver);
+  const hasSelection = useShotEditor((s) => s.selection.length > 0);
+  const inDef = useShotEditor(inDefinition);
+  const watching = useShotEditor(videoView);
+  const inShot = useShotEditor((s) => s.enteredScene !== null);
+  const anchor = useRef<HTMLButtonElement>(null);
+  const [menuOpen, setMenuOpen] = useState(false);
+  if (!open || inDef || watching) {
+    // Returning null is not an unmount: a menu left open when the gate closed
+    // would come back open. ShadingBar's own note.
+    if (menuOpen) setMenuOpen(false);
+    return null;
+  }
+
+  const driven =
+    driver === null
+      ? null
+      : `The camera is driven by ${driver}, so the shot camera has no effect while it is.`;
+
+  /** Why a verb cannot run right now, or null when it can. */
+  const refusal = (key: CameraVerb): string | null => {
+    if (key === "addMove") return inShot ? null : "Open a shot to add a move to it.";
+    if (driven !== null) return driven;
+    if (key === "frameSelection" && !hasSelection) return "Select a layer first.";
+    return null;
+  };
+  const run = (key: CameraVerb): void => {
+    setMenuOpen(false);
+    switch (key) {
+      case "pilot":
+        store.setPilot(!pilot);
+        return;
+      case "toView":
+        store.alignCameraToWorkingView();
+        return;
+      case "frameSelection":
+        store.fitCameraToSelection();
+        return;
+      case "addMove":
+        store.addShotAtPlayhead();
+        return;
+    }
+  };
 
   return (
     <div className="camera-view-bar" role="group" aria-label="Camera" data-testid="camera-view-bar">
       <button
+        ref={anchor}
         type="button"
-        className="btn"
-        title="Point the shot camera where this view is looking (⌥C)"
-        onClick={() => store.alignCameraToWorkingView()}
-      >
-        Align camera
-      </button>
-      <button
-        type="button"
-        className={`btn${follows ? " is-armed" : ""}`}
-        aria-pressed={follows}
-        title="Keep the shot camera pointed where this view looks, while you orbit"
-        onClick={() => store.setCameraFollowsView(!follows)}
-      >
-        Follow view
-      </button>
-      <button
-        type="button"
-        className="btn"
-        // Disabled rather than refusing, because "nothing is selected" is
-        // visible on screen — a refusal message is for the cases the author
-        // cannot see, like a shot painting over the value they just wrote.
-        disabled={!hasSelection}
-        title="Frame the selected layers"
-        onClick={() => store.fitCameraToSelection()}
+        className={`tool-button has-caret${pilot ? " is-armed" : ""}`}
+        aria-haspopup="menu"
+        aria-expanded={menuOpen}
+        aria-label="Camera"
+        title={TWO_CAMERAS}
+        onClick={() => setMenuOpen((v) => !v)}
       >
-        Fit to selection
+        <span className="tool-icon" aria-hidden="true">
+          {CAMERA_ICON}
+        </span>
+        <span className="tool-caret" aria-hidden="true" />
       </button>
+      <Popover open={menuOpen} anchor={anchor} onClose={() => setMenuOpen(false)}>
+        <div className="shading-menu camera-menu" role="menu" data-testid="camera-menu">
+          <div className="camera-menu-caption" role="presentation">
+            {TWO_CAMERAS}
+          </div>
+          {CAMERA_VERB_KEYS.map((key) => {
+            const spec = cameraVerb(key);
+            const why = refusal(key);
+            const armed = key === "pilot" && pilot;
+            return (
+              // THE SENTENCE HANGS ON THE WRAPPER: a disabled button fires no
+              // pointer events, so its own `title` could never open in the one
+              // state that needs explaining.
+              <span key={key} style={{ display: "flex" }} title={why ?? spec.sentence}>
+                <button
+                  type="button"
+                  role={key === "pilot" ? "menuitemcheckbox" : "menuitem"}
+                  {...(key === "pilot" ? { "aria-checked": pilot } : {})}
+                  className={`tool-button${armed ? " is-armed" : ""}`}
+                  disabled={why !== null}
+                  onClick={() => run(key)}
+                >
+                  {spec.label}
+                  <span className="camera-menu-key">{shortcutHint(spec.menuId).trim()}</span>
+                </button>
+              </span>
+            );
+          })}
+        </div>
+      </Popover>
     </div>
   );
 }

package/src/panels/toolbar/CanvasBar.tsx

@@ -0,0 +1,117 @@
+// The canvas bar: the docked row over the canvas cell (`.control-strip`).
+//
+// Left to right: the way out (BackChip, or the IsolationTrail inside an
+// isolation), one group per pane on screen, then
+// the stage's badges as the spring and the zoom, pushed right, and last the
+// panel toggles, which every workspace keeps.
+// It names the PLACE and how each pane is drawn. The docked footer under the
+// canvas carries the tools and the view track (ToolFooter.tsx).
+//
+// ── ONE GROUP PER PANE, OVER ITS PANE ───────────────────────────────────
+//
+// Each group starts with the pane's word from `LAYOUT_SPECS` and holds that
+// pane's controls. In the split the camera group starts AT THE SEAM, so each
+// group sits over the pane it acts on, unless that would clip a control. The
+// CSS does the placing (`.canvas-bar-lead.is-split` in styles/canvas.css) from
+// `--split-x`, which App writes beside `--rail-w`, so this renders no geometry
+// of its own.
+//
+// The pane that zoom and fit address (`activePane`) has its word in accent
+// ink, so in a split the bar says which half the zoom buttons will move.
+//
+// ── THE VIEW TRACK IS IN THE FOOTER ─────────────────────────────────────
+//
+// Clean view and 3D | Split | Camera (ViewModeBar) answer for the whole
+// canvas, not for one pane, so they never sat inside a pane's group. They
+// rode this bar right of the spring until the Paper redesign moved them to
+// the right half of the tool footer, which is where Paper draws them. What
+// that freed is why this bar's give order is short now (canvas.css).
+//
+// ── WHAT IS ON SCREEN, NOT WHAT IS CHOSEN ───────────────────────────────
+//
+// Video draws the camera pane over any layout without writing it
+// (`shownLayoutMode`). The groups follow the picture.
+//
+// ── NEVER EMPTY, NEVER A NEW HEIGHT ─────────────────────────────────────
+//
+// Zoom and the badges are here at every level and in Video, and the bar is
+// always one `--panel-head-h` row, so the canvas cell under it never moves.
+import type { ReactNode } from "react";
+import { useShotEditor } from "../../state/context.js";
+import { layoutSpec } from "../../state/layouts.js";
+import { shownLayoutMode } from "../../state/viewMode.js";
+import type { StagePane } from "../../stage/panes.js";
+import { StageBadges } from "../header/StatusBadges.js";
+import { ZoomControls } from "../header/ZoomControls.js";
+import { BackChip } from "./BackChip.js";
+import { CameraViewBar } from "./CameraViewBar.js";
+import { IsolationTrail } from "./IsolationTrail.js";
+import { ShadingBar } from "./ShadingBar.js";
+import { PanelToggles } from "./PanelToggles.js";
+import { WorkPlaneBar } from "./WorkPlaneBar.js";
+import { CellSlot } from "../stage/cellSlots.js";
+import { workspaceOf } from "../../state/workspace.js";
+
+export function CanvasBar() {
+  // A MODE BRINGS ITS OWN BAR: the way back and its own verbs, portalled into
+  // the slot below (cellSlots.tsx). The stage's panes and zoom mean nothing
+  // over a board, a graph or a code editor.
+  const stage = useShotEditor((s) => workspaceOf(s) === "stage");
+  return (
+    <>
+      <CellSlot name="bar" className="canvas-bar-mode" />
+      {stage ? <StageBar /> : null}
+      {/* Last in every workspace: a mode's bar is its own, the panels are the
+          window's. */}
+      <PanelToggles />
+    </>
+  );
+}
+
+function StageBar() {
+  const open = useShotEditor((s) => s.name !== null);
+  const layout = useShotEditor(shownLayoutMode);
+  const activePane = useShotEditor((s) => s.activePane);
+  // No document, no panes: the bar keeps its row and holds nothing to act on.
+  const working = open && layout !== "camera";
+  const camera = open && layout !== "working";
+  const split = working && camera;
+  return (
+    <>
+      <div className={`canvas-bar-lead${split ? " is-split" : ""}`}>
+        <BackChip />
+        <IsolationTrail />
+        {working ? (
+          <PaneGroup pane="working" active={activePane === "working"}>
+            <ShadingBar />
+            <WorkPlaneBar />
+          </PaneGroup>
+        ) : null}
+      </div>
+      {camera ? (
+        <PaneGroup pane="camera" active={activePane === "camera"}>
+          <CameraViewBar />
+        </PaneGroup>
+      ) : null}
+      {/* The badges are the bar's spring: they push the zoom to the end and
+          are the first thing to give when the bar runs short (canvas.css). */}
+      <StageBadges />
+      <ZoomControls />
+    </>
+  );
+}
+
+function PaneGroup(props: { pane: StagePane; active: boolean; children: ReactNode }) {
+  const word = layoutSpec(props.pane).label;
+  return (
+    <div
+      className={`canvas-pane${props.active ? " is-active" : ""}`}
+      role="group"
+      aria-label={`${word} pane`}
+      data-testid={`canvas-pane-${props.pane}`}
+    >
+      <span className="canvas-pane-word">{word}</span>
+      {props.children}
+    </div>
+  );
+}