@dailies-studio/shot-editor 0.1.0

package/src/stage/bridgeClient.ts

@@ -0,0 +1,278 @@
+// The stage's half of the bridge: a tiny store the chrome writes INTO through
+// `window.__shotStudio`, and that `StageApp` subscribes to.
+//
+// Splitting it out of the React tree is what lets `boot()` install the handle
+// SYNCHRONOUSLY, before anything renders. The chrome polls
+// `iframe.contentWindow.__shotStudio` on load and must never observe a
+// rendered-but-bridgeless stage; if the handle lived in a component it could
+// only appear after the first commit, and the poll would race it.
+import { clearRasterCache } from "@dailies-studio/shot";
+import { markPerf } from "./PerfHud.js";
+import type { Doc3D, Scene3D } from "@dailies-studio/shot/doc";
+import type {
+  ShadingMode,
+  ShotBridgeHandlers,
+  ShotScreenQuad,
+  ShotStageBridge,
+  ShotTool,
+  ShotView,
+  SnapGuide,
+  StageInset,
+  StageLayout,
+  StagePane,
+  WorkingView,
+} from "../bridgeTypes.js";
+import { SHOT_BRIDGE_VERSION } from "../bridgeTypes.js";
+import { clampSplitRatio } from "./panes.js";
+import { clampShading } from "./shading.js";
+import { INITIAL_WORKING_VIEW } from "./workingView.js";
+
+export interface StageClientState {
+  /** A chrome has registered its handlers. Nothing renders before this. */
+  connected: boolean;
+  doc: Doc3D | null;
+  /** MASTER frame. */
+  frame: number;
+  selection: readonly string[];
+  view: ShotView;
+  /** Live only while a gesture is snapping. */
+  guides: readonly SnapGuide[];
+  tool: ShotTool;
+  /** How many panes are on screen. Pushed by the chrome; never derived here,
+   *  so there is one owner of "what is the author looking at". */
+  layout: StageLayout;
+  workingView: WorkingView;
+  /** "Camera follows this view" is armed. The stage brackets its orbit with the
+   *  framing gesture lane while it is, and draws the badge that says so. */
+  cameraFollowsView: boolean;
+  /** The isolated subtree's root layer id, or null for the whole scene. The
+   *  stage derives the members, the camera and the dimming from the document
+   *  it already has — see `setIsolation`. */
+  isolation: string | null;
+  /** Inside isolation, has the author taken the working camera? False means the
+   *  derived orthographic head-on rig draws the pane; true means the ordinary
+   *  orbit rig does. Meaningless while `isolation` is null. */
+  isolationOrbit: boolean;
+  /** The working pane's shading. Workspace state, mirrored from the chrome. */
+  shading: ShadingMode;
+  /** How far the chrome's floating panels reach into the stage, per side. Paint
+   *  only: the overlay lays its furniture inside it and `paneRects` ignores it
+   *  entirely. Zero until the chrome says otherwise. */
+  inset: StageInset;
+}
+
+const INITIAL: StageClientState = {
+  connected: false,
+  doc: null,
+  frame: 0,
+  selection: [],
+  view: { zoom: 1, panX: 0, panY: 0 },
+  guides: [],
+  tool: "select",
+  layout: { mode: "camera", splitRatio: 0.5 },
+  workingView: INITIAL_WORKING_VIEW,
+  cameraFollowsView: false,
+  isolation: null,
+  isolationOrbit: false,
+  shading: "solid",
+  inset: { top: 0, right: 0, bottom: 0, left: 0 },
+};
+
+/** Finite and non-negative on every side. A boundary, like `clampSplitRatio`:
+ *  a NaN here becomes a NaN `y` on a `<text>` and the badge vanishes with no
+ *  error anywhere. */
+function clampInset(inset: StageInset): StageInset {
+  const one = (n: number): number => (Number.isFinite(n) && n > 0 ? n : 0);
+  return { top: one(inset.top), right: one(inset.right), bottom: one(inset.bottom), left: one(inset.left) };
+}
+
+export interface StageClient {
+  readonly bridge: ShotStageBridge;
+  getState(): StageClientState;
+  subscribe(listener: () => void): () => void;
+  /** The chrome's handlers, or null before connect. The stage calls up through
+   *  these; every one must be treated as possibly-absent. */
+  handlers(): ShotBridgeHandlers | null;
+  /** How the stage answers `selectionQuads()`. Registered by the overlay layer
+   *  once it exists; until then the bridge answers null. */
+  setQuadSource(source: ((pane: StagePane) => readonly ShotScreenQuad[] | null) | null): void;
+  /** How the stage answers `fitView()`. Registered by the viewport. */
+  setFitter(fit: (() => ShotView) | null): void;
+  /** …and `fitWorkingView()`. A separate registration rather than one fitter
+   *  returning both, because the two are computed from different things: the
+   *  camera fit needs the PANE SIZE and the working fit needs the DOCUMENT. */
+  setWorkingFitter(fit: (() => WorkingView) | null): void;
+  setDisposer(dispose: () => void): void;
+}
+
+export function createStageClient(): StageClient {
+  let state: StageClientState = INITIAL;
+  const listeners = new Set<() => void>();
+  let handlers: ShotBridgeHandlers | null = null;
+  let quadSource: ((pane: StagePane) => readonly ShotScreenQuad[] | null) | null = null;
+  let fitter: (() => ShotView) | null = null;
+  let workingFitter: (() => WorkingView) | null = null;
+  let dispose: (() => void) | null = null;
+
+  function set(patch: Partial<StageClientState>): void {
+    let changed = false;
+    for (const key of Object.keys(patch) as (keyof StageClientState)[]) {
+      if (!Object.is(state[key], patch[key])) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    state = { ...state, ...patch };
+    for (const l of listeners) l();
+  }
+
+  const bridge: ShotStageBridge = {
+    version: SHOT_BRIDGE_VERSION,
+    connect(next) {
+      handlers = next;
+      set({ connected: true });
+    },
+    loadDoc(doc) {
+      // A DIFFERENT document opening, not an edit echo: the span from here to
+      // the next presented frame is the author's "how long until I see it".
+      // markPerf no-ops without ?perf=1. Set BEFORE the state write, because
+      // the commit this write triggers is the frame that settles it.
+      if (state.doc?.id !== doc.id) markPerf("open→frame");
+      set({ doc });
+    },
+    seek(frame) {
+      // Integer frames over a rational fps is the engine's invariant, and this
+      // is the boundary a float could sneak through: a chrome that computed a
+      // frame from a pixel position would otherwise hand the studio clock a
+      // fractional one and break byte-identity against the export.
+      set({ frame: Math.round(frame) });
+    },
+    setSelection(ids) {
+      set({ selection: [...ids] });
+    },
+    selectionQuads(pane = "camera") {
+      return quadSource === null ? null : quadSource(pane);
+    },
+    setTool(tool) {
+      set({ tool });
+    },
+    setSnapGuides(guides) {
+      // Identity-stable when both are empty, so the common case (no gesture
+      // running) never notifies and never re-renders the stage.
+      if (guides.length === 0 && state.guides.length === 0) return;
+      set({ guides: [...guides] });
+    },
+    setView(view) {
+      set({ view });
+    },
+    fitView() {
+      if (fitter === null) return state.view;
+      const view = fitter();
+      set({ view });
+      return view;
+    },
+    setStageLayout(layout) {
+      // Gaining a working pane is the compile-storm moment (SplitRenderer +
+      // clay mount); the span to the next presented frame measures it.
+      if (layout.mode !== "camera" && state.layout.mode === "camera") markPerf("split→frame");
+      // Clamped HERE and not only in the chrome. This is a boundary: the ratio
+      // becomes a scissor rect, and a NaN scissor draws nothing with no error
+      // anywhere — the stage does not get to assume its caller was careful.
+      set({ layout: { mode: layout.mode, splitRatio: clampSplitRatio(layout.splitRatio) } });
+    },
+    setIsolation(isolation) {
+      // Validated against the DOCUMENT here, not trusted: the chrome's id can
+      // be one edit behind the stage's doc, and an isolation naming a layer
+      // that no longer exists would leave the pane pointed at nothing with no
+      // way for the author to get out.
+      const scene = state.doc === null ? null : sceneWithLayer(state.doc, isolation);
+      // THE ORBIT MODE RESETS WITH THE SUBTREE. Entering a second card while
+      // the first one's camera was taken would otherwise start it in a
+      // perspective pose derived from somewhere else entirely, and the head-on
+      // entry view — the whole point of isolation — would only appear the first
+      // time.
+      set({ isolation: isolation !== null && scene !== null ? isolation : null, isolationOrbit: false });
+    },
+    setIsolationOrbit(taken) {
+      set({ isolationOrbit: taken === true });
+    },
+    setStageInset(inset) {
+      const next = clampInset(inset);
+      // Identity-stable when nothing moved: the chrome writes this from a raw
+      // store subscription, so it fires on every pointermove of a panel resize
+      // and `set`'s `Object.is` check would see a fresh object every time.
+      const at = state.inset;
+      if (at.top === next.top && at.right === next.right && at.bottom === next.bottom && at.left === next.left) {
+        return;
+      }
+      set({ inset: next });
+    },
+    setWorkingView(workingView) {
+      set({ workingView });
+    },
+    fitWorkingView() {
+      if (workingFitter === null) return state.workingView;
+      const workingView = workingFitter();
+      set({ workingView });
+      return workingView;
+    },
+    setShadingMode(mode) {
+      // Clamped at the boundary like the split ratio: an unknown mode from a
+      // careless caller means the default clay, not a pane that draws nothing.
+      set({ shading: clampShading(mode) });
+    },
+    setCameraFollowsView(on) {
+      set({ cameraFollowsView: on === true });
+    },
+    closeDoc() {
+      set({ doc: null, selection: [] });
+    },
+    clearCaches() {
+      // Called right after closeDoc. The chrome's two calls run synchronously
+      // before the stage's doc-null commit can land, so the clear disposes
+      // textures some planes still bind — safe, because no GL draw happens
+      // between synchronous JS and that commit (draws ride commits), and the
+      // unmount commit runs cleanups, never a draw of the old doc.
+      clearRasterCache();
+    },
+    dispose() {
+      dispose?.();
+      dispose = null;
+      handlers = null;
+    },
+  };
+
+  return {
+    bridge,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    handlers: () => handlers,
+    setQuadSource(source) {
+      quadSource = source;
+    },
+    setFitter(fit) {
+      fitter = fit;
+    },
+    setWorkingFitter(fit) {
+      workingFitter = fit;
+    },
+    setDisposer(fn) {
+      dispose = fn;
+    },
+  };
+}
+
+/** The scene holding a layer, or null. Exported for the isolation guard and for
+ *  the stage's own scoping — "is this id still real" is the question both ask,
+ *  and a second implementation of it is how the two drift. */
+export function sceneWithLayer(doc: Doc3D, layerId: string | null): Scene3D | null {
+  if (layerId === null) return null;
+  for (const scene of Object.values(doc.scenesById)) {
+    if (scene.layersById[layerId] !== undefined) return scene;
+  }
+  return null;
+}

package/src/stage/feed.ts

@@ -0,0 +1,243 @@
+// The mutable handoff between the half of the stage that lives INSIDE the
+// canvas and the half that lives outside it.
+//
+// WHY A MUTABLE OBJECT AND NOT STATE. The pointer lane sits on the container
+// div (pointer events land on the DOM, not on the scene graph) while picking
+// and projection need the live camera, which only exists inside `<Canvas>`.
+// Passing the camera out through React state would make every pointermove a
+// render; passing a mutable box in makes it a property read. The same pattern
+// the 2D lane's `feed.ts` uses, for the same reason.
+//
+// `version` is the ONE thing React is told about, and only when a selected
+// quad actually moved by more than half a pixel — see `quadMoved`. Everything
+// else on here is read imperatively at the moment it is needed.
+//
+// ── EVERY QUERY NAMES A PANE ────────────────────────────────────────────
+//
+// The stage can show two views of one scene at once (panes.ts), and the two
+// have DIFFERENT CAMERAS. So there is no such thing as "the ray at x, y": the
+// same canvas pixel unprojects to two different rays, picks two different
+// layers and, in the working pane, sorts its hits by a different rule
+// (`pickLayersByDistance` vs `pickLayers`). Making the pane the first argument
+// rather than a mode on the feed is deliberate — a mode would be one more piece
+// of state to keep in step with the pointer, and getting it stale means the
+// author's click is answered by the pane they are not pointing at.
+//
+// COORDINATES ARE PANE-LOCAL CSS px, from the pane's top-left. `paneAt` returns
+// exactly that pairing, so the caller passes through what it was handed and
+// there is no second place where a pane origin gets subtracted.
+import type { Camera, Matrix4, Ray } from "three";
+import type { GestureKind, ResizeHandle } from "@dailies-studio/shot/doc";
+import type { StagePane } from "./panes.js";
+import type { GizmoGrab } from "./gizmoMath.js";
+import type { LayerFrame, ScreenQuad, WorldQuad } from "./project.js";
+
+/** What a press on the current selection turned out to be. */
+export interface Grab {
+  kind: GestureKind;
+  /** resize only. */
+  handle?: ResizeHandle;
+  /** The grabbed layer's group matrix, for the gesture's plane. */
+  matrixWorld: Matrix4;
+  /**
+   * resize only: which way the grabbed handle points ON SCREEN, in radians from
+   * the quad's centre, measured in the overlay's own y-DOWN space.
+   *
+   * COMPUTED HERE, WHERE THE QUAD IS. The cursor has to be the handle's real
+   * direction and not its NAME: these are projected trapezoids, so the "nw"
+   * corner of a layer rolled 45 degrees points north, and a name-based
+   * `nwse-resize` would sit at 45 degrees to the edge the author is about to
+   * drag. Under the working pane's free orbit a name means even less.
+   *
+   * The pointer lane buckets it to the four bidirectional builtins and never
+   * derives it a second time, so the drawn handle, the hit test and the cursor
+   * all come off one number.
+   */
+  handleAngle?: number;
+  /**
+   * resize and roll: the projected CENTRE of the quad the handle belongs to, in
+   * the same pane-local px `handleAngle` was measured about.
+   *
+   * CARRIED, not re-derived. The rotate lane used to look the centre up again
+   * from `feed.quadsCamera[feed.ids.indexOf(selection[0])]`, and `selection[0]`
+   * is whichever id sorts LOWEST in document order — not the one the author
+   * grabbed. With a multi-selection the first pointermove jumped by the angle
+   * between the two centres, and when the lowest id had no frame at the
+   * playhead `indexOf` answered -1 and the press died silently.
+   */
+  centre?: readonly [number, number];
+  /**
+   * scale only: the UNION box's four world corners, snapshotted at the press.
+   *
+   * The drag needs them to place the pivot at the corner opposite the grabbed
+   * handle, and it needs them FROZEN: the box is rebuilt from the members every
+   * frame, so a live reference would move the pivot with the very layers the
+   * scale is moving and the ratio would chase itself.
+   */
+  union?: WorldQuad;
+}
+
+export interface StageFeed {
+  /** Bumped by the in-canvas half when the overlay needs repainting. */
+  version: number;
+  /**
+   * Bumped whenever a layer object MOUNTS OR UNMOUNTS in the three scene graph.
+   *
+   * `collectFrames` walks the whole graph, and its answer is a pure function of
+   * the graph's SHAPE — the matrices inside it are live references, so motion
+   * needs no invalidation and neither does a seek that only moves things. What
+   * it cannot see is membership, and membership changes for a reason no
+   * document value predicts: a GLB or an instance module resolves and suspense
+   * commits a subtree that was not there a frame ago. This counter is that
+   * event, and it is what lets the walk be memoised across an orbit.
+   */
+  sceneEpoch: number;
+  /**
+   * The overlay's OWN repaint hook, registered by the component that draws
+   * the quads and called by `StageTools` when they move.
+   *
+   * It used to be a `bumpOverlay` reducer on `StageApp`, and that shape was a
+   * double render: a camera dolly with a selection committed the whole stage
+   * (ShotRuntime included, whose dependency-less `ClockDriver` effect draws a
+   * GL frame per commit), then the quads moved, then `bumpOverlay` committed
+   * it all AGAIN. Registering the listener at the overlay leaf means a moved
+   * quad re-renders one SVG and zero canvases.
+   */
+  onOverlay: (() => void) | null;
+  /** The CURRENT selection, in the order both quad arrays are parallel to. One
+   *  list for both panes: the selection is one selection, only its projection
+   *  differs. */
+  ids: string[];
+  /** Screen quads for `ids` in each pane, in that pane's LOCAL CSS px. A pane
+   *  that is not on screen has an empty array rather than stale quads — an
+   *  overlay drawn from last layout's numbers is worse than no overlay. */
+  quadsCamera: ScreenQuad[];
+  quadsWorking: ScreenQuad[];
+  /** Parallel to `ids`: is each selected layer locked? Written here rather than
+   *  looked up by the overlay because `collectFrames` is the one place that
+   *  already knows, and a second lookup could disagree with the `grabAt` that
+   *  refuses the handle. */
+  locked: boolean[];
+  /**
+   * The multi-select's ONE box, in world and projected into each pane, or null.
+   *
+   * Null covers three different situations on purpose, because the overlay
+   * treats them identically: fewer than two layers selected, a selection that
+   * is not coplanar, and one that is not axis-parallel (`unionQuad` says which).
+   * In all three the members keep their own outlines and their own handles.
+   *
+   * All three projections in ONE field so they cannot go out of step: the world
+   * corners are the pivot the drag measures against and the screen corners are
+   * what the author grabbed, and a frame where those disagreed would scale
+   * about a box nobody drew.
+   */
+  union: { world: WorldQuad; camera: ScreenQuad | null; working: ScreenQuad | null } | null;
+  /** Every alive layer this frame, for picking and the marquee. Null before
+   *  the canvas has committed once. */
+  frames: readonly LayerFrame[] | null;
+  /**
+   * The working pane's camera, or null when that pane is off screen.
+   *
+   * WRITTEN BY `StageTools` AT PRIORITY 0 AND READ BY `SplitRenderer` AT
+   * PRIORITY 1, which is the whole reason it lives on the feed rather than
+   * being owned by the renderer that draws with it. The camera that answers a
+   * pick and the camera that drew the pixel are then the same object in the
+   * same state, by construction — a second camera written a frame later would
+   * put every working-pane click an orbit-step away from what the author saw.
+   *
+   * A `Camera` and not a `PerspectiveCamera`: isolation puts an ORTHOGRAPHIC
+   * camera in this slot (see stage/isolation.ts), and every consumer here —
+   * raycasting, projection, `renderBins` — takes the base class already.
+   */
+  workingCamera: Camera | null;
+  /** Ray-pick at a point in the pane's own CSS px. Front-most first, where
+   *  "front-most" is paint order in the camera pane and nearest in the working
+   *  one. Null until the canvas exists; empty for a pane that is not on
+   *  screen. */
+  pick: ((pane: StagePane, x: number, y: number) => string[]) | null;
+  /**
+   * The outline a CLICK here would select, already projected — or null over
+   * nothing.
+   *
+   * Separate from `pick` because the answer is a QUAD and not an id list: the
+   * overlay draws it, and projecting one frame stage-side is cheaper and more
+   * honest than sending an id to the chrome and waiting a round trip for a quad
+   * that will be one pointermove stale by the time it arrives.
+   *
+   * It walks to the same container `onPick` selects (`layerOps.outermost`), so
+   * the outline the author sees before they click IS the thing the click
+   * selects. A second walk here would be that bug.
+   */
+  hoverQuad: ((pane: StagePane, x: number, y: number) => ScreenQuad | null) | null;
+  /** Marquee, in the same coordinates. */
+  pickRect:
+    | ((pane: StagePane, rect: { x0: number; y0: number; x1: number; y1: number }) => string[])
+    | null;
+  /** Is this press a transform gesture on the current selection, and which?
+   *  Null for a press that is a selection change instead. */
+  grabAt:
+    | ((pane: StagePane, x: number, y: number, selection: readonly string[]) => Grab | null)
+    | null;
+  /** The camera ray through a point, for the move gesture's unprojection.
+   *  Null for a pane that has no camera on screen — a pane with no camera has
+   *  no ray, and answering with the other pane's would silently drag the layer
+   *  along a plane the author is not looking at. */
+  rayAt: ((pane: StagePane, x: number, y: number) => Ray | null) | null;
+  /**
+   * Did a press in the WORKING pane land on the shot camera's frustum gizmo,
+   * and on which part?
+   *
+   * No pane argument, because there is only one pane this can be true in: the
+   * frustum gizmo IS the camera pane's camera, drawn as an object. It cannot
+   * appear inside the view it represents.
+   */
+  frustumHit: ((x: number, y: number) => "body" | "apex" | null) | null;
+  /**
+   * Did a press in the WORKING pane land on one of the selection's three drag
+   * arms, and on which?
+   *
+   * No pane argument, for `frustumHit`'s reason: the gizmo is drawn in the
+   * working pane alone (the camera pane has resize handles, which the working
+   * pane deliberately does not — see `grabAt`).
+   *
+   * The answer carries the arm's ORIGIN AND DIRECTION as a snapshot rather
+   * than a live reference: the gizmo re-centres on the selection every frame,
+   * and an axis line that moved with the layer being dragged along it would
+   * chase its own translation.
+   */
+  gizmoHit: ((x: number, y: number) => GizmoGrab | null) | null;
+  /**
+   * The arm the pointer is over, or null.
+   *
+   * WRITTEN BY THE POINTER LANE, READ INSIDE THE FRAME LOOP, which is what
+   * keeps a hover off React entirely: `MoveGizmo` already runs at priority 0
+   * and re-colours a material there, so highlighting costs one uniform write
+   * per frame and zero renders. Blender's gizmos highlight under the cursor and
+   * ours did not, which is the difference between "is this grabbable" being
+   * obvious and being something the author finds out by trying.
+   */
+  hoverArm: GizmoGrab["axis"] | null;
+}
+
+export function createStageFeed(): StageFeed {
+  return {
+    version: 0,
+    sceneEpoch: 0,
+    onOverlay: null,
+    ids: [],
+    quadsCamera: [],
+    quadsWorking: [],
+    locked: [],
+    union: null,
+    frames: null,
+    workingCamera: null,
+    pick: null,
+    hoverQuad: null,
+    pickRect: null,
+    grabAt: null,
+    rayAt: null,
+    frustumHit: null,
+    gizmoHit: null,
+    hoverArm: null,
+  };
+}