@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/panes.ts

@@ -6,25 +6,41 @@
 // a second GL context doubles a budget this lane already owns outright (the
 // shot runtime owns the present, see the lane note in CLAUDE.md). Not two
 // iframes: the stage iframe may never remount. So the pane boundary exists only
-// as numbers, and it has exactly two readers — the renderer's scissor rect and
-// the pointer lane's hit test.
+// as numbers, and every reader takes them from here: the renderer's scissor
+// rect, the pointer lane's hit test, and the chrome's split handle (`splitX`).
 //
 // They must read the SAME numbers. If the divider the renderer draws to and the
 // divider the pointer tests against differ by even one column, a press in that
 // column is answered by the other pane's camera, and the symptom is "picking is
 // off by half a screen" rather than anything that looks like a layout bug.
 //
-// THREE-FREE ON PURPOSE. The chrome lays out the divider handle from these same
-// rects, and the chrome may not import three (test/sourceHygiene.test.ts).
+// THREE-FREE ON PURPOSE. App.tsx places the divider handle and writes
+// `--split-x` (where the canvas bar's camera group starts) through `splitX`,
+// and the chrome may not import three (test/sourceHygiene.test.ts).
+import type { StageInset } from "../bridgeTypes.js";
 import type { Viewport } from "./view.js";
 
+/** The two panes, as a VALUE as well as a type: the chrome's layout table is a
+ *  `Record` over these, so a third pane would fail to compile there rather than
+ *  arriving with no word for it. */
+export const STAGE_PANES = ["camera", "working"] as const;
+
 /** Which of the two views a coordinate, a camera or a query belongs to. */
-export type StagePane = "camera" | "working";
+export type StagePane = (typeof STAGE_PANES)[number];
+
+/** The three layouts the stage can be in. ONE WRITTEN FORM: the union below is
+ *  derived from this list, and `state/layouts.ts` keys its table on the union,
+ *  so the members exist in exactly one place across the whole chrome. */
+export const STAGE_LAYOUT_MODES = ["camera", "split", "working"] as const;
+
+/** Which editor is on screen. The chrome's words, keys and menu ids for these
+ *  are in `state/layouts.ts`; this is only the vocabulary itself. */
+export type StageLayoutMode = (typeof STAGE_LAYOUT_MODES)[number];
 
 /** What the stage is showing. Editor state: it is never written to the document
  *  and never reaches an export. */
 export interface StageLayout {
-  mode: "camera" | "split" | "working";
+  mode: StageLayoutMode;
   /** The WORKING pane's fraction of the viewport WIDTH. Read only in "split". */
   splitRatio: number;
 }
@@ -55,6 +71,53 @@ export function clampSplitRatio(ratio: number): number {
   return Math.max(MIN_SPLIT_RATIO, Math.min(MAX_SPLIT_RATIO, ratio));
 }
 
+/** No chrome at all: the identity inset, so a caller with nothing to subtract
+ *  can pass a value rather than a special case. */
+export const NO_INSET: StageInset = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/**
+ * Where the split's seam falls, in canvas px from the left.
+ *
+ * ── WHY THE INSET IS AN ARGUMENT ────────────────────────────────────────
+ *
+ * The ratio is the WORKING pane's share of the width, and the width it used to
+ * be a share of was the whole window. But the window's left edge is under the
+ * rail and its right edge is under the inspector, so at 1366 with the panels
+ * open a 0.5 split put the seam at 683 while the visible canvas ran from 212 to
+ * 1066 — the working pane got 471 visible px against the camera pane's 383, and
+ * a fifth of the working pane was behind the rail. The ratio has to divide the
+ * part the author can SEE, or it is not the thing they think they are dragging.
+ *
+ * The pane RECTS still partition the whole viewport (the scissor draws
+ * full-bleed under the chrome, see `insetRect`); only where the seam lands
+ * moves. Both readers of the seam — the renderer's scissor and the chrome's
+ * divider handle — call this, so they cannot disagree by a column.
+ *
+ * A degenerate inset (more chrome than window, which a mid-animation panel
+ * width can briefly report) falls back to dividing the whole width: a seam
+ * somewhere is recoverable, a NaN seam is a scissor that draws nothing.
+ */
+export function splitX(ratio: number, width: number, inset: StageInset = NO_INSET): number {
+  const left = Math.max(0, inset.left);
+  const clear = width - left - Math.max(0, inset.right);
+  const x =
+    Number.isFinite(clear) && clear > 1
+      ? left + Math.round(clampSplitRatio(ratio) * clear)
+      : Math.round(width * clampSplitRatio(ratio));
+  return Math.min(Math.max(1, x), width - 1);
+}
+
+/** The inverse of `splitX`: what ratio a seam at `x` represents. The drag
+ *  handle's `onChange` reads a pixel and has to store a ratio, and doing that
+ *  arithmetic at the call site is how the two ends drift apart. */
+export function splitRatioAt(x: number, width: number, inset: StageInset = NO_INSET): number {
+  const left = Math.max(0, inset.left);
+  const clear = width - left - Math.max(0, inset.right);
+  return clampSplitRatio(
+    Number.isFinite(clear) && clear > 1 ? (x - left) / clear : x / Math.max(1, width),
+  );
+}
+
 /**
  * The two panes' rectangles.
  *
@@ -65,10 +128,17 @@ export function clampSplitRatio(ratio: number): number {
  * A pane that is not on screen is `null`, not a zero-sized rect. Null cannot be
  * scissored by accident and cannot be hit-tested by accident; a 0x0 rect can be
  * both, silently.
+ *
+ * THE RECTS PARTITION THE WHOLE VIEWPORT even with an inset. The scissor draws
+ * full-bleed under the docked chrome on purpose, so a pane never shrinks; the
+ * inset only moves where the SEAM lands, via `splitX`. Which pixels are visible
+ * is `insetRect`'s question, and it is asked separately by the two things that
+ * have to be seen rather than drawn.
  */
 export function paneRects(
   layout: StageLayout,
   viewport: Viewport,
+  inset: StageInset = NO_INSET,
 ): { working: PaneRect | null; camera: PaneRect | null } {
   const { width, height } = viewport;
   // The same guard view.ts's `fitView` applies, for the same reason: the
@@ -82,16 +152,95 @@ export function paneRects(
   // A viewport too narrow to hold two panes shows the CAMERA one. It is the
   // pane that is the export, so it is the one worth keeping when only one fits.
   if (width < 2) return { working: null, camera: full };
-  // ROUNDED, and the camera pane takes the remainder rather than its own
-  // rounding: two independently rounded widths can leave a one-column seam that
-  // neither pane owns, and a column nobody draws is a visible tear.
-  const split = Math.min(Math.max(1, Math.round(width * clampSplitRatio(layout.splitRatio))), width - 1);
+  // THROUGH `splitX`, never inline: the chrome's divider handle positions
+  // itself from the same call, and a seam computed twice is a seam that drifts
+  // by a column — which reads as "picking is off" rather than as a layout bug.
+  const split = splitX(layout.splitRatio, width, inset);
   return {
     working: { x: 0, y: 0, width: split, height },
     camera: { x: split, y: 0, width: width - split, height },
   };
 }
 
+/**
+ * The part of a pane the chrome is NOT covering.
+ *
+ * ── WHY THIS IS NOT `paneRects`' JOB ────────────────────────────────────
+ *
+ * The pane rect is the SCISSOR rect, and the stage draws full-bleed under the
+ * chrome on purpose: the docked panels sit over a picture that continues
+ * behind them, and insetting the scissor would leave dead gutters instead. So `inset`
+ * is paint information for everything that has to be SEEN rather than drawn —
+ * the overlay's furniture, and the derived head-on framing.
+ *
+ * That distinction is exactly the bug this was added for. An orbit rig framed
+ * to the whole canvas is fine, because the author pans and zooms to compensate.
+ * A DERIVED frame promises "this subject, whole, fitted", and the author has
+ * nothing to compensate with — so fitting it to a box a third of which is under
+ * the timeline dock breaks the promise silently. See `headOnCamera` and the
+ * camera pane's `fit`.
+ *
+ * ── AN INTERSECTION, NOT FOUR SUBTRACTIONS ──────────────────────────────
+ *
+ * The inset describes the WINDOW's clear band, not each pane's. Subtracting all
+ * four sides from a pane charges every pane for chrome it does not touch: in a
+ * split, the camera pane starts at the seam and is nowhere near the rail, yet
+ * it lost another `inset.left` off its left edge and slid right by that much,
+ * while the working pane ends at the seam and paid for an inspector on the far
+ * side of it. So this intersects the pane with the window's clear rect instead.
+ * For a pane that IS the whole viewport the two are the same arithmetic, which
+ * is why the head-on framing this was written for is unchanged.
+ *
+ * `viewport` defaults to the pane's own far corner, so a caller holding a
+ * full-viewport pane can still pass two arguments and mean it.
+ *
+ * DEGENERATE INSETS COLLAPSE TO THE PANE, never to a zero or negative box: a
+ * chrome that reported more furniture than there is canvas (a narrow window, a
+ * mid-animation panel width) would otherwise produce a zero-width frustum,
+ * which projects everything to NaN and draws nothing with no error anywhere.
+ * A pane that misses the clear band entirely collapses the same way.
+ */
+export function insetRect(
+  pane: PaneRect,
+  inset: StageInset,
+  viewport: Viewport = { width: pane.x + pane.width, height: pane.y + pane.height },
+): PaneRect {
+  const x = Math.max(pane.x, Math.max(0, inset.left));
+  const y = Math.max(pane.y, Math.max(0, inset.top));
+  const width = Math.min(pane.x + pane.width, viewport.width - Math.max(0, inset.right)) - x;
+  const height = Math.min(pane.y + pane.height, viewport.height - Math.max(0, inset.bottom)) - y;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return pane;
+  return { x, y, width, height };
+}
+
+/**
+ * The same visible rect as `insetRect`, in PANE-LOCAL px.
+ *
+ * ── WHY THE LOCAL ANSWER NEEDS ITS OWN FUNCTION ─────────────────────────
+ *
+ * `insetRect` answers in CANVAS coordinates, which is what a caller comparing
+ * panes to each other wants. But the two things that lay furniture out inside a
+ * pane — the overlay's `<g transform="translate(pane.x pane.y)">`, and
+ * `fitView`, which is handed the pane's SIZE and reads every screen coordinate
+ * from the pane's top-left — are already in the pane's own space. They need the
+ * canvas answer minus the pane origin, which is all this does.
+ *
+ * SUBTRACTING A RAW INSET EDGE INSTEAD IS THE DOUBLE-COUNT. The inset is the
+ * WINDOW's clear band, not any one pane's, so `working.width - inset.right`
+ * charges the working pane of a split for an inspector that is on the far side
+ * of the SEAM and covers none of it: that is what put the nav gizmo an
+ * inspector's width left of the pane edge, 300px into the middle of the
+ * picture. The mirror case is the camera pane, whose local x is measured from
+ * the seam, so `inset.left` there subtracts a rail that pane never touches.
+ * Going through `insetRect` avoids both, because it intersects the pane with
+ * the clear band rather than subtracting all four sides — and collapses to the
+ * whole pane on a degenerate inset, which here means a local rect at 0,0.
+ */
+export function clearOf(pane: PaneRect, inset: StageInset, viewport: Viewport): PaneRect {
+  const clear = insetRect(pane, inset, viewport);
+  return { x: clear.x - pane.x, y: clear.y - pane.y, width: clear.width, height: clear.height };
+}
+
 /**
  * Which pane a canvas-space point is in, and where it lands inside it.
  *

package/src/stage/project.ts

@@ -21,12 +21,14 @@
 //      the layer up to a shadow-blur radius outside its own box.
 //
 //   2. DISTANCE IS NOT THE ORDER. Every layer draws with `depthTest: false` and
-//      `renderOrder = layer.order`, so what covers what is DOCUMENT order and
-//      not camera distance — a shot deliberately lets a layer sit further away
+//      `renderOrder = layer.order` (the layer lists' paint walk), so what
+//      covers what is DOCUMENT order and not camera distance: a shot
+//      deliberately lets a layer sit further away
 //      yet on top. A raycaster sorts by distance, so its "first hit" is
 //      routinely a layer the author cannot see. Ordering the hits by `order`
 //      descending is what makes the front-most hit the one under the cursor.
 import { Matrix4, Ray, Vector3 } from "three";
+import type { Camera, Object3D, OrthographicCamera, PerspectiveCamera } from "three";
 
 /** A layer's four world-space corners, in TL, TR, BR, BL order. */
 export type WorldQuad = readonly [Vector3, Vector3, Vector3, Vector3];
@@ -42,6 +44,9 @@ export interface LayerFrame {
   /** Design px. */
   size: readonly [number, number];
   matrixWorld: Matrix4;
+  /** The group `matrixWorld` belongs to, so the overlay pass can bring it up
+   *  to date (`updateWorldMatrix`) before reading it. Absent in tests. */
+  object?: Object3D;
   /** Paint order. Higher is nearer the viewer, whatever the depth says. */
   order: number;
   /** Locked layers are skipped by picking and marquee, and by nothing else. */
@@ -169,13 +174,28 @@ export interface Projector {
  * `setViewOffset`. So the working-area pan and zoom need no separate term here
  * and cannot drift out of step with what the renderer drew.
  */
+/**
+ * Scratch for `toScreen`. It NEVER escapes: the function returns a plain
+ * `[number, number]` built from `v.x`/`v.y`, so no caller can retain it, and
+ * the body is synchronous with no callback between the write and the read, so
+ * it cannot re-enter. Two panes projecting in one frame call this in sequence,
+ * each finishing before the next begins.
+ *
+ * Worth pooling rather than trusting the allocator: this is the most-called
+ * allocation in the stage's frame, roughly 90-120 times from TransformGizmo
+ * alone (75 arc points, 12 pad corners, 6 arm ends) plus four per quad per
+ * pane from StageTools. Same hoist `_guideA`/`_guideB` already take in
+ * StageApp, for the same reason.
+ */
+const _project = new Vector3();
+
 export function toScreen(
   point: Vector3,
   camera: Projector,
   width: number,
   height: number,
 ): [number, number] {
-  const v = new Vector3().copy(point).applyMatrix4(camera.matrixWorldInverse).applyMatrix4(
+  const v = _project.copy(point).applyMatrix4(camera.matrixWorldInverse).applyMatrix4(
     camera.projectionMatrix,
   );
   // Perspective divide is inside applyMatrix4 for a Vector3 (three divides by
@@ -183,6 +203,40 @@ export function toScreen(
   return [((v.x + 1) / 2) * width, ((1 - v.y) / 2) * height];
 }
 
+const _depth = new Vector3();
+const DEG = Math.PI / 180;
+
+/**
+ * World units per CSS pixel AT A POINT, which is what turns a fixed screen
+ * length (the transform gizmo's `GIZMO_PX`, the camera body's clamps) into a
+ * world one.
+ *
+ * Both camera classes, because isolation swaps an ORTHOGRAPHIC camera into the
+ * working pane's slot (StageTools) and a perspective-only formula would size a
+ * gizmo off a `fov` that camera does not have — reading `undefined` and
+ * drawing arms of length NaN, which is a gizmo that silently disappears inside
+ * isolation.
+ *
+ * Perspective: the visible height at the point's own view depth, over the pane.
+ * Orthographic: its frustum height over the pane, which has no depth term at
+ * all — that is what orthographic means.
+ */
+export function worldPerPixel(camera: Camera, at: Vector3, paneHeight: number): number {
+  const height = Math.max(1, paneHeight);
+  const ortho = camera as OrthographicCamera;
+  if (ortho.isOrthographicCamera === true) {
+    const zoom = ortho.zoom > 0 ? ortho.zoom : 1;
+    return Math.abs(ortho.top - ortho.bottom) / zoom / height;
+  }
+  const perspective = camera as PerspectiveCamera;
+  const fov = Number.isFinite(perspective.fov) ? perspective.fov : 50;
+  // View-space z runs NEGATIVE in front of the camera, so the depth is its
+  // negation — and it is floored off zero, because a point sitting exactly at
+  // the eye would otherwise give every length zero.
+  const depth = Math.max(-_depth.copy(at).applyMatrix4(camera.matrixWorldInverse).z, 1e-3);
+  return (2 * Math.tan((fov * DEG) / 2) * depth) / height;
+}
+
 export function screenQuad(
   frame: LayerFrame,
   camera: Projector,
@@ -300,6 +354,17 @@ export function pickLayersByDistance(ray: Ray, frames: readonly LayerFrame[]): s
   return hits.map((h) => h.id);
 }
 
+/**
+ * A hit list with every MASK after every other hit, each side in its own
+ * order. A mask draws nothing of its own (gap 7), so a click goes to what the
+ * author sees. It matters in the working pane, which sorts by distance and can
+ * put a mask in front of the content it mattes. A mask alone under the cursor
+ * is still picked.
+ */
+export function maskHitsLast(ids: readonly string[], isMask: (id: string) => boolean): string[] {
+  return [...ids.filter((id) => !isMask(id)), ...ids.filter(isMask)];
+}
+
 /**
  * Layers whose quad intersects a screen-space rectangle — the marquee.
  *