@dailies-studio/shot-editor 0.1.0

package/src/app/App.tsx

@@ -0,0 +1,394 @@
+// The shell.
+//
+// ── THE ONE STRUCTURAL RULE ──────────────────────────────────────────────
+//
+// `<StagePanel>` is the UNCONDITIONAL, UNKEYED FIRST CHILD of the shell root,
+// and every panel floats over it. Nothing this component renders may reorder,
+// reparent, key or conditionally wrap it, because a remount costs a full iframe
+// document load, a fresh WebGPU adapter request, every layer raster redrawn and
+// a dead stage for at least one connect poll. `test/stageIdentity.test.tsx`
+// asserts `===` node identity across every shell state.
+//
+// The corollary, inherited from the canvas lane and just as load-bearing: NO
+// ANCESTOR OF THE STAGE IFRAME MAY CARRY `transform`, `filter`,
+// `backdrop-filter`, `contain` OR `will-change`. Each of those makes the
+// element a containing block for fixed-position descendants, and the iframe is
+// `position: fixed; inset: 0`; the failure is the stage silently sizing itself
+// to a panel instead of the viewport.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { FilePanel } from "../panels/files/FilePanel.js";
+import { HelpSection } from "../panels/help/HelpSection.js";
+import { ResizeHandle } from "../panels/ResizeHandle.js";
+import { RAIL_WIDTH } from "../state/panelSize.js";
+import { Header } from "../panels/header/Header.js";
+import { InspectorPanel } from "../panels/inspector/InspectorPanel.js";
+import { StagePanel } from "../panels/stage/StagePanel.js";
+import { TimelineDock } from "../panels/timeline/TimelineDock.js";
+import { ToolDockBar } from "../panels/toolbar/ToolDockBar.js";
+import { ViewModeBar } from "../panels/toolbar/ViewModeBar.js";
+import { ShadingBar } from "../panels/toolbar/ShadingBar.js";
+import { CameraViewBar } from "../panels/toolbar/CameraViewBar.js";
+import { ExportDialog } from "../panels/export/ExportDialog.js";
+import { StageMenu } from "../panels/stage/StageMenu.js";
+import { MaterialPicker } from "../panels/material/MaterialPicker.js";
+import { AgentPanel } from "../panels/agent/AgentPanel.js";
+import { AudioPreviewBridge } from "../audio/index.js";
+import { subscribeStudioEvents } from "../state/renderEvents.js";
+import { useShotEditor, useStore } from "../state/context.js";
+import type { StageInset } from "../bridgeTypes.js";
+
+export function App() {
+  const store = useStore();
+  const [stageError, setStageError] = useState<string | null>(null);
+  const onConnectError = useCallback((message: string | null) => setStageError(message), []);
+
+  const name = useShotEditor((s) => s.name);
+  const error = useShotEditor((s) => s.error);
+  const reportedStageError = useShotEditor((s) => s.stageError);
+  const exportOpen = useShotEditor((s) => s.exportOpen);
+  const agentOpen = useShotEditor((s) => s.agentOpen);
+
+  useOpenFromUrl();
+  useKeymap();
+  useExternalChangeRelay();
+
+  // Subscribed for the WHOLE session, not while the dialog is open: closing the
+  // dialog must not stop the render or lose its progress, and the header badge
+  // reads the same store bit.
+  useEffect(() => subscribeStudioEvents(store), [store]);
+
+  const railCollapsed = useShotEditor((s) => s.railCollapsed);
+  const inspectorCollapsed = useShotEditor((s) => s.inspectorCollapsed);
+  // The MODE alone, not the whole layout: the divider's own drag writes the
+  // ratio dozens of times a second, and subscribing to that here would
+  // re-render the entire shell on every frame of it. `--split-x` carries the
+  // position, written imperatively beside `--rail-w`.
+  const stageLayout = { mode: useShotEditor((s) => s.stageLayout.mode) };
+
+  // The dragged sizes reach CSS as variables on the shell, which is what lets
+  // the control strip and the timeline dock position themselves off the rail
+  // without any of the three knowing about the others.
+  //
+  // WRITTEN IMPERATIVELY, OUTSIDE REACT. The values exist only to become two
+  // custom properties, and subscribing them here re-rendered the entire shell
+  // — every panel, every dock row — on every pointermove of a resize drag,
+  // to do a style write. A raw store subscription writes the same two
+  // variables and renders nothing.
+  //
+  // `--rail-w` is omitted while the rail is collapsed ON PURPOSE: an inline
+  // style beats a class rule, so writing it unconditionally would override
+  // `.is-rail-collapsed { --rail-w: 0px }` and the strip would keep a gap
+  // where the hidden rail used to be.
+  const shellRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    const el = shellRef.current;
+    if (el === null) return;
+    let raf = 0;
+    // ── WHAT CAN MOVE A PANEL EDGE ────────────────────────────────────
+    //
+    // The variables are cheap style writes and are done on every store change.
+    // `measureInset` is not: it is seven `getBoundingClientRect` reads, which
+    // is a FORCED LAYOUT, and this is a raw store subscription — so it ran once
+    // per playback frame, for four numbers that a seek cannot possibly change.
+    //
+    // These seven fields are every piece of state that moves an edge. `name` is
+    // on the list because the header's title is content-sized and a long
+    // document name wraps the strip; the window's own resize comes through the
+    // ResizeObserver instead, which forces the measure outright.
+    let lastEdges = "";
+    const edgesOf = (s: ReturnType<typeof store.getState>): string =>
+      [
+        s.railCollapsed,
+        s.inspectorCollapsed,
+        s.dockCollapsed,
+        s.railWidth,
+        s.dockHeight,
+        s.agentOpen,
+        s.name,
+      ].join("|");
+    const write = (force: boolean): void => {
+      raf = 0;
+      const s = store.getState();
+      if (s.railCollapsed) el.style.removeProperty("--rail-w");
+      else el.style.setProperty("--rail-w", `${s.railWidth}px`);
+      el.style.setProperty("--dock-h", `${s.dockHeight}px`);
+      // Where the stage's own divider is, so the handle can sit on it without
+      // the shell re-rendering per frame of the drag.
+      el.style.setProperty("--split-x", `${Math.round(s.stageLayout.splitRatio * window.innerWidth)}px`);
+      const edges = edgesOf(s);
+      if (!force && edges === lastEdges) return;
+      lastEdges = edges;
+      // ── AND THE STAGE IS TOLD WHERE IT IS COVERED ────────────────────
+      //
+      // The stage iframe is pinned `inset: 0` behind these panels, so its
+      // panes are the whole window and it cannot see any of this. It used to
+      // carry a hardcoded 116 for the top edge and nothing at all for the
+      // other three, which put two mode bars behind the opaque header and the
+      // G / R / S pill behind the 232px left rail — where it has never once
+      // been visible in the default layout.
+      //
+      // MEASURED, not derived from the CSS constants. `.control-strip` is
+      // `flex-wrap: wrap` and grows past any constant on a narrow window, and
+      // `.timeline-dock` is content-driven under a max-height. Reading the
+      // boxes is both shorter than reproducing the layout and correct when
+      // someone changes it.
+      store.stage()?.setStageInset(measureInset(el));
+    };
+    // COALESCED TO THE FRAME. This is a raw store subscription so it fires on
+    // every pointermove of a panel resize, and `getBoundingClientRect` is a
+    // forced layout read against a layout that same move just invalidated.
+    let forced = false;
+    const schedule = (force: boolean): void => {
+      forced = forced || force;
+      if (raf !== 0) return;
+      raf = requestAnimationFrame(() => {
+        const f = forced;
+        forced = false;
+        write(f);
+      });
+    };
+    write(true);
+    const unsubscribe = store.subscribe(() => schedule(false));
+    // The store cannot see a WINDOW resize, and that is exactly when the
+    // control strip wraps and the top edge moves — so its tick FORCES the
+    // measure rather than asking the store whether anything changed.
+    const observer = new ResizeObserver(() => schedule(true));
+    observer.observe(el);
+    return () => {
+      if (raf !== 0) cancelAnimationFrame(raf);
+      unsubscribe();
+      observer.disconnect();
+    };
+  }, [store]);
+
+  return (
+    <div
+      ref={shellRef}
+      className={`shell${railCollapsed ? " is-rail-collapsed" : ""}${
+        inspectorCollapsed ? " is-inspector-collapsed" : ""
+      }`}
+    >
+      {/* FIRST, unconditional, unkeyed. See the header. */}
+      <StagePanel onConnectError={onConnectError} />
+
+      <Header />
+      <aside className="left-rail">
+        <FilePanel />
+        {/* Pinned to the rail's bottom (margin-top: auto) — the manual lives in
+            the corner that is otherwise empty, and stays put when the layer
+            tree grows because the rail scrolls as one column. */}
+        <HelpSection />
+      </aside>
+      {/* A SIBLING of the rail, not a child: the rail scrolls, and a handle
+          inside a scrolling box scrolls away from the edge it is supposed to
+          be on. Positioned off the same --rail-w the rail's width comes from,
+          so the two cannot disagree. */}
+      {railCollapsed ? null : (
+        <ResizeHandle
+          axis="x"
+          getValue={() => store.getState().railWidth}
+          sign={1}
+          onChange={(w) => store.setRailWidth(w)}
+          onReset={() => store.setRailWidth(RAIL_WIDTH.default)}
+          className="rail-resize"
+          label="Resize the left panel"
+        />
+      )}
+      {/* ── THE SPLIT DIVIDER DRAGS ────────────────────────────────────────
+          `splitRatio` has been in the schema, clamped twice and read by the
+          scissor since the split landed, and NOTHING ever moved it: the stage
+          drew a 1px seam and `panes.ts`'s header claimed the chrome laid out a
+          handle from the same rects. It did not.
+
+          CHROME-SIDE, because a stage-side handle needs a new stage-to-chrome
+          bridge message AND `pointerEvents: auto` inside an overlay whose
+          `pointerEvents: none` is a stated invariant — without it every drag
+          would end the moment the cursor crossed the divider.
+
+          Against `window.innerWidth`, which IS the pane width: the stage iframe
+          is pinned `inset: 0`, so its viewport is the whole window (panes.ts).
+          `clampSplitRatio` and `setStageLayout` already bound the value twice,
+          so there is no third validation here. */}
+      {stageLayout.mode !== "split" ? null : (
+        <ResizeHandle
+          axis="x"
+          getValue={() => store.getState().stageLayout.splitRatio * window.innerWidth}
+          sign={1}
+          onChange={(px) =>
+            store.setStageLayout({
+              ...store.getState().stageLayout,
+              splitRatio: px / Math.max(1, window.innerWidth),
+            })
+          }
+          onReset={() => store.setStageLayout({ ...store.getState().stageLayout, splitRatio: 0.5 })}
+          className="split-resize"
+          label="Resize the split"
+        />
+      )}
+      {/* ONE control strip along the top of the stage. These three were three
+          separately-positioned floats — tools centred on the bottom edge, the
+          view modes and camera verbs stacked at the top left — which cost the
+          bottom of the frame to a bar and split "what am I doing" across two
+          corners. As one flex row they read left to right in the order a
+          gesture is decided: which pane, what the camera does, which tool. */}
+      <div className="control-strip">
+        <ViewModeBar />
+        <ShadingBar />
+        <CameraViewBar />
+        <ToolDockBar />
+      </div>
+      {agentOpen ? <AgentPanel /> : <InspectorPanel />}
+      <TimelineDock />
+      {/* Renders nothing. Mounted HERE and not in the stage: audio is not part
+          of the document, and the stage is a GL iframe that must never
+          remount. Unconditional, so it survives every shell state. */}
+      <AudioPreviewBridge />
+
+      {exportOpen && name !== null && <ExportDialog onClose={() => store.setExportOpen(false)} />}
+
+      {/* Both portal out of the layout, so they hang here rather than inside a
+          panel: the stage menu opens over whichever half was right-clicked, and
+          the picker is a mode over the whole shell. Unconditional, because each
+          renders nothing until its own state field is set. */}
+      <StageMenu />
+      <MaterialPicker />
+
+      {name === null ? (
+        <div className="empty-state">
+          <h1>Dailies shot</h1>
+          <p>Open a scene, or create one, to start.</p>
+        </div>
+      ) : null}
+
+      <div className="overlay-strip" role="status" aria-live="polite">
+        {[stageError, reportedStageError, error].filter((m): m is string => m !== null).map((message) => (
+          <div key={message} className="overlay-message">
+            <span>{message}</span>
+            <button type="button" onClick={() => store.dismissError()} title="Dismiss">
+              ×
+            </button>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/** `?shot=<name>` on load. The URL is a MIRROR the store writes, and reading it
+ *  once at boot is what makes a reload land back where the author was — the
+ *  same reason the canvas lane mirrors its focused board.
+ *
+ *  With NO name in the URL, open the first document there is. A bare `/shot`
+ *  is how a hosted workspace is entered — nobody types a query string at a
+ *  front door — and greeting a new author with an empty stage hides the fact
+ *  that their project already has content. Guarded on `name === null` so it
+ *  can only ever fill a vacuum, never replace something already open. */
+function useOpenFromUrl(): void {
+  const store = useStore();
+  useEffect(() => {
+    const wanted = new URLSearchParams(window.location.search).get("shot");
+    if (wanted !== null && wanted.length > 0) {
+      void store.openShot(wanted);
+      return;
+    }
+    void (async () => {
+      await store.refreshShots();
+      const first = store.getState().shots[0];
+      if (first !== undefined && store.getState().name === null) {
+        await store.openShot(first.name);
+      }
+    })();
+  }, [store]);
+}
+
+/**
+ * The shell's keydown lane, which is now four lines: every binding lives in
+ * `state/keymap.ts` and every action lives in the store.
+ *
+ * ONE BINDING SITE was the point. A keymap spread across a shell handler, a
+ * panel and a stage is a keymap where "what does ⇧A do" has three answers and
+ * a reader has to find all three to be sure.
+ */
+/** The panels that float over the stage, per edge they eat into. Hidden ones
+ *  measure 0x0 and are skipped, which is what makes a collapsed rail give the
+ *  stage its corner back. */
+const INSET_PANELS = {
+  top: [".shell-header", ".control-strip"],
+  left: [".left-rail"],
+  right: [".inspector", ".agent-panel"],
+  bottom: [".timeline-dock"],
+} as const;
+
+/**
+ * How far the chrome's furniture reaches into the stage, per side, in CSS px.
+ *
+ * ZERO-SIZED ELEMENTS ARE SKIPPED and that is not an optimisation. A
+ * `display: none` panel reports an all-zero rect, and for the RIGHT edge
+ * `shell.right - 0` is the whole window — so a collapsed inspector would tell
+ * the stage its entire width was covered and every badge would render off
+ * screen.
+ */
+function measureInset(shell: HTMLElement): StageInset {
+  const box = shell.getBoundingClientRect();
+  const edge = (selectors: readonly string[], of: (r: DOMRect) => number): number => {
+    let most = 0;
+    for (const selector of selectors) {
+      const el = shell.querySelector(selector);
+      if (el === null) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 || rect.height === 0) continue;
+      most = Math.max(most, of(rect));
+    }
+    return most;
+  };
+  return {
+    top: edge(INSET_PANELS.top, (r) => r.bottom - box.top),
+    left: edge(INSET_PANELS.left, (r) => r.right - box.left),
+    right: edge(INSET_PANELS.right, (r) => box.right - r.left),
+    bottom: edge(INSET_PANELS.bottom, (r) => box.bottom - r.top),
+  };
+}
+
+function useKeymap(): void {
+  const store = useStore();
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (store.handleKey({ ...keyOf(e), target: e.target })) e.preventDefault();
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [store]);
+}
+
+/** The fields the keymap reads, so it can be called with a plain object
+ *  from a test as easily as with a real event. */
+function keyOf(e: KeyboardEvent) {
+  return {
+    key: e.key,
+    shiftKey: e.shiftKey,
+    altKey: e.altKey,
+    ctrlKey: e.ctrlKey,
+    metaKey: e.metaKey,
+    code: e.code,
+  };
+}
+
+/**
+ * The stage relays the server's "this shot changed under you" push (only the
+ * iframe has a live HMR client — see stage/main.tsx). Turn it back into a store
+ * call here.
+ */
+function useExternalChangeRelay(): void {
+  const store = useStore();
+  useEffect(() => {
+    const onMessage = (e: MessageEvent): void => {
+      if (e.origin !== window.location.origin) return;
+      const data = e.data as { type?: unknown; data?: unknown } | null;
+      if (data?.type !== "studio:shot-doc-changed") return;
+      store.adoptExternalChange((data.data ?? {}) as { name?: string; origin?: string; clientId?: string });
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [store]);
+}
+

package/src/audio/index.tsx

@@ -0,0 +1,74 @@
+// The chrome-side bridge that feeds the scheduler from the store with real Web
+// Audio. Renders nothing.
+//
+// MOUNTED FROM THE CHROME, never from the stage: the stage is a GL document in
+// an iframe that must never remount, and audio is not part of the document.
+//
+// Pushes are per-notification but O(1) — the scheduler only acts on play/pause
+// edges, discontinuities and document identity changes (see preview.ts), so the
+// playback rAF path stays free of work. Monitoring level and mute are STORE
+// state (session, never document), so the dock head's controls and this bridge
+// read one bit and cannot disagree.
+import { useEffect } from "react";
+import { useStore } from "../state/context.js";
+import { createAudioPreview } from "./preview.js";
+import type { AudioContextLike, AudioPreview, AudioPreviewDeps } from "./preview.js";
+
+export { SCRUB_JUMP_FRAMES, createAudioPreview } from "./preview.js";
+export type {
+  AudioBufferLike,
+  AudioBufferSourceNodeLike,
+  AudioContextLike,
+  AudioParamLike,
+  AudioPreview,
+  AudioPreviewDeps,
+  GainNodeLike,
+  TransportSnapshot,
+} from "./preview.js";
+
+async function fetchBytes(url: string): Promise<ArrayBuffer> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`GET ${url} -> ${res.status}`);
+  return res.arrayBuffer();
+}
+
+const browserDeps: AudioPreviewDeps = {
+  // Lazy: the first play edge is the user gesture that may create the context.
+  createContext: () => new AudioContext() as unknown as AudioContextLike,
+  fetchBytes,
+  decode: (ctx, bytes) => (ctx as unknown as AudioContext).decodeAudioData(bytes),
+};
+
+/** `create` is the test seam; production gets Web Audio. */
+export function AudioPreviewBridge(props: { create?: () => AudioPreview } = {}): null {
+  const store = useStore();
+  const create = props.create;
+  useEffect(() => {
+    const preview = create ? create() : createAudioPreview(browserDeps);
+    let muted: boolean | null = null;
+    let volume: number | null = null;
+    const push = (): void => {
+      const s = store.getState();
+      if (s.previewMuted !== muted) {
+        muted = s.previewMuted;
+        preview.setMasterMute(muted);
+      }
+      if (s.previewVolume !== volume) {
+        volume = s.previewVolume;
+        preview.setMasterVolume(volume);
+      }
+      // AFTER the monitor bits: an unmute that reschedules must do so knowing
+      // the transport it is rescheduling against, and `update` is what records
+      // it. On the very first push both orders agree, because the scheduler
+      // starts paused.
+      preview.update({ playing: s.playing, frame: s.frame, doc: s.doc });
+    };
+    push();
+    const unsub = store.subscribe(push);
+    return () => {
+      unsub();
+      preview.dispose();
+    };
+  }, [store, create]);
+  return null;
+}