@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/stage/StagePanel.tsx

@@ -12,7 +12,7 @@
 // It renders no conditional siblings, holds no error state and takes no
 // children, because it is the shell's backdrop: `App` mounts it as the
 // unconditional, unkeyed FIRST child of the shell root and the CSS pins it
-// `position: fixed; inset: 0` behind the floating panels. Anything conditional
+// `position: fixed; inset: 0` behind the docked panels. Anything conditional
 // living in here would share a parent with the iframe, and the whole point of
 // the arrangement is that no shell state can reorder, reparent or remount it.
 //
@@ -25,25 +25,86 @@
 // The connect FAILURE therefore reports upward, into the shell's overlay strip,
 // rather than rendering a sibling strip here.
 //
+// HOSTED, THE STAGE WAITS FOR THE CODE HOST (hostApi.ts). No Vite serves the
+// project's modules there: a Service Worker does, from what the host compiled.
+// So the iframe gets its src only once `__dailiesHost.ready` settles (the
+// element itself is mounted from the start, so its identity never moves), and
+// each stage load asks the host before connecting, which re-posts the module
+// epoch and makes sure the Service Worker controls the new document. Locally
+// there is no host and none of this runs.
+//
 // Note main.tsx mounts under StrictMode, so this effect double-runs in dev:
 // connect, abort + attachStage(null), connect again. The abort path rejects
 // with "stage connect aborted" and is swallowed. The iframe ELEMENT is not
 // remounted by that — only the effect re-runs — and any future effect touching
 // the bridge must survive the same double-invoke.
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
+import { useStudioTheme } from "@dailies-studio/ui/theme";
 import { useStore } from "../../state/context.js";
-import { connectStage } from "../../bridge.js";
+import { connectStage, stageBridgeOf } from "../../bridge.js";
+import { dailiesHost } from "../../hostApi.js";
+import { chromePerfFlag } from "../../state/playbackPreparation.js";
+import { bindBoardClipboard } from "../storyboard/boardClipboard.js";
+import { PLAY_CONTROL } from "../timeline/PlayButton.js";
+
+/** The author input a background preparing pass gives way to, in either
+ *  window (`noteAuthorInput`). */
+const AUTHOR_INPUT = ["pointerdown", "keydown", "wheel", "dragover"] as const;
 
-/** The stage URL, resolved ONCE at module load. Only the perf flag crosses the
- *  boundary — never the chrome's whole search string: the chrome rewrites
- *  ?shot/?scene via history.replaceState, and an iframe src interpolating live
- *  location.search would RELOAD the stage (fresh WebGPU adapter, every raster
- *  redrawn) on every document switch. */
-const STAGE_SRC =
-  "/shot-stage.html" +
-  (typeof window !== "undefined" && new URLSearchParams(window.location.search).get("perf") === "1"
-    ? "?perf=1"
-    : "");
+/** Input aimed at the Play control itself: its click, after the press,
+ *  upgrades a background pass, which must still be running then. */
+function atPlayControl(event: Event): boolean {
+  const target = event.target as Partial<Element> | null;
+  return typeof target?.closest === "function" && target.closest(PLAY_CONTROL) !== null;
+}
+/** How far a pointer over the stage moves from where it was last heard
+ *  before the move counts as input, in CSS px. */
+const POINTER_TRAVEL_PX = 3;
+
+/** Whether a drag over the stage can land: only a file does. An asset tile,
+ *  a board card, a planned shot and a Library card land on the board, never
+ *  here. Types only: `getData` is empty until the drop. */
+export function stageDropLands(dt: Pick<DataTransfer, "types">): boolean {
+  return Array.from(dt.types).includes("Files");
+}
+
+/** The stage URL is frozen by StagePanel's ref on its FIRST render. Only the
+ *  perf flag, the gate's two A/B arms (`warmup`, `rasterDensity`), the heavy
+ *  lanes' render-scale arm (`renderScale`) and the initial resolved theme
+ *  cross the boundary, never the
+ *  chrome's whole search string: the chrome rewrites ?shot/?scene via
+ *  history.replaceState, and an iframe src interpolating live location.search
+ *  would RELOAD the stage (fresh GL context, every raster redrawn) on every
+ *  document switch or appearance change. */
+export function stageSrc(theme: "light" | "dark"): string {
+  const search = new URLSearchParams();
+  // ALLOWLISTED, never forwarded verbatim (`chromePerfFlag`, which the
+  // preparing pass's diagnostics read too): this value is interpolated into
+  // the stage's URL, so the set of things it may be is closed on purpose. "1"
+  // is the HUD, "log" is the HUD plus a console echo of every sample.
+  const perf = chromePerfFlag();
+  if (perf !== null) search.set("perf", perf);
+  const own = typeof window === "undefined" ? null : new URLSearchParams(window.location.search);
+  // Same closed set for the warm-up arm (`ShotRuntimeProps.warmup`): the
+  // playback gate's A/B seam, absent from the URL in normal use.
+  const warmup = own?.get("warmup") ?? null;
+  if (warmup === "off" || warmup === "mount") {
+    search.set("warmup", warmup);
+  }
+  // And the raster-density arm (the stage's `STAGE_RASTER_DENSITY`): `on`
+  // cuts the layer rasters at the zoom times the density, one value and no
+  // other.
+  if (own?.get("rasterDensity") === "on") search.set("rasterDensity", "on");
+  // And the render-scale arm (the stage's `STAGE_RENDER_SCALE`): `off` mounts
+  // no playback scale at all, and a step forces that scale on every played
+  // frame. The heavy proofs' seam, never set in normal use.
+  const renderScale = own?.get("renderScale") ?? null;
+  if (renderScale !== null && ["off", "1", "0.85", "0.7", "0.5"].includes(renderScale)) {
+    search.set("renderScale", renderScale);
+  }
+  search.set("theme", theme);
+  return `/shot-stage.html?${search.toString()}`;
+}
 
 export function StagePanel({
   /** Report a stage connect failure to the shell's overlay strip (null clears). */
@@ -52,42 +113,296 @@ export function StagePanel({
   onConnectError: (message: string | null) => void;
 }) {
   const store = useStore();
+  const { resolved: theme } = useStudioTheme();
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const srcRef = useRef(stageSrc(theme));
+  // Read once: the boot script installs it before the chrome runs, or never.
+  const [host] = useState(dailiesHost);
+  const [hostSettled, setHostSettled] = useState(host === undefined);
 
+  useEffect(() => {
+    if (host === undefined) return;
+    let live = true;
+    let off: (() => void) | undefined;
+    host.ready.then(
+      () => {
+        if (live) setHostSettled(true);
+      },
+      (e: unknown) => {
+        if (!live) return;
+        // The stage still loads: a document with no project component draws,
+        // and each instance layer reports its own failure on top of this.
+        const message = `The hosted editor could not start its code host: ${e instanceof Error ? e.message : String(e)}`;
+        store.reportError(message);
+        // A later epoch means the host recovered: clear the error, unless
+        // something else has replaced it since.
+        off = host.subscribe(() => {
+          if (store.getState().error === message) store.reportError(null);
+          off?.();
+          off = undefined;
+        });
+        setHostSettled(true);
+      },
+    );
+    return () => {
+      live = false;
+      off?.();
+    };
+  }, [host, store]);
+
+  // The stage is a same-origin document, so editor furniture can follow a
+  // live appearance change by updating its namespaced root signal in place.
+  // Only furniture descendants consume it; authored content never receives a
+  // generic data-theme or changing root palette. The iframe URL stays frozen
+  // above, which keeps the document, bridge and GL context alive. Re-apply on
+  // load too because Vite HMR may replace the document without replacing this
+  // iframe element.
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const apply = (): void => {
+      try {
+        const root = iframe.contentDocument?.documentElement;
+        if (root !== undefined && root !== null) root.dataset.dailiesStudioTheme = theme;
+      } catch {
+        // The shipped stage is same-origin. If a dev proxy temporarily serves
+        // an error document from elsewhere, appearance is cosmetic and must
+        // not tear down the bridge while it recovers.
+      }
+    };
+    iframe.addEventListener("load", apply);
+    apply();
+    return () => iframe.removeEventListener("load", apply);
+  }, [theme]);
+
+  // ── DROPPING A FILE ON THE PICTURE ──────────────────────────────────────
+  //
+  // The gesture every tool in this class has, and the one an author reaches for
+  // first with a screen recording. Without it the browser's own default wins and
+  // the drop NAVIGATES THE STAGE IFRAME to the file, which tears down the
+  // document, the bridge and the GL context: the app goes blank and the only way
+  // back is a reload.
+  //
+  // Listened for on the stage's own document rather than on the `<iframe>`
+  // element, because a drop lands INSIDE the frame and never reaches the parent
+  // element's handlers. That is the same same-origin reach the theme effect
+  // above makes, and the same `try` for the same reason.
+  //
+  // AT THE DROP POINT (F52). The stage owns its coordinate space, so the drop's
+  // client point crosses once through `designPointAt` (bridge v38), the same
+  // conversion the draw gesture gives its corners. Off the frame pane (the
+  // camera pane over a Shot, an open definition's one pane inside it) it is
+  // null and the drop lands centred, what the Add menu's row does.
   useEffect(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
     const aborter = new AbortController();
+    const bind = (): void => {
+      try {
+        const doc = iframe.contentDocument;
+        if (!doc) return;
+        // `dragover` MUST be prevented or `drop` never fires at all: the spec's
+        // default for dragover is "this is not a drop target". Prevented always,
+        // so the browser never navigates the frame to a file; `dropEffect`
+        // "none" is what tells the author nothing lands here.
+        doc.addEventListener(
+          "dragover",
+          (e) => {
+            e.preventDefault();
+            const dt = (e as DragEvent).dataTransfer;
+            if (dt !== null && dt !== undefined && !stageDropLands(dt)) {
+              dt.dropEffect = "none";
+            }
+          },
+          { signal: aborter.signal },
+        );
+        doc.addEventListener(
+          "drop",
+          (e) => {
+            // Prevented FIRST and unconditionally, before any early return: the
+            // navigation this stops is destructive even for a file the store
+            // will refuse, and returning early without it is how a dropped .zip
+            // would still blank the stage.
+            e.preventDefault();
+            const dt = (e as DragEvent).dataTransfer;
+            const point = store.stage()?.designPointAt(e.clientX, e.clientY) ?? undefined;
+            const file = dt?.files?.[0];
+            if (file === undefined) return;
+            // Through the identical handshake the Frame tool and the Add menu
+            // use: park a click box at the point, then hand over the file. The
+            // kind is the SERVER's sniff, so an unsupported file is refused
+            // there with one message rather than guessed at here.
+            const at = point ?? store.insertOrigin();
+            store.stageHandlers.onDraw("image", [at, at]);
+            void store.completeImageDraw(file).catch((err: unknown) => {
+              store.reportError(err instanceof Error ? err.message : String(err));
+            });
+          },
+          { signal: aborter.signal },
+        );
+        // The board's ⌘C ⌘V on a frame layer: the pointer on the frame focuses
+        // this document, so the native clipboard events fire here, not in the
+        // chrome's.
+        bindBoardClipboard(doc, store, aborter.signal);
+      } catch {
+        // Same as the theme effect: a dev proxy serving a cross-origin error
+        // document must not tear anything down. The cost is that dropping does
+        // nothing until it recovers, which is the pre-existing behaviour.
+      }
+    };
+    iframe.addEventListener("load", bind, { signal: aborter.signal });
+    bind();
+    return () => aborter.abort();
+  }, [store]);
+
+  // ── THE AUTHOR AT WORK, IN BOTH WINDOWS ────────────────────────────────
+  //
+  // What a background preparing pass gives way to, and what its idle wait
+  // starts again on (`noteAuthorInput`): a press, a key, a wheel or a drag
+  // over, in the chrome or on the stage, heard in the capture phase so a
+  // handler that stops the event cannot hide it. On the stage a pointer that
+  // TRAVELS counts too, but not one at rest or jittering in place, which is
+  // the author's usual state over the picture: pausing on it would starve the
+  // pass. Input aimed at the Play control only restarts the wait: its click is
+  // the press of Play that upgrades the pass. The stage's listeners go on
+  // again after each load, since a reminted document has none.
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const aborter = new AbortController();
+    const options = { capture: true, passive: true, signal: aborter.signal };
+    const note = (event: Event): void => store.noteAuthorInput(!atPlayControl(event));
+    const listen = (target: Window): void => {
+      for (const type of AUTHOR_INPUT) target.addEventListener(type, note, options);
+    };
+    let travelledFrom: { x: number; y: number } | null = null;
+    const travel = (e: PointerEvent): void => {
+      const from = travelledFrom;
+      if (from !== null && Math.hypot(e.clientX - from.x, e.clientY - from.y) < POINTER_TRAVEL_PX) return;
+      travelledFrom = { x: e.clientX, y: e.clientY };
+      // The first move only says where the pointer is.
+      if (from !== null) store.noteAuthorInput();
+    };
+    listen(window);
+    const bindStage = (): void => {
+      try {
+        const stage = iframe.contentWindow;
+        if (stage === null) return;
+        travelledFrom = null;
+        listen(stage);
+        stage.addEventListener("pointermove", travel, options);
+      } catch {
+        // The drop effect's reason: a dev proxy's cross-origin error document
+        // must not tear anything down. Its input goes unheard meanwhile.
+      }
+    };
+    iframe.addEventListener("load", bindStage, { signal: aborter.signal });
+    bindStage();
+    return () => aborter.abort();
+  }, [store]);
+
+  // THE PANEL GOING withdraws the stage it expected, settled or not: the
+  // connect effect below has no cleanup before the host settles, so an
+  // unmount then would leave a queued Play waiting for a stage that is gone.
+  // Its own effect, so the settle flip never runs it.
+  useEffect(() => () => store.expectStage(false), [store]);
+
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    // A STAGE IS ON ITS WAY FROM THE FIRST COMMIT, hosted too: the code host's
+    // boot comes before the stage's src, and a press of Play in it is queued
+    // like one during the stage's own boot. Before the return below, and with
+    // no cleanup on that branch, so the expectation holds across the settle
+    // flip: only an unmount or a failed connect withdraws it.
+    store.expectStage(true);
+    if (!hostSettled) return;
+    // ONE CONTROLLER PER CONNECT ATTEMPT: a new attempt (the next load) ends
+    // the one before it, so a local boot, which connects at once and again at
+    // the iframe's load, attaches once.
+    let attempt: AbortController | null = null;
     const connect = (): void => {
+      attempt?.abort();
+      const own = new AbortController();
+      attempt = own;
       onConnectError(null);
-      void connectStage(iframe, store.stageHandlers, { signal: aborter.signal })
+      store.setStageConnectError(null);
+      // A RELOAD IS A NEW STAGE. This runs for the reminted document too, and
+      // the bridge from the old one is dead by then, so dropping it HERE is
+      // what clears `stageInfo` and `stageBusy`. Without it the chrome went on
+      // holding a stale "the stage is ready" beside a stage that had not come
+      // up, which is a lit play button over a canvas that has never drawn.
+      // Paired with the expectation below, a press of Play is queued across a
+      // remint exactly as it is across the first boot.
+      store.attachStage(null);
+      store.expectStage(true);
+      void connectStage(iframe, store.stageHandlers, { signal: own.signal })
         .then((bridge) => {
-          if (!aborter.signal.aborted) store.attachStage(bridge);
+          if (own.signal.aborted) return;
+          store.attachStage(bridge);
+          // A RELOAD IS HEARD AS THE OLD DOCUMENT GOES, not only at the new
+          // one's load: the transport pauses (remembering its start) while
+          // the next stage boots, instead of running sound over a stage that
+          // is gone. A pagehide that keeps the page for the back/forward
+          // cache comes back with no load to reattach it, so it is ignored.
+          iframe.contentWindow?.addEventListener(
+            "pagehide",
+            (e: PageTransitionEvent) => {
+              if (e.persisted) return;
+              store.attachStage(null);
+              store.expectStage(true);
+            },
+            { signal: own.signal },
+          );
         })
         .catch((e) => {
-          if (!aborter.signal.aborted) {
-            onConnectError(e instanceof Error ? e.message : String(e));
+          if (!own.signal.aborted) {
+            // WITHDRAWN ON FAILURE, so a bridge version mismatch or the poll
+            // deadline calls a queued Play off instead of leaving it waiting
+            // for a stage that will never draw. The refusal is the overlay
+            // strip's, which says what actually went wrong.
+            store.expectStage(false);
+            const message = e instanceof Error ? e.message : String(e);
+            onConnectError(message);
+            // And for an agent, which cannot see the strip (stage health).
+            store.setStageConnectError(message);
           }
         });
     };
-    iframe.addEventListener("load", connect);
-    connect(); // the load event may already have fired
+    const onLoad = (): void => {
+      const stage = iframe.contentWindow;
+      // False: the host is reloading the stage to get it controlled.
+      if (host !== undefined && stage !== null && !host.stageLoaded(stage)) return;
+      // The document already attached (its bridge booted before its load
+      // event): nothing new loaded, so the stage is not dropped and taken
+      // again, and a queued Play is not mistaken for a reload's.
+      const attached = store.stage();
+      if (attached !== null && stageBridgeOf(iframe) === attached) return;
+      connect();
+    };
+    iframe.addEventListener("load", onLoad);
+    // Locally the load event may already have fired. Hosted, the src was set
+    // in the commit this effect follows, so the stage's load is still ahead,
+    // and connecting before it would push a document the host has not seen.
+    if (host === undefined) connect();
     return () => {
-      aborter.abort();
-      iframe.removeEventListener("load", connect);
+      attempt?.abort();
+      iframe.removeEventListener("load", onLoad);
       store.attachStage(null);
+      store.expectStage(false);
       // The error belonged to the connection being torn down; it is the shell's
       // state now, so it has to be cleared explicitly rather than dying with a
       // local useState.
       onConnectError(null);
+      store.setStageConnectError(null);
     };
-  }, [store, onConnectError]);
+  }, [store, onConnectError, host, hostSettled]);
 
   return (
     <iframe
       ref={iframeRef}
       className="stage-frame"
-      src={STAGE_SRC}
+      src={hostSettled ? srcRef.current : undefined}
       title="Stage"
       // The stage pins the cursor for the duration of a G / R / S transform,
       // and an iframe cannot without the delegation. Without it

package/src/panels/stage/cellSlots.tsx

@@ -0,0 +1,70 @@
+// THE CELLS A MODE SHOWS ITS CONTENT IN.
+//
+// The four modes (the Storyboard, the material nodes, the Component Studio,
+// Code Studio) used to cover the window. They now show their content in the
+// docked grid's own cells: the left column, the canvas cell, the bottom row
+// and the canvas bar. Each of those cells renders one SLOT, always, and a mode
+// portals its parts into them.
+//
+// ── WHY PORTALS AND NOT FOUR COMPONENTS PER MODE ────────────────────────────
+//
+// A mode is one component with one state: the board's canvas API is shared by
+// its rail and its canvas, the material graph's React Flow provider wraps the
+// zoom its bar shows, the code studio's buffer feeds its editor and its save.
+// Split into per-cell components, every one of those would have to move into
+// the store or a new context. A portal keeps the mode one React subtree
+// (context, refs and events all flow through a portal) and only moves where
+// its pieces land in the DOM.
+//
+// The slots are rendered unconditionally, so a mode that opens finds them
+// already registered and lands in the same commit, never a frame later.
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export type CellName = "left" | "centre" | "bottom" | "bar";
+
+type Slots = Record<CellName, HTMLElement | null>;
+
+interface CellSlotsValue {
+  slots: Slots;
+  register: (name: CellName, el: HTMLElement | null) => void;
+}
+
+const CellSlotsContext = createContext<CellSlotsValue | null>(null);
+
+const EMPTY: Slots = { left: null, centre: null, bottom: null, bar: null };
+
+/** Around the shell. Renders no element of its own, so the stage iframe's
+ *  place in the DOM is untouched. */
+export function CellSlotsProvider({ children }: { children: ReactNode }) {
+  const [slots, setSlots] = useState<Slots>(EMPTY);
+  const register = useCallback((name: CellName, el: HTMLElement | null) => {
+    setSlots((was) => (was[name] === el ? was : { ...was, [name]: el }));
+  }, []);
+  const value = useMemo(() => ({ slots, register }), [slots, register]);
+  return <CellSlotsContext.Provider value={value}>{children}</CellSlotsContext.Provider>;
+}
+
+/** A cell's slot: an empty element a mode portals into. */
+export function CellSlot({ name, className }: { name: CellName; className: string }) {
+  const ctx = useContext(CellSlotsContext);
+  const register = ctx?.register;
+  const ref = useCallback(
+    (el: HTMLDivElement | null) => {
+      register?.(name, el);
+    },
+    [register, name],
+  );
+  return <div ref={ref} className={className} data-cell-slot={name} />;
+}
+
+/**
+ * A mode's part, shown in the named cell. Renders nothing until the cell's
+ * slot is on the page (outside the shell, as in a unit test that mounts a mode
+ * alone, there is no slot and nothing is shown).
+ */
+export function InCell({ name, children }: { name: CellName; children: ReactNode }) {
+  const node = useContext(CellSlotsContext)?.slots[name] ?? null;
+  return node === null ? null : createPortal(children, node);
+}