@dailies-studio/shot-editor 0.1.0

package/src/stage/panes.ts

@@ -0,0 +1,121 @@
+// The stage's two panes, as pure rectangles.
+//
+// ── WHY THE PANES ARE ARITHMETIC AND NOT TWO ELEMENTS ───────────────────
+//
+// The split view is ONE canvas drawn twice under a scissor. Not two canvases:
+// 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.
+//
+// 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).
+import type { Viewport } from "./view.js";
+
+/** Which of the two views a coordinate, a camera or a query belongs to. */
+export type StagePane = "camera" | "working";
+
+/** 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";
+  /** The WORKING pane's fraction of the viewport WIDTH. Read only in "split". */
+  splitRatio: number;
+}
+
+/**
+ * A pane's rectangle in CSS px from the CANVAS TOP-LEFT.
+ *
+ * Top-left because that is the unit every other screen coordinate in this lane
+ * is already in (view.ts, project.ts). GL's bottom-left origin is a conversion
+ * the renderer does at the scissor call, and doing it here would leave two
+ * different y conventions in one file for the pointer lane to pick between.
+ */
+export interface PaneRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export const MIN_SPLIT_RATIO = 0.2;
+export const MAX_SPLIT_RATIO = 0.8;
+
+/** 0.5 for a nonsense ratio, for the same reason `clampZoom` answers 1: a NaN
+ *  here becomes a NaN scissor rect, and a NaN scissor rect draws nothing at all
+ *  with no error anywhere. */
+export function clampSplitRatio(ratio: number): number {
+  if (!Number.isFinite(ratio)) return 0.5;
+  return Math.max(MIN_SPLIT_RATIO, Math.min(MAX_SPLIT_RATIO, ratio));
+}
+
+/**
+ * The two panes' rectangles.
+ *
+ * THE WORKING PANE IS ON THE LEFT and the camera pane on the right, matching
+ * the reference: the camera pane is the one being judged, and a judged image
+ * belongs where a reader's eye finishes rather than where it starts.
+ *
+ * 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.
+ */
+export function paneRects(
+  layout: StageLayout,
+  viewport: Viewport,
+): { working: PaneRect | null; camera: PaneRect | null } {
+  const { width, height } = viewport;
+  // The same guard view.ts's `fitView` applies, for the same reason: the
+  // container is measured by a ResizeObserver and is 0x0 for the first frame.
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return { working: null, camera: null };
+  }
+  const full: PaneRect = { x: 0, y: 0, width, height };
+  if (layout.mode === "camera") return { working: null, camera: full };
+  if (layout.mode === "working") return { working: full, camera: null };
+  // 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);
+  return {
+    working: { x: 0, y: 0, width: split, height },
+    camera: { x: split, y: 0, width: width - split, height },
+  };
+}
+
+/**
+ * Which pane a canvas-space point is in, and where it lands inside it.
+ *
+ * THE DIVIDER COLUMN BELONGS TO THE CAMERA PANE. Both rects are half-open —
+ * `[x, x + width)` on each axis — so `x === split` is the camera pane's FIRST
+ * column and not the working pane's last. Half-open is what makes the two panes
+ * a partition: no point is in both, and no point between them is in neither.
+ * Which side wins matters less than the fact that it is stated; a `<=` on both
+ * sides would make the answer depend on the order the rects are tested in.
+ *
+ * Null for a point outside every pane, which is what the chrome's own gutters
+ * and the not-yet-laid-out first frame produce.
+ */
+export function paneAt(
+  rects: { working: PaneRect | null; camera: PaneRect | null },
+  x: number,
+  y: number,
+): { pane: StagePane; local: [number, number] } | null {
+  for (const pane of ["working", "camera"] as const) {
+    const rect = rects[pane];
+    if (rect === null) continue;
+    if (x < rect.x || x >= rect.x + rect.width) continue;
+    if (y < rect.y || y >= rect.y + rect.height) continue;
+    return { pane, local: [x - rect.x, y - rect.y] };
+  }
+  return null;
+}

package/src/stage/penState.ts

@@ -0,0 +1,112 @@
+// The pen's model, as a PURE REDUCER.
+//
+// The 2D lane's pen (canvas-editor/src/stage/penTool.ts) buries the identical
+// arithmetic inside a controller that owns DOM listeners, a preview element and
+// a store subscription, so the only way to ask it "what does a drag past the
+// threshold do to the incoming handle" is to drive a browser. Here the model is
+// a function of (state, event) and the controller in StageApp.tsx is the thin
+// part: every rule below is checkable in node, and the stage keeps no geometry
+// of its own to disagree with.
+//
+// EVERYTHING IS DESIGN PX. The two thresholds are authored in SCREEN px because
+// they are about the author's finger, not about the document, so the caller
+// divides them by the current zoom before handing them in. That keeps the
+// reducer free of view state without pretending an 8px slop means the same
+// thing at 25% and 400%.
+import type { PathData, PathPoint } from "@dailies-studio/shot/doc";
+
+/** How near the first anchor a press has to land to CLOSE the path. Screen px,
+ *  the same 8 the 2D lane uses — the two pens should feel identical. */
+export const PEN_CLOSE_SLOP_PX = 8;
+/** How far a press has to travel before it is pulling handles rather than
+ *  placing a corner. Screen px, matching the move/resize lanes, so a press
+ *  meant as a click cannot mint a curve the author did not ask for. */
+export const PEN_DRAG_THRESHOLD_PX = 3;
+
+type Vec2 = [number, number];
+
+export interface PenState {
+  points: PathPoint[];
+  /** True once a press lands back on the first anchor. The caller commits on
+   *  seeing it; the wrap segment is what `closed` means, so no anchor is added
+   *  for it (a duplicate point there prints a zero-length segment into `d`). */
+  closed: boolean;
+  /** The anchor a live press is pulling handles out of, or null. */
+  drag: { index: number; from: Vec2 } | null;
+  /** Where the cursor last was, for the rubber band. Null before the first
+   *  move, which is why the preview draws no band on the very first anchor. */
+  cursor: Vec2 | null;
+}
+
+export const PEN_EMPTY: PenState = { points: [], closed: false, drag: null, cursor: null };
+
+export type PenEvent =
+  | { kind: "press"; at: Vec2; closeSlop: number }
+  | { kind: "move"; at: Vec2; dragThreshold: number }
+  | { kind: "release" };
+
+/** Whether a press at `at` would close the path. Exported because the preview
+ *  highlights the first anchor on hover using the same answer, and two
+ *  implementations of "near enough" would highlight one thing and do another. */
+export function penCloses(state: PenState, at: Vec2, closeSlop: number): boolean {
+  const first = state.points[0];
+  if (first === undefined || state.points.length < 2) return false;
+  return Math.hypot(at[0] - first.p[0], at[1] - first.p[1]) <= closeSlop;
+}
+
+export function penReduce(state: PenState, ev: PenEvent): PenState {
+  switch (ev.kind) {
+    case "press": {
+      if (penCloses(state, ev.at, ev.closeSlop)) return { ...state, closed: true, drag: null, cursor: null };
+      // A DOUBLE-CLICK COMMIT LANDS ITS SECOND PRESS ON THE FIRST'S POINT, so
+      // an unconditional append would bake a zero-length segment and a
+      // redundant anchor into the committed model — and because the printer is
+      // fed that same model, `pathToD(points) === d` still holds and nothing
+      // downstream refuses it. It just ships a wrong shape. Caught HERE rather
+      // than in each commit path, so the preview, `penLayer` and anything
+      // later all inherit it; `layerFromDraw`'s own `dedupe` stays where it is,
+      // serving the bare-points `onDraw` lane it was written for.
+      const last = state.points[state.points.length - 1];
+      if (last !== undefined && last.p[0] === ev.at[0] && last.p[1] === ev.at[1]) {
+        // Re-point the drag at the anchor already there, so holding and
+        // dragging the second press still pulls that anchor's handles.
+        return { ...state, drag: { index: state.points.length - 1, from: ev.at }, cursor: ev.at };
+      }
+      // A fresh anchor is a CORNER until a drag proves otherwise: no handles,
+      // which is exactly what makes a click-only path a polyline.
+      const points = [...state.points, { p: [ev.at[0], ev.at[1]] as Vec2 }];
+      return { points, closed: false, drag: { index: points.length - 1, from: ev.at }, cursor: ev.at };
+    }
+    case "move": {
+      const drag = state.drag;
+      if (drag === null) return { ...state, cursor: ev.at };
+      if (
+        Math.abs(ev.at[0] - drag.from[0]) < ev.dragThreshold &&
+        Math.abs(ev.at[1] - drag.from[1]) < ev.dragThreshold
+      ) {
+        return { ...state, cursor: ev.at };
+      }
+      const anchor = state.points[drag.index];
+      if (anchor === undefined) return { ...state, cursor: ev.at };
+      // THE MIRROR IS THE POINT. `out` is where the author dragged and `in` is
+      // its reflection through the anchor, which is what makes the curve smooth
+      // THROUGH the anchor rather than kinked at it. Writing `out` alone would
+      // give every dragged anchor a corner on its incoming side.
+      const out: Vec2 = [ev.at[0], ev.at[1]];
+      const inHandle: Vec2 = [2 * anchor.p[0] - ev.at[0], 2 * anchor.p[1] - ev.at[1]];
+      const points = [...state.points];
+      points[drag.index] = { p: anchor.p, in: inHandle, out };
+      return { ...state, points, cursor: ev.at };
+    }
+    case "release":
+      return state.drag === null ? state : { ...state, drag: null };
+  }
+}
+
+/** The authored model a commit writes, or null when there is not enough path to
+ *  be one. Two points is the floor: one anchor prints a move-to and nothing
+ *  else, which is a layer with no geometry and no way to select it. */
+export function penData(state: PenState): PathData | null {
+  if (state.points.length < 2) return null;
+  return { points: state.points.map((p) => ({ ...p })), closed: state.closed };
+}

package/src/stage/project.ts

@@ -0,0 +1,402 @@
+// World -> screen, and ray -> layer. The stage's whole geometry surface, pure
+// enough to test against a hand-built camera.
+//
+// ── EVERY LAYER IS A QUAD, AND THAT IS EXPLOITED RATHER THAN ABSTRACTED ──
+//
+// A shot layer is a flat plane at a depth. So its outline on screen is FOUR
+// PROJECTED POINTS, and its pick test is a ray against two triangles. Both are
+// exact, both are a few lines, and neither needs the renderer.
+//
+// The selection overlay is therefore a POLYGON, never an axis-aligned rect. A
+// tilted layer's outline is a trapezoid; a bounding box would lie about the
+// tilt in every frame and would put the resize handles somewhere the layer is
+// not.
+//
+// ── WHY PICKING IS NOT `Raycaster.intersectObjects` ─────────────────────
+//
+// Two reasons, and the second is the one that matters.
+//
+//   1. The MESH is not the layer. A paint layer's plane is grown by the
+//      rasterizer's shadow padding (raster.ts), so intersecting the mesh picks
+//      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
+//      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";
+
+/** A layer's four world-space corners, in TL, TR, BR, BL order. */
+export type WorldQuad = readonly [Vector3, Vector3, Vector3, Vector3];
+
+/** The same four, projected, as x,y pairs in CSS px from the canvas top-left. */
+export type ScreenQuad = readonly [number, number, number, number, number, number, number, number];
+
+/** What picking and projection need to know about one layer. `matrixWorld` is
+ *  the layer GROUP's — which carries position, tilt and roll but NOT the box
+ *  scale, so the box is passed separately and the padded mesh cannot leak in. */
+export interface LayerFrame {
+  id: string;
+  /** Design px. */
+  size: readonly [number, number];
+  matrixWorld: Matrix4;
+  /** 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. */
+  locked?: boolean;
+  /**
+   * False for the kinds that paint NOTHING of their own.
+   *
+   * A GROUP and a CLONER — a device draws its own slab now, and the comment
+   * here said otherwise for long enough to be worth correcting.
+   *
+   * Clicking inside a group but outside every child must not select the group:
+   * what makes a group selectable is a hit on a CHILD, which is a chrome policy
+   * over the hit list rather than a question the stage can answer. A group is
+   * still projected, because a selection made from the layers panel needs an
+   * outline.
+   */
+  pickable?: boolean;
+}
+
+const CORNERS: ReadonlyArray<readonly [number, number]> = [
+  [-0.5, 0.5], // TL — design +y is DOWN, three +y is UP, so the TOP corner is +y here
+  [0.5, 0.5], // TR
+  [0.5, -0.5], // BR
+  [-0.5, -0.5], // BL
+];
+
+/** The layer's four world corners. Allocates; call it per selected layer per
+ *  frame, not per layer per frame. */
+export function worldQuad(frame: LayerFrame): WorldQuad {
+  const [w, h] = frame.size;
+  return CORNERS.map(([u, v]) =>
+    new Vector3(u * w, v * h, 0).applyMatrix4(frame.matrixWorld),
+  ) as unknown as WorldQuad;
+}
+
+/**
+ * How far out of one plane, and off one axis, a multi-select may be and still
+ * get a union box. In DESIGN px, because world units are design units.
+ *
+ * Half a pixel: below that the two answers round to the same drawn box anyway,
+ * and above it the box would start claiming an alignment the layers do not have.
+ */
+const UNION_EPSILON = 0.5;
+
+/**
+ * The one box around a multi-select, or null when there honestly isn't one.
+ *
+ * ── WHY IT IS ALLOWED TO BE AN AABB HERE, WHEN THE HEADER FORBIDS IT ────
+ *
+ * The header's rule is that a layer's OUTLINE is a polygon, because a bounding
+ * box would lie about that layer's tilt. This is a different object: the union
+ * of several layers, which has no tilt of its own to lie about. It gets to be a
+ * rectangle exactly when the layers make one honest, and the predicate below is
+ * what "honest" means:
+ *
+ *   COPLANAR — every corner of every member shares one world z. A member tilted
+ *   out of the design plane fails here, and it must: its four corners span a
+ *   range of depths, so no single rectangle contains them without inventing a
+ *   depth for the box.
+ *
+ *   AXIS-PARALLEL — every member's own edges run along world x and y. A member
+ *   rolled 30 degrees fails, and it must for a subtler reason: the box would
+ *   still be drawable, but the SCALE it offers could not be honoured. One
+ *   `GestureDelta` carries one `axis`, and `localizeGesture` applies it in
+ *   DESIGN x/y — so a one-axis drag on a box whose axes are rotated away from
+ *   design would grow the wrong dimension of every rolled member. A member
+ *   rolled a multiple of 180 still passes, which is right: its edges are still
+ *   the design axes, and `size` has no sign for the flip to disturb.
+ *
+ * A selection that fails keeps its per-layer outlines and is told, once, that
+ * the union scale is not available — see `Overlays`. Drawing a box that lies is
+ * the one option not on the table.
+ */
+export function unionQuad(frames: readonly LayerFrame[]): WorldQuad | null {
+  // ONE LAYER IS NOT A UNION. It keeps its own quad, its own handles and its
+  // own `resize`, which changes that layer's `size` and is a different and
+  // better operation than a ratio about a pivot.
+  if (frames.length < 2) return null;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let z = 0;
+  let first = true;
+  for (const frame of frames) {
+    const quad = worldQuad(frame);
+    if (first) z = quad[0].z;
+    for (const p of quad) {
+      if (Math.abs(p.z - z) > UNION_EPSILON) return null;
+      minX = Math.min(minX, p.x);
+      maxX = Math.max(maxX, p.x);
+      minY = Math.min(minY, p.y);
+      maxY = Math.max(maxY, p.y);
+    }
+    // TL->TR must run along world x and TL->BL along world y. Testing the two
+    // edges rather than the matrix's axes keeps this reading the exact points
+    // that get drawn, so the box and the outline cannot disagree about tilt.
+    if (Math.abs(quad[1].y - quad[0].y) > UNION_EPSILON) return null;
+    if (Math.abs(quad[3].x - quad[0].x) > UNION_EPSILON) return null;
+    first = false;
+  }
+  if (!Number.isFinite(minX) || !Number.isFinite(minY)) return null;
+  // TL, TR, BR, BL — `worldQuad`'s order, because everything downstream
+  // (`HANDLE_SITES`, `handlePoint`, `rotateRingAt`) indexes corners by it.
+  // World +y is UP, so the TOP corners take `maxY`.
+  return [
+    new Vector3(minX, maxY, z),
+    new Vector3(maxX, maxY, z),
+    new Vector3(maxX, minY, z),
+    new Vector3(minX, minY, z),
+  ];
+}
+
+/** A camera far enough for `project` — the slice of three's Camera this needs. */
+export interface Projector {
+  projectionMatrix: Matrix4;
+  matrixWorldInverse: Matrix4;
+}
+
+/**
+ * World -> CSS px from the canvas top-left.
+ *
+ * It goes through `projectionMatrix * matrixWorldInverse`, which is exactly
+ * what `Vector3.project` does — and, critically, that matrix ALREADY carries
+ * `setViewOffset`. So the working-area pan and zoom need no separate term here
+ * and cannot drift out of step with what the renderer drew.
+ */
+export function toScreen(
+  point: Vector3,
+  camera: Projector,
+  width: number,
+  height: number,
+): [number, number] {
+  const v = new Vector3().copy(point).applyMatrix4(camera.matrixWorldInverse).applyMatrix4(
+    camera.projectionMatrix,
+  );
+  // Perspective divide is inside applyMatrix4 for a Vector3 (three divides by
+  // w), so `v` is already NDC.
+  return [((v.x + 1) / 2) * width, ((1 - v.y) / 2) * height];
+}
+
+export function screenQuad(
+  frame: LayerFrame,
+  camera: Projector,
+  width: number,
+  height: number,
+): ScreenQuad {
+  return projectQuad(worldQuad(frame), camera, width, height);
+}
+
+/** The same projection for a quad that is not a layer's — the union box. */
+export function projectQuad(
+  quad: WorldQuad,
+  camera: Projector,
+  width: number,
+  height: number,
+): ScreenQuad {
+  const pts: number[] = [];
+  for (const corner of quad) {
+    const [x, y] = toScreen(corner, camera, width, height);
+    pts.push(x, y);
+  }
+  return pts as unknown as ScreenQuad;
+}
+
+/** Did any corner move enough to be worth repainting the overlay? Half a CSS
+ *  pixel: below that the SVG rounds to the same path and the repaint is pure
+ *  cost, and the overlay is recomputed on EVERY frame the camera moves. */
+export function quadMoved(a: ScreenQuad | undefined, b: ScreenQuad, epsilon = 0.5): boolean {
+  if (a === undefined) return true;
+  for (let i = 0; i < 8; i++) if (Math.abs(a[i]! - b[i]!) > epsilon) return true;
+  return false;
+}
+
+/**
+ * Ray against a layer's quad. Returns the ray distance, or null for a miss.
+ *
+ * Two triangles rather than a plane intersection plus a 2D containment test:
+ * Möller–Trumbore gives the answer and the bounds together, it needs no
+ * degenerate-plane special case, and it is the same arithmetic for both halves.
+ */
+export function rayHitsQuad(ray: Ray, quad: WorldQuad): number | null {
+  return (
+    rayHitsTriangle(ray, quad[0], quad[1], quad[2]) ?? rayHitsTriangle(ray, quad[0], quad[2], quad[3])
+  );
+}
+
+const EPSILON = 1e-8;
+
+function rayHitsTriangle(ray: Ray, a: Vector3, b: Vector3, c: Vector3): number | null {
+  const edge1 = new Vector3().subVectors(b, a);
+  const edge2 = new Vector3().subVectors(c, a);
+  const pvec = new Vector3().crossVectors(ray.direction, edge2);
+  const det = edge1.dot(pvec);
+  // Two-sided on purpose: a layer flipped or tilted past 90 degrees is still
+  // the same layer, and refusing to select it from behind would be a bug the
+  // author could not diagnose.
+  if (Math.abs(det) < EPSILON) return null;
+  const invDet = 1 / det;
+  const tvec = new Vector3().subVectors(ray.origin, a);
+  const u = tvec.dot(pvec) * invDet;
+  if (u < 0 || u > 1) return null;
+  const qvec = new Vector3().crossVectors(tvec, edge1);
+  const v = ray.direction.dot(qvec) * invDet;
+  if (v < 0 || u + v > 1) return null;
+  const t = edge2.dot(qvec) * invDet;
+  return t >= 0 ? t : null;
+}
+
+/**
+ * Every layer under the pointer, FRONT-MOST FIRST.
+ *
+ * Front-most means highest `order`, not nearest — see the header. The whole
+ * ordered list is returned rather than the winner, because the chrome owns
+ * what a modified click means (plain takes the front, meta walks behind), and
+ * a stage that decided it would be a second place selection policy lives.
+ */
+export function pickLayers(ray: Ray, frames: readonly LayerFrame[]): string[] {
+  const hits: Array<{ id: string; order: number }> = [];
+  for (const frame of frames) {
+    if (frame.locked === true) continue;
+    if (rayHitsQuad(ray, worldQuad(frame)) !== null) hits.push({ id: frame.id, order: frame.order });
+  }
+  hits.sort((a, b) => b.order - a.order);
+  return hits.map((h) => h.id);
+}
+
+/**
+ * Every layer under the pointer, NEAREST FIRST.
+ *
+ * THE WORKING PANE'S PICKER, and the divergence from `pickLayers` is the point.
+ * In the camera pane, what covers what is DOCUMENT order: every layer draws
+ * with `depthTest: false` and `renderOrder = order`, so the thing on top is the
+ * thing with the highest order however far away it sits, and picking by
+ * distance there would routinely return a layer the author cannot see (the
+ * header's reason 2).
+ *
+ * In a free orbit view none of that holds. The author is looking at real 3D
+ * POSITIONS from an angle the document never specifies, so paint order is
+ * meaningless as a "what did I click" answer: the plane whose surface the ray
+ * reaches first is the one under the cursor. Same hit test, one different sort.
+ *
+ * Ties break on paint order, which is not a nicety: layers default to z = 0, so
+ * a stack of coplanar layers is the common case and `t` is equal for all of
+ * them. Falling back to the camera pane's rule there keeps the two panes
+ * agreeing whenever depth has nothing to say.
+ */
+export function pickLayersByDistance(ray: Ray, frames: readonly LayerFrame[]): string[] {
+  const hits: Array<{ id: string; t: number; order: number }> = [];
+  for (const frame of frames) {
+    if (frame.locked === true) continue;
+    const t = rayHitsQuad(ray, worldQuad(frame));
+    if (t !== null) hits.push({ id: frame.id, t, order: frame.order });
+  }
+  hits.sort((a, b) => a.t - b.t || b.order - a.order);
+  return hits.map((h) => h.id);
+}
+
+/**
+ * Layers whose quad intersects a screen-space rectangle — the marquee.
+ *
+ * ── CORNERS BOTH WAYS, NOT JUST THE LAYER'S ─────────────────────────────
+ *
+ * It tested only the LAYER's corners against the rect, which quietly failed
+ * the two commonest marquees there are:
+ *
+ *   A box drawn INSIDE a big layer — a full-bleed background, a card larger
+ *   than the band — selected nothing at all, because none of that layer's
+ *   corners were in the box.
+ *
+ *   A box crossing a card edge to edge, taller than it and narrower, likewise:
+ *   the card's corners are outside on both sides.
+ *
+ * Testing the RECT's four corners against the quad as well covers both, and
+ * costs a point-in-convex-polygon test the file already has the geometry for.
+ * Edge-crossing with no corner inside either shape (a thin cross) is still
+ * missed; that is a rare enough marquee to leave, and named rather than
+ * pretended away.
+ */
+export function pickInRect(
+  frames: readonly LayerFrame[],
+  camera: Projector,
+  width: number,
+  height: number,
+  rect: { x0: number; y0: number; x1: number; y1: number },
+): string[] {
+  const minX = Math.min(rect.x0, rect.x1);
+  const maxX = Math.max(rect.x0, rect.x1);
+  const minY = Math.min(rect.y0, rect.y1);
+  const maxY = Math.max(rect.y0, rect.y1);
+  const corners: ReadonlyArray<readonly [number, number]> = [
+    [minX, minY],
+    [maxX, minY],
+    [maxX, maxY],
+    [minX, maxY],
+  ];
+  const hit: Array<{ id: string; order: number }> = [];
+  for (const frame of frames) {
+    if (frame.locked === true) continue;
+    // ── BEHIND THE CAMERA PROJECTS TO GARBAGE, PER CORNER ────────────────
+    //
+    // `toScreen` divides by w, which is negative behind the eye, so the NDC
+    // mirrors through the origin and lands somewhere entirely plausible — a
+    // layer behind the author would be marquee-selected from a box drawn in
+    // front of them. `rayHitsQuad` rejects `t < 0`, and both gizmos carry their
+    // own guard; the marquee was the one projection consumer without one.
+    //
+    // WHOLE-LAYER VETO WAS TOO BLUNT. A layer STRADDLING the eye plane — a
+    // full-bleed background under a wide orbit, or anything the author has
+    // dollied into — has some corners in front and some behind, and refusing
+    // the layer outright made it un-marqueeable, which it was not before the
+    // guard existed. So the guard is per corner: only the lying ones are
+    // dropped, and a layer whose four corners all lie is skipped entirely.
+    const world = worldQuad(frame);
+    const ahead = world.map((p) => new Vector3().copy(p).applyMatrix4(camera.matrixWorldInverse).z < 0);
+    if (!ahead.some(Boolean)) continue;
+    const q = projectQuad(world, camera, width, height);
+    let inside = false;
+    for (let i = 0; i < 8 && !inside; i += 2) {
+      // A corner behind the eye has no honest screen position, so it cannot be
+      // the corner that puts this layer in the box.
+      if (ahead[i / 2] !== true) continue;
+      inside = q[i]! >= minX && q[i]! <= maxX && q[i + 1]! >= minY && q[i + 1]! <= maxY;
+    }
+    // The RECT's corners against the quad — the test that catches a box drawn
+    // inside a big layer. Only meaningful when the whole quad projected
+    // honestly: `pointInQuad`'s edge signs are nonsense once one vertex has
+    // mirrored through the origin.
+    if (!inside && ahead.every(Boolean)) {
+      for (const c of corners) {
+        if (inside) break;
+        inside = pointInQuad(c[0], c[1], q);
+      }
+    }
+    if (inside) hit.push({ id: frame.id, order: frame.order });
+  }
+  hit.sort((a, b) => a.order - b.order);
+  return hit.map((h) => h.id);
+}
+
+/** Point in a CONVEX quad, by the sign of the cross product against each edge.
+ *  A projected layer quad is always convex — a projective map takes a convex
+ *  quad to a convex quad — so the sign test is exact rather than a heuristic. */
+function pointInQuad(x: number, y: number, q: ScreenQuad): boolean {
+  let positive = false;
+  let negative = false;
+  for (let i = 0; i < 4; i++) {
+    const ax = q[i * 2]!;
+    const ay = q[i * 2 + 1]!;
+    const bx = q[((i + 1) % 4) * 2]!;
+    const by = q[((i + 1) % 4) * 2 + 1]!;
+    const cross = (bx - ax) * (y - ay) - (by - ay) * (x - ax);
+    if (cross > 0) positive = true;
+    if (cross < 0) negative = true;
+    if (positive && negative) return false;
+  }
+  return true;
+}