@dailies-studio/shot-editor 0.1.0

package/src/stage/handles.ts

@@ -0,0 +1,151 @@
+// The selection box's eight resize handles, as pure screen geometry.
+//
+// ── WHY THIS IS ITS OWN MODULE ──────────────────────────────────────────
+//
+// THREE READERS, and they must never disagree. `Overlays` DRAWS the handles,
+// `StageTools.grabAt` HIT-TESTS them, and the cursor lane asks which way one
+// points. A drawn handle the hit test does not answer, or an answered one
+// nobody drew, is precisely the bug a hover cursor exists to make impossible —
+// and the two used to be separate tables in separate files, one of which only
+// knew about four of the eight.
+//
+// It is also the only shape here that can be checked in node: `StageTools`
+// pulls in three's WebGPU node materials through its neighbours, so a test that
+// wanted to ask "what does a press at this point grab" had to mount a canvas.
+//
+// ── AND WHY THE QUAD IS A TRAPEZOID, NOT A RECTANGLE ────────────────────
+//
+// `screenQuad` projects a layer's four corners through whichever camera the
+// pane is using. Under the camera pane's perspective lens a tilted layer is
+// already a trapezoid; under the working pane's free orbit it can be any convex
+// quad at all. So nothing here may assume axis alignment, and in particular a
+// handle's NAME says nothing about which way it points on screen.
+import { RESIZE_HANDLES } from "@dailies-studio/shot/doc";
+import type { ResizeHandle } from "@dailies-studio/shot/doc";
+import type { ScreenQuad } from "./project.js";
+
+/** How close a press has to land to a handle, in CSS px. Larger than the drawn
+ *  7px handle, because a 7px target is a 7px target and everyone misses it. */
+export const HANDLE_GRAB_PX = 10;
+
+/**
+ * The eight handle sites, in HIT-TEST ORDER: four corners, then four edge
+ * midpoints.
+ *
+ * Corners first is load-bearing rather than cosmetic. The grab radius is larger
+ * than the drawn handle, so a corner's target overlaps both of its neighbouring
+ * edge targets; testing edges first would answer a corner press with an edge,
+ * and the author would resize one axis when they asked for two.
+ *
+ * `a` and `b` are quad corner indices (TL, TR, BR, BL) and the site is their
+ * MIDPOINT — which is the corner itself when they are equal. The midpoint of
+ * two projected corners is exactly the projection of the edge's midpoint,
+ * because a projective map takes lines to lines, so an edge handle sits on the
+ * drawn edge at every angle with no extra maths.
+ *
+ * The handle's two signs ARE the resize arithmetic (packages/shot's
+ * `resizeTransform`). `RESIZE_HANDLES` has carried all eight since the document
+ * model was written; four of them were unreachable from the pointer until this
+ * table existed.
+ */
+export const HANDLE_SITES: ReadonlyArray<{ a: number; b: number; handle: ResizeHandle }> = [
+  { a: 0, b: 0, handle: RESIZE_HANDLES["nw"]! },
+  { a: 1, b: 1, handle: RESIZE_HANDLES["ne"]! },
+  { a: 2, b: 2, handle: RESIZE_HANDLES["se"]! },
+  { a: 3, b: 3, handle: RESIZE_HANDLES["sw"]! },
+  { a: 0, b: 1, handle: RESIZE_HANDLES["n"]! },
+  { a: 1, b: 2, handle: RESIZE_HANDLES["e"]! },
+  { a: 2, b: 3, handle: RESIZE_HANDLES["s"]! },
+  { a: 3, b: 0, handle: RESIZE_HANDLES["w"]! },
+];
+
+/** Where a site sits on screen. */
+export function handlePoint(quad: ScreenQuad, site: { a: number; b: number }): [number, number] {
+  return [
+    (quad[site.a * 2]! + quad[site.b * 2]!) / 2,
+    (quad[site.a * 2 + 1]! + quad[site.b * 2 + 1]!) / 2,
+  ];
+}
+
+/**
+ * The mean of the four projected corners.
+ *
+ * NOT the diagonals' intersection: under a perspective camera the quad is a
+ * trapezoid whose diagonals do not bisect each other, and the two answers
+ * disagree by enough at a steep angle to flip a cursor across a 45 degree
+ * bucket boundary.
+ */
+export function quadCentre(quad: ScreenQuad): [number, number] {
+  let cx = 0;
+  let cy = 0;
+  for (let i = 0; i < 4; i++) {
+    cx += quad[i * 2]!;
+    cy += quad[i * 2 + 1]!;
+  }
+  return [cx / 4, cy / 4];
+}
+
+/**
+ * Which of the eight handles a press grabbed, with the direction it points.
+ *
+ * `angle` is the OUTWARD screen direction from the quad's centre, in radians in
+ * the overlay's y-DOWN space. It is here rather than at the cursor's end
+ * because this is where the quad is, and deriving it twice is how the drawn
+ * handle and the cursor end up a rotation apart.
+ */
+export function nearestHandle(
+  quad: ScreenQuad | undefined,
+  x: number,
+  y: number,
+): { handle: ResizeHandle; angle: number } | null {
+  if (quad === undefined) return null;
+  for (const site of HANDLE_SITES) {
+    const [hx, hy] = handlePoint(quad, site);
+    if (Math.hypot(hx - x, hy - y) > HANDLE_GRAB_PX) continue;
+    const [cx, cy] = quadCentre(quad);
+    return { handle: site.handle, angle: Math.atan2(hy - cy, hx - cx) };
+  }
+  return null;
+}
+
+/**
+ * The rotate ring: a band JUST OUTSIDE each corner.
+ *
+ * ── WHY OUTSIDE, AND WHY ONLY AT THE CORNERS ────────────────────────────
+ *
+ * Figma and Framer both put rotation in the empty space beyond a corner, and
+ * that placement is not arbitrary: it is the one region around a selection box
+ * that no other gesture claims. Inside is a body move, on the corner is a
+ * resize, along an edge is a one-axis resize, and further out is empty space.
+ *
+ * Corners only, not the whole perimeter, for the same reason: the band beside
+ * an EDGE is a few px from that edge's own resize handle, so a ring there would
+ * make one-axis resizes hard to hit for a gesture that has somewhere else to
+ * live.
+ *
+ * It starts where the resize slop ends, so the two never both answer, and the
+ * annulus is wide enough to hit without being a trap the pointer falls into on
+ * the way out of the box.
+ */
+export const RING_INNER_PX = HANDLE_GRAB_PX;
+export const RING_OUTER_PX = 26;
+
+/** Is this press in the rotate ring, and which way does that corner point? */
+export function rotateRingAt(
+  quad: ScreenQuad | undefined,
+  x: number,
+  y: number,
+): { angle: number } | null {
+  if (quad === undefined) return null;
+  const [cx, cy] = quadCentre(quad);
+  for (let i = 0; i < 4; i++) {
+    const d = Math.hypot(quad[i * 2]! - x, quad[i * 2 + 1]! - y);
+    if (d <= RING_INNER_PX || d > RING_OUTER_PX) continue;
+    // OUTSIDE THE BOX ONLY. The annulus around a corner reaches inwards too,
+    // and that half belongs to the body move — a press an author aimed at the
+    // layer must not rotate it.
+    if (Math.hypot(x - cx, y - cy) < Math.hypot(quad[i * 2]! - cx, quad[i * 2 + 1]! - cy)) continue;
+    return { angle: Math.atan2(y - cy, x - cx) };
+  }
+  return null;
+}

package/src/stage/instanceModules.ts

@@ -0,0 +1,152 @@
+// Resolving a shot's INSTANCE targets to real modules, on the stage.
+//
+// WHY IT BELONGS HERE AND NOWHERE ELSE. The shot stage is served through the
+// PROJECT's Vite (`/shot-stage.html` + `/@fs`, shotRoutes.ts) precisely so the
+// three stack resolves to the studio's pinned copies and the project's own
+// modules are reachable. The chrome cannot do it (it is a prebuilt static
+// bundle with no view of the project graph) and @dailies-studio/shot must not
+// (codegen supplies static imports there). This is a faithful sibling of the
+// canvas lane's `embedModules.ts`, and it is deliberately a sibling rather than
+// a shared module: the two chromes depend on neither each other nor a third
+// package, and the whole file is forty lines of dynamic import.
+//
+// TWO LOADS PER COMPONENT, mirroring codegen exactly (shot codegen emit.ts):
+//   the COMPONENT   through `virtual:studio-components`, whose `load()` already
+//                   resolves the named export and handles BUILTINS (bare
+//                   package specifiers, not project paths) — hand-rolling a URL
+//                   here would get exactly that case wrong.
+//   the CONTRACT    a DECLARED contract is a module, imported from the same
+//                   specifier codegen writes. A SNAPSHOT comes off the document
+//                   (`snapshotInstanceContracts`, folded in by `ShotRuntime`)
+//                   and needs no network at all.
+//
+// FAILURE IS NEVER FATAL. Every load is caught: a component that will not
+// resolve is simply absent from the map and its layer draws nothing, with the
+// reason travelling up the stage's existing error channel. A stage that threw
+// here would blank the whole editor over one broken import.
+import {
+  controlsModuleOf,
+  instanceComponentIdsOf,
+  instanceContractBindings,
+  instanceModuleOf,
+  isBareModuleSpecifier,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import type { Contract } from "@dailies-studio/contract";
+import type { ComponentType } from "react";
+
+/** The `virtual:studio-components` row shape (cli registry.ts). */
+interface RegistryEntry {
+  id: string;
+  host: string;
+  load(): Promise<unknown>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type InstanceModules = Record<string, ComponentType<any>>;
+
+export interface InstanceResolution {
+  instances: InstanceModules;
+  contracts: Record<string, Contract>;
+  /** One line per component that could not be resolved. Empty when everything
+   *  loaded (or the document has no instances). */
+  errors: string[];
+}
+
+const EMPTY: InstanceResolution = { instances: {}, contracts: {}, errors: [] };
+
+/** Module-level caches: the stage re-resolves on every document identity change
+ *  (an inspector keystroke), and a dynamic import is idempotent but a REJECTED
+ *  one is not cheap to retry in a loop. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const componentCache = new Map<string, Promise<ComponentType<any> | null>>();
+const contractCache = new Map<string, Promise<Contract | null>>();
+
+/** The registry's URL, not its module ID. `virtual:studio-components` is
+ *  resolvable only by the studio server's own Vite plugin, so a bare specifier
+ *  would be a hard build error in every OTHER Vite that sees this file. Held in
+ *  a const so Vite's import analysis cannot see a literal and try. */
+const COMPONENT_REGISTRY_URL = "/@id/virtual:studio-components";
+
+async function registry(): Promise<Record<string, RegistryEntry>> {
+  const mod = (await import(/* @vite-ignore */ COMPONENT_REGISTRY_URL)) as {
+    components?: Record<string, RegistryEntry>;
+  };
+  return mod.components ?? {};
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function loadComponent(id: string): Promise<ComponentType<any> | null> {
+  const hit = componentCache.get(id);
+  if (hit !== undefined) return hit;
+  const p = (async () => {
+    const entry = (await registry())[id];
+    if (entry === undefined) return null;
+    const value = await entry.load();
+    // A vanished export resolves to undefined; treat it as "not resolvable"
+    // rather than rendering `undefined` into the tree.
+    return typeof value === "function" || (typeof value === "object" && value !== null)
+      ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (value as ComponentType<any>)
+      : null;
+  })().catch(() => null);
+  componentCache.set(id, p);
+  return p;
+}
+
+function loadDeclaredContract(specifier: string): Promise<Contract | null> {
+  const hit = contractCache.get(specifier);
+  if (hit !== undefined) return hit;
+  const url = isBareModuleSpecifier(specifier) ? specifier : `/${specifier}`;
+  const p = (async () => {
+    const mod = (await import(/* @vite-ignore */ url)) as { controls?: unknown };
+    const controls = mod.controls;
+    return controls !== null && typeof controls === "object" && "keys" in controls
+      ? (controls as Contract)
+      : null;
+  })().catch(() => null);
+  contractCache.set(specifier, p);
+  return p;
+}
+
+/** Resolve every instance target in `doc`. Pure I/O — no React, no state — so
+ *  the caller owns when it runs and what it does with a partial answer. */
+export async function resolveInstanceModules(doc: Doc3D): Promise<InstanceResolution> {
+  const ids = instanceComponentIdsOf(doc);
+  if (ids.length === 0) return EMPTY;
+
+  const instances: InstanceModules = {};
+  const errors: string[] = [];
+  await Promise.all(
+    ids.map(async (id) => {
+      const comp = await loadComponent(id);
+      if (comp === null) {
+        errors.push(`instance "${id}" could not be loaded from the project — its layer is empty.`);
+        return;
+      }
+      instances[id] = comp;
+    }),
+  );
+
+  // Only the DECLARED ones. `ShotRuntime` folds the document's own snapshots in
+  // underneath, so there is nothing to merge here and no chance of this half
+  // shadowing a snapshot with an undefined.
+  const contracts: Record<string, Contract> = {};
+  await Promise.all(
+    instanceContractBindings(doc).map(async ({ component, ref }) => {
+      if (ref.source === "snapshot") return;
+      const specifier = controlsModuleOf(instanceModuleOf(component), ref.source);
+      const contract = await loadDeclaredContract(specifier);
+      if (contract === null) {
+        errors.push(
+          `instance "${component}" declares its contract in ${JSON.stringify(specifier)}, which ` +
+            `did not load — its props render unmapped here.`,
+        );
+        return;
+      }
+      contracts[component] = contract;
+    }),
+  );
+
+  return { instances, contracts, errors };
+}

package/src/stage/interactions/move.ts

@@ -0,0 +1,172 @@
+// Turning a pointer into a DESIGN-SPACE delta, which is the one thing the
+// chrome's document math cannot do for itself.
+//
+// ── THE V-vs-G RULE, WHICH IS THE WHOLE FILE ────────────────────────────
+//
+// The 2D lane could say "screen delta ÷ zoom" because everything was coplanar.
+// Here each layer sits at its OWN depth under a perspective camera, so a screen
+// delta maps to a different world delta per layer — and there is no single
+// correct answer, because two different gestures are being asked for:
+//
+//   SELECT (V) unprojects onto the LAYER'S OWN tilted plane. Dragging a tilted
+//     layer slides it along its own surface, which is what "move this thing"
+//     means once the thing is a plane in space.
+//
+//   MOVE (G) unprojects onto the plane through the layer's origin PARALLEL to
+//     the export frame. Flat screen space: z never changes and tilt is ignored,
+//     which is what "move it on the canvas" means.
+//
+// Two `Ray.intersectPlane` calls. One plane constructor different. That is the
+// entire distinction, and stating it as two planes rather than as two code
+// paths is what keeps it from drifting.
+import { Plane, Vector3 } from "three";
+import type { Ray } from "three";
+
+export type MovePlane = "layer" | "frame";
+
+/**
+ * The plane a gesture unprojects onto.
+ *
+ * `matrixWorld` is the layer group's, so its third basis column is the layer's
+ * own normal — no separate rotation bookkeeping, and a layer flipped or tilted
+ * past 90 degrees still gets its own plane rather than a mirrored one.
+ */
+export function gesturePlane(kind: MovePlane, matrixWorld: { elements: ArrayLike<number> }): Plane {
+  const e = matrixWorld.elements;
+  const origin = new Vector3(e[12]!, e[13]!, e[14]!);
+  if (kind === "frame") {
+    // Parallel to the export frame, through the layer's own depth: the design
+    // z = 0 plane's normal is world +z, and moving the plane to the layer keeps
+    // the drag anchored to the thing being dragged rather than to the canvas.
+    return new Plane().setFromNormalAndCoplanarPoint(new Vector3(0, 0, 1), origin);
+  }
+  const normal = new Vector3(e[8]!, e[9]!, e[10]!).normalize();
+  return new Plane().setFromNormalAndCoplanarPoint(normal, origin);
+}
+
+/** Where a ray meets a plane, or null when it is parallel to it (an edge-on
+ *  layer) — which is a real case and must not become a NaN delta. */
+export function unproject(ray: Ray, plane: Plane): Vector3 | null {
+  const hit = ray.intersectPlane(plane, new Vector3());
+  return hit === null || !Number.isFinite(hit.x) ? null : hit;
+}
+
+/**
+ * The world-space displacement between two rays on one plane, expressed in the
+ * DESIGN coordinates the schema uses.
+ *
+ * The one mapping is undone here and nowhere else: design +y is DOWN and +z is
+ * AWAY, so world (x, y, z) reads back as design (x, -y, -z).
+ */
+export function designDelta(
+  from: Ray,
+  to: Ray,
+  plane: Plane,
+): { dx: number; dy: number; dz: number } | null {
+  const a = unproject(from, plane);
+  const b = unproject(to, plane);
+  if (a === null || b === null) return null;
+  return { dx: b.x - a.x, dy: -(b.y - a.y), dz: -(b.z - a.z) };
+}
+
+/** A point on the gesture's plane, in DESIGN coordinates. The same one mapping
+ *  `designDelta` undoes, for the absolute point rather than the difference —
+ *  the union scale needs both, because a ratio is a quotient of distances and
+ *  not a displacement. */
+export function designPoint(ray: Ray, plane: Plane): [number, number, number] | null {
+  const p = unproject(ray, plane);
+  return p === null ? null : [p.x, -p.y, -p.z];
+}
+
+/**
+ * A multi-select's box, in DESIGN px. `x0,y0` is the top-left corner.
+ *
+ * It is a rectangle rather than a quad because `unionQuad` only hands one back
+ * for a selection that makes a rectangle honest — coplanar and axis-parallel.
+ */
+export interface DesignBox {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+/** Below this the anchor is ON the pivot and every ratio is a division by
+ *  nothing. In design px, so it is the same threshold at every zoom. */
+const MIN_SCALE_ARM = 1;
+
+/**
+ * The smallest ratio a drag may report, matching `MIN_INVERTIBLE_SCALE`.
+ *
+ * Dragging PAST the pivot asks for a negative factor, which `applyGesture`
+ * refuses by name — correctly, since `size` has no sign. Clamping here rather
+ * than letting the refusal fire means the box stops at the pivot instead of
+ * filling the error line on every pointermove of an overshoot, and nothing is
+ * lost on the way back out: every emit is a total from the press, so the clamp
+ * is re-evaluated from the base and never compounds.
+ */
+const MIN_RATIO = 1e-3;
+
+/**
+ * A drag on the union box's handle, as the ratio-about-a-pivot the document
+ * model actually has.
+ *
+ * ── WHY A RATIO AND NOT EIGHT EDGE DISTANCES ────────────────────────────
+ *
+ * A `resize` moves ONE layer's edge to the pointer, which is exact for one
+ * layer and meaningless for eight: each member sits a different distance from
+ * the box's edge, so "the edge travelled 40px" is a different size change for
+ * every one of them. What a group resize means is that the whole arrangement
+ * grows about a fixed point — one factor, applied to every member's size AND to
+ * its offset from that point. That is `GestureDelta`'s `scale`.
+ *
+ * ── THE ANCHOR IS THE PRESS, NOT THE HANDLE ─────────────────────────────
+ *
+ * The grab radius is 10px, so a press is near the handle and not on it.
+ * Measuring from the handle's own corner would make the box jump by up to that
+ * distance on the first pointermove; measuring from where the author actually
+ * pressed starts every drag at a ratio of exactly 1.
+ *
+ * Returns null when the anchor sits on the pivot along the axis being scaled —
+ * a division by nothing, which is a real case for a press dead-centre on an
+ * edge handle with ALT held, and NaN is the alternative.
+ */
+export function unionScale(
+  box: DesignBox,
+  handle: { sx: number; sy: number },
+  anchor: readonly [number, number],
+  travel: { dx: number; dy: number },
+  aboutCentre: boolean,
+): { ratio: number; axis: "x" | "y" | "both"; pivot: [number, number] } | null {
+  const midX = (box.x0 + box.x1) / 2;
+  const midY = (box.y0 + box.y1) / 2;
+  // The corner OPPOSITE the one grabbed, which is what stays put. An edge
+  // handle has one sign of zero, and negating zero gives the box's own middle
+  // on that axis — exactly the "opposite edge" pivot, with no second rule.
+  const pivot: [number, number] = aboutCentre
+    ? [midX, midY]
+    : [
+        handle.sx === 0 ? midX : handle.sx < 0 ? box.x1 : box.x0,
+        handle.sy === 0 ? midY : handle.sy < 0 ? box.y1 : box.y0,
+      ];
+  const ax = anchor[0] - pivot[0];
+  const ay = anchor[1] - pivot[1];
+  const bx = ax + travel.dx;
+  const by = ay + travel.dy;
+  // A corner scales UNIFORMLY, by the ratio of the two distances from the
+  // pivot. One `ratio` cannot express the independent x and y a single-layer
+  // corner resize gives, and a uniform group scale is both the honest reading
+  // of one number and what Blender's `S` does.
+  if (handle.sx !== 0 && handle.sy !== 0) {
+    const a = Math.hypot(ax, ay);
+    if (a < MIN_SCALE_ARM) return null;
+    return { ratio: Math.max(Math.hypot(bx, by) / a, MIN_RATIO), axis: "both", pivot };
+  }
+  // An edge handle names ONE of the box's axes, and the box's axes are the
+  // design axes — `unionQuad` refuses any selection where they are not.
+  const axis = handle.sx !== 0 ? "x" : "y";
+  const a = axis === "x" ? ax : ay;
+  const b = axis === "x" ? bx : by;
+  if (Math.abs(a) < MIN_SCALE_ARM) return null;
+  return { ratio: Math.max(b / a, MIN_RATIO), axis, pivot };
+}

package/src/stage/interactions/panZoom.ts

@@ -0,0 +1,60 @@
+// Pan and zoom of the working area. Pure: (event, view) -> view.
+//
+// It writes only `ShotView`, never the camera, because `view.ts` owns the one
+// conversion into `setViewOffset`. Two places computing a camera from a gesture
+// is how a lane ends up with a frame border that disagrees with the render.
+import { clampZoom, zoomAt } from "../view.js";
+import type { FrameSize, ShotView, Viewport } from "../view.js";
+
+/**
+ * A wheel event.
+ *
+ * ctrl/meta + wheel is a browser pinch-zoom gesture — trackpads report a pinch
+ * as exactly that, so honouring it is what makes two-finger zoom work at all.
+ * A plain wheel PANS, which is what every design tool does and what makes a
+ * trackpad's two-finger scroll usable.
+ *
+ * `deltaMode` is honoured because Firefox reports lines (1) and pages (2) where
+ * Chrome reports pixels (0); ignoring it makes the same gesture ~16x weaker on
+ * one browser.
+ */
+export function wheelToView(
+  event: {
+    deltaX: number;
+    deltaY: number;
+    deltaMode: number;
+    ctrlKey: boolean;
+    metaKey: boolean;
+  },
+  point: readonly [number, number],
+  view: ShotView,
+  viewport: Viewport,
+  frame: FrameSize,
+): ShotView {
+  const scale = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.height : 1;
+  const dx = event.deltaX * scale;
+  const dy = event.deltaY * scale;
+  if (event.ctrlKey || event.metaKey) {
+    // Exponential, so a fixed wheel notch is a fixed RATIO at every zoom —
+    // linear steps crawl when zoomed out and jump when zoomed in.
+    return zoomAt(view, viewport, frame, point, clampZoom(view.zoom * Math.exp(-dy / 320)));
+  }
+  return { ...view, panX: view.panX - dx, panY: view.panY - dy };
+}
+
+/** A pan drag: the view at press, plus the pointer's total displacement. Always
+ *  measured from the PRESS, never accumulated per move, so a coalesced move or
+ *  a clamp cannot make the canvas drift away from the cursor. */
+export function panBy(start: ShotView, deltaX: number, deltaY: number): ShotView {
+  return { ...start, panX: start.panX + deltaX, panY: start.panY + deltaY };
+}
+
+/**
+ * Does this pointer event start a PAN rather than a selection?
+ *
+ * Middle button, or space held. Both are the conventions a designer already
+ * has, and neither collides with a left-drag marquee.
+ */
+export function isPanGesture(event: { button: number }, spaceHeld: boolean): boolean {
+  return event.button === 1 || spaceHeld;
+}