@dailies-studio/shot-editor 0.1.0

package/src/stage/shading.ts

@@ -0,0 +1,55 @@
+// The working pane's shading modes, as PLAIN DATA both documents share.
+//
+// Like `panes.ts`, this module is three-free arithmetic-and-tables on purpose:
+// the chrome needs the vocabulary (the ShadingBar, the keymap's cycle, the
+// store's pref) and the stage needs the draw policy, and a second declaration
+// of "what wireframe means" in either document would be a second truth. The
+// GL half — which materials, which pipeline — stays in SplitRenderer; what
+// lives here is only the DECISION, which is what a GPU-free test can pin.
+//
+// The camera pane is always the graded render and is deliberately not in this
+// vocabulary at all: a shading mode is a statement about the WORKING pane, the
+// workspace's clay model of the scene, never about the shot.
+
+export type ShadingMode = "solid" | "wireframe" | "material" | "rendered";
+
+/** Bar order, which is also Z's cycle order: cheapest first, truest last. */
+export const SHADING_MODES: readonly ShadingMode[] = ["solid", "wireframe", "material", "rendered"];
+
+/** Z's cycle, wrapping. */
+export function nextShading(mode: ShadingMode): ShadingMode {
+  const at = SHADING_MODES.indexOf(mode);
+  return SHADING_MODES[(at + 1) % SHADING_MODES.length]!;
+}
+
+/** Boundary clamp, the `clampSplitRatio` rationale: the stage does not get to
+ *  assume its caller was careful, and garbage means the default, not a throw. */
+export function clampShading(mode: unknown): ShadingMode {
+  return SHADING_MODES.includes(mode as ShadingMode) ? (mode as ShadingMode) : "solid";
+}
+
+/**
+ * What the working pane does this frame, per mode.
+ *
+ * `override` names which override material covers the scene ("clay" is
+ * today's flat grey, "wire" its wireframe twin, null draws the real layer
+ * materials). `graded` runs the scene through the post chain from the working
+ * camera — and it is only ever true when the scene HAS a chain, so "rendered"
+ * on an effect-less scene degrades to the material plan rather than paying
+ * for a pipeline that would output its own input.
+ */
+export function workingDrawPlan(
+  mode: ShadingMode,
+  hasChain: boolean,
+): { override: "clay" | "wire" | null; graded: boolean } {
+  switch (mode) {
+    case "solid":
+      return { override: "clay", graded: false };
+    case "wireframe":
+      return { override: "wire", graded: false };
+    case "material":
+      return { override: null, graded: false };
+    case "rendered":
+      return { override: null, graded: hasChain };
+  }
+}

package/src/stage/tokenColor.ts

@@ -0,0 +1,26 @@
+// A palette token, resolved into a three `Color`.
+//
+// Every editor-only object in the working pane is drawn with a MATERIAL colour,
+// and a material colour cannot read a CSS custom property the way an SVG fill
+// can. Resolving one at mount, inside the stage document — which imports
+// shotTokens.css — is what lets the gizmo, the grid and the SVG overlay share
+// the single definition in that file instead of each carrying its own literal.
+//
+// Not for GL CLEAR colours: SplitRenderer's clay backdrop is hard-coded because
+// it is written before any style has resolved.
+import { Color } from "three";
+
+export function tokenColor(name: string, fallback: string): Color {
+  const backstop = new Color(fallback);
+  if (typeof document === "undefined") return backstop;
+  const token = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+  if (token.length === 0) return backstop;
+  try {
+    return new Color(token);
+  } catch {
+    // A token that is not a colour three can parse (a `color-mix`, a var chain
+    // that resolved to nothing) is a stylesheet bug, and drawing in the
+    // fallback is what keeps it a cosmetic one rather than a mount that throws.
+    return backstop;
+  }
+}

package/src/stage/view.ts

@@ -0,0 +1,182 @@
+// The working area: one camera, a wider render than the export frame, and the
+// frame's screen rect derived from the same numbers.
+//
+// ── WHY THERE IS ONLY ONE CAMERA ─────────────────────────────────────────
+//
+// Raylight's authoring view IS the shot. "A bright border marks the exportable
+// frame; you can work off-canvas" describes a view WIDER THAN THE FRAME, not a
+// different camera — and that is exactly `camera.setViewOffset`.
+//
+// A second, flat "design camera" would let an author position a layer in a view
+// the export never shows. That is the class of bug the 2D lane's address rule
+// was written to eliminate, and it is not worth reintroducing for a pan.
+//
+// ── THE MODEL ────────────────────────────────────────────────────────────
+//
+// The camera's BASE frustum is the export frame's: `aspect = W/H`, the scene's
+// fov, and `planeDistance` deriving the distance — so with no view offset it
+// renders the frame and nothing else. `setViewOffset` then carves out the
+// sub-rectangle the viewport actually shows, measured in DESIGN PIXELS of that
+// frame. Everything below is that one conversion, in both directions.
+//
+// Because the offset lives in the camera's projection matrix, `project.ts`
+// needs to know nothing about pan or zoom: `Vector3.project` already carries
+// them, so the overlay cannot drift from what was drawn. That is the whole
+// reason to do it this way rather than with a CSS transform over the canvas.
+//
+// KEEP THIS FILE SMALL. Its 2D counterpart (`measure.ts`, 558 lines) is the
+// file everyone dreads, and three consumers — the frame border, the snap
+// thresholds and the marquee — have to agree with it to the sub-pixel.
+
+/** Where the export frame sits in the working area. */
+export interface ShotView {
+  /** Screen px per design px at z = 0. */
+  zoom: number;
+  /** Screen px the frame's CENTRE is displaced from the viewport's centre. */
+  panX: number;
+  panY: number;
+}
+
+/** The viewport the stage actually has, in CSS px. */
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+/** The design canvas, in design px. */
+export interface FrameSize {
+  width: number;
+  height: number;
+}
+
+/** three's `setViewOffset` arguments, in the frame's own design pixels. */
+export interface ViewOffset {
+  fullWidth: number;
+  fullHeight: number;
+  offsetX: number;
+  offsetY: number;
+  width: number;
+  height: number;
+}
+
+export const MIN_ZOOM = 0.02;
+export const MAX_ZOOM = 32;
+
+export function clampZoom(zoom: number): number {
+  if (!Number.isFinite(zoom) || zoom <= 0) return 1;
+  return Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, zoom));
+}
+
+/**
+ * The camera view offset for a view.
+ *
+ * `fullWidth/fullHeight` are the FRAME in design px, so the sub-rect is read
+ * directly in design px too: the viewport is `viewport.width / zoom` design px
+ * wide, and it starts wherever the pan puts it.
+ */
+export function viewOffsetFor(view: ShotView, viewport: Viewport, frame: FrameSize): ViewOffset {
+  const zoom = clampZoom(view.zoom);
+  const width = viewport.width / zoom;
+  const height = viewport.height / zoom;
+  return {
+    fullWidth: frame.width,
+    fullHeight: frame.height,
+    // A pan that moves the frame RIGHT on screen moves the visible window LEFT
+    // within the frame, hence the subtraction. Getting this sign wrong makes
+    // the canvas drag the wrong way, which is unmistakable and therefore cheap.
+    offsetX: (frame.width - width) / 2 - view.panX / zoom,
+    offsetY: (frame.height - height) / 2 - view.panY / zoom,
+    width,
+    height,
+  };
+}
+
+/**
+ * The exportable frame's rectangle on screen, in CSS px from the canvas
+ * top-left.
+ *
+ * DERIVED FROM THE SAME NUMBERS as the view offset, deliberately: the frame
+ * border, the snap thresholds and the marquee all read this, and a border
+ * computed independently would disagree with the render by a sub-pixel at some
+ * zooms — which reads as "snapping feels sticky in one direction" rather than
+ * as a projection bug.
+ */
+export function frameRect(
+  view: ShotView,
+  viewport: Viewport,
+  frame: FrameSize,
+): { x: number; y: number; width: number; height: number } {
+  const zoom = clampZoom(view.zoom);
+  const offset = viewOffsetFor(view, viewport, frame);
+  return {
+    x: -offset.offsetX * zoom,
+    y: -offset.offsetY * zoom,
+    width: frame.width * zoom,
+    height: frame.height * zoom,
+  };
+}
+
+/** Screen px (canvas top-left) -> design px of the z = 0 plane. The inverse of
+ *  `frameRect`, and the two are tested against each other. */
+export function screenToDesign(
+  point: readonly [number, number],
+  view: ShotView,
+  viewport: Viewport,
+  frame: FrameSize,
+): [number, number] {
+  const rect = frameRect(view, viewport, frame);
+  const zoom = clampZoom(view.zoom);
+  return [(point[0] - rect.x) / zoom, (point[1] - rect.y) / zoom];
+}
+
+/** Design px of the z = 0 plane -> screen px. */
+export function designToScreen(
+  point: readonly [number, number],
+  view: ShotView,
+  viewport: Viewport,
+  frame: FrameSize,
+): [number, number] {
+  const rect = frameRect(view, viewport, frame);
+  const zoom = clampZoom(view.zoom);
+  return [rect.x + point[0] * zoom, rect.y + point[1] * zoom];
+}
+
+/** Space left around the frame when fitting, as a fraction of the viewport. */
+export const FIT_MARGIN = 0.08;
+
+/** The view that shows the whole frame with a margin. Pure in the viewport and
+ *  the frame, so the chrome's "fit" button and a window resize agree. */
+export function fitView(viewport: Viewport, frame: FrameSize): ShotView {
+  if (viewport.width <= 0 || viewport.height <= 0) return { zoom: 1, panX: 0, panY: 0 };
+  const usable = 1 - FIT_MARGIN * 2;
+  const zoom = Math.min(
+    (viewport.width * usable) / frame.width,
+    (viewport.height * usable) / frame.height,
+  );
+  return { zoom: clampZoom(zoom), panX: 0, panY: 0 };
+}
+
+/**
+ * Zoom about a screen point: the design pixel under the cursor stays under the
+ * cursor.
+ *
+ * That anchoring is the whole difference between a zoom that feels like a
+ * camera and one that feels like a slider — and it is one equation, so there is
+ * no reason to ship the slider version first.
+ */
+export function zoomAt(
+  view: ShotView,
+  viewport: Viewport,
+  frame: FrameSize,
+  screenPoint: readonly [number, number],
+  nextZoom: number,
+): ShotView {
+  const zoom = clampZoom(nextZoom);
+  const anchor = screenToDesign(screenPoint, view, viewport, frame);
+  const after = designToScreen(anchor, { ...view, zoom }, viewport, frame);
+  return {
+    zoom,
+    panX: view.panX + (screenPoint[0] - after[0]),
+    panY: view.panY + (screenPoint[1] - after[1]),
+  };
+}