@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/frustumGeometry.ts

@@ -26,6 +26,7 @@
 // COORDINATES ARE WORLD (three). The one mapping — design (x, y, z) is world
 // (x, -y, -z) — is applied here and nowhere downstream, the same note
 // workingView.ts carries.
+import { rigPose as shotRigPose } from "@dailies-studio/shot/doc";
 import type { Framing } from "@dailies-studio/shot/doc";
 import type { FrameSize } from "./view.js";
 
@@ -79,7 +80,9 @@ export function frustumShape(rig: CameraRig, frame: FrameSize): FrustumShape {
   // The framing's pan IS the camera's position on the plane, negated in y by
   // the one mapping.
   const cx = finite(rig.framing.x, 0);
-  const cy = -finite(rig.framing.y, 0);
+  // `+ 0` folds a negative zero, so this apex and `rigPose`'s eye are equal
+  // component by component and not only close.
+  const cy = -finite(rig.framing.y, 0) + 0;
   const at = (u: number, v: number): Vec3 => [
     cx + right[0] * u * halfW + up[0] * v * halfH,
     cy + right[1] * u * halfW + up[1] * v * halfH,
@@ -104,6 +107,85 @@ export function frustumShape(rig: CameraRig, frame: FrameSize): FrustumShape {
   };
 }
 
+/** A camera as three holds it: where it is, its world basis and its lens.
+ *  `right`, `up` and `forward` are unit vectors. */
+export interface CameraPose {
+  eye: Vec3;
+  right: Vec3;
+  up: Vec3;
+  forward: Vec3;
+  fovDeg: number;
+}
+
+/**
+ * IS THE CAMERA STILL WHERE THE RIG PUT IT?
+ *
+ * `ShotCamera` places the render camera on the rig every frame: eye at
+ * `(x, -y, distance)`, looking down -z, rolled about it, at the rig's lens. An
+ * instance component may then write that same camera in its own `useFrame`
+ * (a flythrough drives eye, target and lens itself). The camera pane renders
+ * with whatever the camera ends up as, so the gizmo has to know which of the
+ * two it is looking at, and this is the one test that tells them apart. The
+ * tolerances are float noise only: a component that moves the camera moves
+ * it by far more than these.
+ */
+export function offTheRig(rig: CameraRig, pose: CameraPose): boolean {
+  const own = rigPose(rig);
+  const slack = 1e-4 * Math.max(1, Math.abs(finite(rig.distance, 1)));
+  for (let k = 0; k < 3; k++) {
+    if (Math.abs(pose.eye[k]! - own.eye[k]!) > slack) return true;
+  }
+  // A roll turns about the view axis, so the rig's forward is its own whatever
+  // the roll; only a component's `lookAt` can turn it away.
+  const along = pose.forward[0] * own.forward[0] + pose.forward[1] * own.forward[1] + pose.forward[2] * own.forward[2];
+  if (along < 1 - 1e-6) return true;
+  return Math.abs(pose.fovDeg - own.fovDeg) > 1e-3;
+}
+
+/**
+ * IS SOMETHING ELSE DRIVING THE CAMERA? A declared driver (the runtime's
+ * camera claim) is the answer when there is one; `offTheRig` is the fallback
+ * for a component that writes the camera without claiming it.
+ */
+export function isDriven(driver: { name: string } | null, rig: CameraRig, pose: CameraPose | null): boolean {
+  if (driver !== null) return true;
+  return pose !== null && offTheRig(rig, pose);
+}
+
+/**
+ * THE FRUSTUM OF A CAMERA SOMETHING ELSE IS DRIVING.
+ *
+ * There is no design plane to land the rectangle on: the component's world is
+ * its own scale and its camera looks wherever it likes. So the rectangle sits
+ * `distance` ahead of the eye along the view axis, sized by the lens exactly
+ * as the rig's is, and the caller picks the distance so the gizmo keeps a
+ * readable size on screen. Same winding, same up-marker, so the drawing reads
+ * as the same camera whoever is moving it.
+ */
+export function frustumShapeAhead(pose: CameraPose, distance: number, frame: FrameSize): FrustumShape {
+  const d = finite(distance, 1);
+  const halfH = Math.abs(d * Math.tan((finite(pose.fovDeg, 35) * DEG) / 2));
+  const aspect = frame.height > 0 ? frame.width / frame.height : 1;
+  const halfW = halfH * aspect;
+  const { eye, right, up, forward } = pose;
+  const centre: Vec3 = [eye[0] + forward[0] * d, eye[1] + forward[1] * d, eye[2] + forward[2] * d];
+  const from = (origin: Vec3, u: number, v: number): Vec3 => [
+    origin[0] + right[0] * u * halfW + up[0] * v * halfH,
+    origin[1] + right[1] * u * halfW + up[1] * v * halfH,
+    origin[2] + right[2] * u * halfW + up[2] * v * halfH,
+  ];
+  const topMid = from(centre, 0, 1);
+  return {
+    apex: [eye[0], eye[1], eye[2]],
+    corners: [from(centre, -1, 1), from(centre, 1, 1), from(centre, 1, -1), from(centre, -1, -1)],
+    up: [
+      from(topMid, -UP_BASE_FRACTION, 0),
+      from(topMid, 0, UP_HEIGHT_FRACTION),
+      from(topMid, UP_BASE_FRACTION, 0),
+    ],
+  };
+}
+
 /** Every segment as a flat xyz pair list, ready for a `LineSegments` position
  *  attribute: four pyramid edges, the base rectangle, then the up-marker. */
 export function frustumSegments(shape: FrustumShape): number[] {
@@ -125,6 +207,88 @@ export function frustumSegments(shape: FrustumShape): number[] {
  *  the first call happened to produce. */
 export const FRUSTUM_SEGMENT_FLOATS = 11 * 2 * 3;
 
+// ── A PATH MOVE'S WAYPOINTS ─────────────────────────────────────────────────
+//
+// Same file, same reason as the frustum's own vertices: the marks are the only
+// part that can be silently WRONG. A waypoint drawn at the wrong depth still
+// looks like a waypoint, and the author would read the error as the camera
+// travelling somewhere it does not.
+//
+// ONE MAPPING, THE SAME ONE. A waypoint is a `Framing`, so its eye is exactly
+// where `cameraRigAt` would put the camera at that pose: `(x, -y, distance)`,
+// with the distance derived from the scene's fov and the pose's own zoom. This
+// file does not import `planeDistance` — it takes the distance as an argument,
+// the same way `CameraRig` states what it needs rather than importing a shape
+// it cannot check.
+
+/** Half-extent of a waypoint's cross, as a fraction of the SCENE'S extent (the
+ *  camera body's own rule below): 0.02 of a 1920-wide frame is the 38 design px
+ *  the old frame-height fraction gave. */
+export const WAYPOINT_CROSS_FRACTION = 0.02;
+/** ...clamped on screen like the body, so a cross is never a dot from far away
+ *  and a five-waypoint path never becomes a wall of crosses up close. */
+export const WAYPOINT_CROSS_MIN_PX = 6;
+export const WAYPOINT_CROSS_MAX_PX = 20;
+
+/** A waypoint cross's half-extent in world units, for a world-per-pixel at
+ *  that eye. `wpp` of zero (no camera on screen yet) leaves it unclamped. */
+export function waypointCrossSize(extent: number, wpp: number): number {
+  const scene = finite(extent, 0);
+  let size = WAYPOINT_CROSS_FRACTION * (scene > 0 ? scene : 1);
+  const perPixel = finite(wpp, 0);
+  if (perPixel > 0) {
+    size = Math.min(Math.max(size, WAYPOINT_CROSS_MIN_PX * perPixel), WAYPOINT_CROSS_MAX_PX * perPixel);
+  }
+  return size > 0 && Number.isFinite(size) ? size : 1;
+}
+
+/** The eye of each waypoint, in WORLD coordinates. `distances[i]` is
+ *  `planeDistance(frameHeight, fovDeg, waypoints[i].zoom)`. */
+export function waypointEyes(
+  waypoints: readonly Framing[],
+  distances: readonly number[],
+): Vec3[] {
+  return waypoints.map((pose, i) => [
+    finite(pose.x, 0),
+    -finite(pose.y, 0),
+    finite(distances[i] ?? 0, 0),
+  ]);
+}
+
+/**
+ * The marks: a three-axis cross at each eye, plus the polyline through them.
+ *
+ * The POLYLINE is not decoration — a path move curves through its middle poses
+ * with a centripetal spline, and without the line between them a reader cannot
+ * tell which waypoint comes after which. It is drawn straight rather than
+ * curved on purpose: the curve is what the resolver produces, and drawing a
+ * straight chord is honestly "these are the knots" rather than a second, wrong
+ * spline evaluated here.
+ */
+export function waypointSegments(eyes: readonly Vec3[], sizes: readonly number[]): number[] {
+  const out: number[] = [];
+  const seg = (a: Vec3, b: Vec3): void => {
+    out.push(a[0], a[1], a[2], b[0], b[1], b[2]);
+  };
+  for (let i = 0; i < eyes.length; i++) {
+    const eye = eyes[i]!;
+    // One size PER EYE: each cross is clamped against its own screen depth,
+    // and a missing size is a degenerate (but finite) cross rather than NaN.
+    const size = Math.max(0, finite(sizes[i] ?? 0, 0));
+    seg([eye[0] - size, eye[1], eye[2]], [eye[0] + size, eye[1], eye[2]]);
+    seg([eye[0], eye[1] - size, eye[2]], [eye[0], eye[1] + size, eye[2]]);
+    seg([eye[0], eye[1], eye[2] - size], [eye[0], eye[1], eye[2] + size]);
+  }
+  for (let i = 1; i < eyes.length; i++) seg(eyes[i - 1]!, eyes[i]!);
+  return out;
+}
+
+/** How many floats `waypointSegments` produces for `n` waypoints: three cross
+ *  axes each plus `n - 1` chords, two vertices of three floats per segment. */
+export function waypointSegmentFloats(n: number): number {
+  return (n * 3 + Math.max(0, n - 1)) * 2 * 3;
+}
+
 /** Did any vertex move enough to be worth re-uploading the buffer? Half a
  *  design pixel, mirroring `quadMoved`'s gate for the same reason: this runs on
  *  every committed frame and a still playhead must cost nothing. */
@@ -170,3 +334,157 @@ export function borderDistance(
 function finite(value: number, fallback: number): number {
   return Number.isFinite(value) ? value : fallback;
 }
+
+// ── THE CAMERA AS AN OBJECT ─────────────────────────────────────────────────
+//
+// The framed rectangle at the plane is the DOCUMENT's model and stays: it is
+// what is in shot, from any angle. What it could never do is say "here is the
+// camera" at a size an author can read. A wide shot's rectangle dwarfs the
+// canvas, and a camera a component drives has no plane to land on at all, so
+// its rectangle used to be sized off the VIEWER's distance instead: constant
+// on screen, which reads as a camera that is huge from far away and shrinks as
+// you approach, the opposite of every object around it.
+//
+// So the camera also gets a BODY: a short lens pyramid in front of the eye and
+// a box behind it, sized against the SCENE it lives in (a fraction of the
+// design frame, or of a driven component's own content bounds) and clamped in
+// screen pixels so it never vanishes and never covers the pane. Blender's
+// camera object at a fixed display size, with the clamp Blender leaves to the
+// user. The rig case and the driven case draw through the same pose, so the
+// two cannot drift apart.
+
+/** The body's length (eye to lens rectangle) as a fraction of the scene's
+ *  extent. 0.06 of a 1920 frame is ~115 design px: about 6% of the pane at the
+ *  default working view. */
+export const CAMERA_DISPLAY_FRACTION = 0.06;
+/** The body never projects shorter than this, so it stays a readable object
+ *  from far away... */
+export const CAMERA_MIN_PX = 24;
+/** ...nor longer than this fraction of the pane's height, so up close it never
+ *  covers the picture. */
+export const CAMERA_MAX_PANE_FRACTION = 0.35;
+/** The box behind the eye: its depth as a fraction of the body's length, and
+ *  its cross-section as a fraction of the lens rectangle's half-extents. */
+export const BODY_DEPTH_FRACTION = 0.5;
+export const BODY_CROSS_FRACTION = 0.5;
+/** How close a press has to land to the body's projected box, or to the framed
+ *  rectangle's drawn border, in CSS px. The arms' own 14. */
+export const BODY_GRAB_PX = 14;
+
+/**
+ * The pose `ShotCamera` writes for a rig, orbit angles and roll included: the
+ * shot package's own `rigPose`, re-exported so this file stays the one import
+ * the gizmo needs. THE ONE PLACE the rig becomes a pose, so the body, the
+ * framed rectangle, the runtime's camera and `offTheRig` all agree.
+ */
+export const rigPose: (rig: CameraRig) => CameraPose = shotRigPose;
+
+/**
+ * How long the body is, in world units.
+ *
+ * A fixed fraction of the scene's extent, then clamped between a floor and a
+ * ceiling measured in SCREEN pixels at the apex (`wpp` is world units per CSS
+ * px there), so between the clamps the body shrinks and grows with the scene
+ * exactly as the layers around it do. `maxWorld` is the rig case's cap: the
+ * lens rectangle has to stay in front of the design plane.
+ */
+export function cameraDisplayLength(
+  extent: number,
+  wpp: number,
+  paneHeightPx: number,
+  maxWorld: number = Number.POSITIVE_INFINITY,
+): number {
+  const scene = finite(extent, 0);
+  let length = CAMERA_DISPLAY_FRACTION * (scene > 0 ? scene : 1);
+  const perPixel = finite(wpp, 0);
+  if (perPixel > 0) {
+    const height = finite(paneHeightPx, 0);
+    const floor = CAMERA_MIN_PX * perPixel;
+    const ceiling = height > 0 ? CAMERA_MAX_PANE_FRACTION * height * perPixel : Number.POSITIVE_INFINITY;
+    length = Math.min(Math.max(length, floor), Math.max(floor, ceiling));
+  }
+  if (Number.isFinite(maxWorld) && maxWorld > 0) length = Math.min(length, maxWorld);
+  return length > 0 && Number.isFinite(length) ? length : 1;
+}
+
+/** The body's vertices: the eye, the lens rectangle `length` ahead, the box
+ *  behind the eye (front ring then back ring, TL TR BR BL each) and the
+ *  up-marker on the lens rectangle's top edge. */
+export interface CameraBodyShape {
+  apex: Vec3;
+  near: [Vec3, Vec3, Vec3, Vec3];
+  box: [Vec3, Vec3, Vec3, Vec3, Vec3, Vec3, Vec3, Vec3];
+  up: [Vec3, Vec3, Vec3];
+}
+
+export function cameraBodyShape(pose: CameraPose, length: number, frame: FrameSize): CameraBodyShape {
+  const L = finite(length, 1);
+  // The lens rectangle IS the frustum's cross-section `L` ahead, so it comes
+  // out of the same function the driven rectangle always did.
+  const lens = frustumShapeAhead(pose, L, frame);
+  const halfH = Math.abs(L * Math.tan((finite(pose.fovDeg, 35) * DEG) / 2));
+  const aspect = frame.height > 0 ? frame.width / frame.height : 1;
+  const bw = BODY_CROSS_FRACTION * halfH * aspect;
+  const bh = BODY_CROSS_FRACTION * halfH;
+  const depth = BODY_DEPTH_FRACTION * L;
+  const { eye, right, up, forward } = pose;
+  const at = (d: number, u: number, v: number): Vec3 => [
+    eye[0] - forward[0] * d + right[0] * u * bw + up[0] * v * bh,
+    eye[1] - forward[1] * d + right[1] * u * bw + up[1] * v * bh,
+    eye[2] - forward[2] * d + right[2] * u * bw + up[2] * v * bh,
+  ];
+  return {
+    apex: lens.apex,
+    near: lens.corners,
+    box: [
+      at(0, -1, 1),
+      at(0, 1, 1),
+      at(0, 1, -1),
+      at(0, -1, -1),
+      at(depth, -1, 1),
+      at(depth, 1, 1),
+      at(depth, 1, -1),
+      at(depth, -1, -1),
+    ],
+    up: lens.up,
+  };
+}
+
+/** The body's segments: four short edges apex-first, the lens rectangle, the
+ *  twelve box edges, then the up-marker. */
+export function cameraBodySegments(shape: CameraBodyShape): number[] {
+  const { apex, near, box, up } = shape;
+  const out: number[] = [];
+  const seg = (a: Vec3, b: Vec3): void => {
+    out.push(a[0], a[1], a[2], b[0], b[1], b[2]);
+  };
+  for (const corner of near) seg(apex, corner);
+  for (let i = 0; i < 4; i++) seg(near[i]!, near[(i + 1) % 4]!);
+  for (let i = 0; i < 4; i++) seg(box[i]!, box[(i + 1) % 4]!);
+  for (let i = 0; i < 4; i++) seg(box[4 + i]!, box[4 + ((i + 1) % 4)]!);
+  for (let i = 0; i < 4; i++) seg(box[i]!, box[4 + i]!);
+  seg(up[0], up[1]);
+  seg(up[1], up[2]);
+  seg(up[2], up[0]);
+  return out;
+}
+
+/** How many floats `cameraBodySegments` writes: 23 segments. */
+export const CAMERA_BODY_SEGMENT_FLOATS = 23 * 2 * 3;
+
+/** The reach from the eye to the framed rectangle at the plane: the four long
+ *  pyramid edges and the rectangle itself. The first eight segments of
+ *  `frustumSegments`, without the up-marker the body now carries. */
+export function frameSegments(shape: FrustumShape): number[] {
+  const { apex, corners } = shape;
+  const out: number[] = [];
+  const seg = (a: Vec3, b: Vec3): void => {
+    out.push(a[0], a[1], a[2], b[0], b[1], b[2]);
+  };
+  for (const corner of corners) seg(apex, corner);
+  for (let i = 0; i < 4; i++) seg(corners[i]!, corners[(i + 1) % 4]!);
+  return out;
+}
+
+/** How many floats `frameSegments` writes: 8 segments. */
+export const FRAME_SEGMENT_FLOATS = 8 * 2 * 3;

package/src/stage/furnitureTokens.ts

@@ -0,0 +1,33 @@
+// The design tokens, rescoped from the stage document's ROOT to its furniture.
+//
+// The stage mounts the author's real components, and its root is theirs. The
+// house token files declare their names on `:root`, so imported as-is they put
+// a hundred house custom properties on the authored root. That root is also
+// where a project's own theme lives: an unlayered house `--accent` or
+// `--font-sans` beats a framework's layered theme variable of the same name,
+// so the authored content previews in house values and exports in its own,
+// which is the preview-versus-export split this lane refuses.
+//
+// So the stage takes the SAME two files as text and rewrites their selectors
+// onto `[data-dailies-stage-furniture]`, the attribute every Dailies-owned
+// layer in the stage carries (the overlay SVG, the token probe, the crash
+// card). The authored root declares no house token at all.
+//
+// A second win comes free: every furniture element now DECLARES the tokens,
+// so a var()-derived token (a fill wash, an alias) resolves on that element
+// in its own theme instead of arriving pre-resolved from a dark root.
+
+export const FURNITURE = "[data-dailies-stage-furniture]";
+export const LIGHT_FURNITURE = `:root[data-dailies-studio-theme="light"] ${FURNITURE}`;
+
+/** One token sheet's text with every root selector moved onto the furniture:
+ *  `:root` becomes the furniture attribute, and the chrome's light scope
+ *  (`:root[data-theme="light"]`) becomes the stage's (the studio theme on the
+ *  stage root, then the furniture). Comments are dropped; they are for the
+ *  source file, not the page. */
+export function scopeToFurniture(css: string): string {
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/:root\[data-theme="light"\]/g, LIGHT_FURNITURE)
+    .replace(/:root(?=\s*[{,])/g, FURNITURE);
+}