@dailies-studio/shot-editor 0.1.0

package/src/stage/modalState.ts

@@ -0,0 +1,427 @@
+// Blender-style modal transforms (G / R / S) as PURE data and mapping tables.
+//
+// The shape penState.ts established, for the same reason: this module owns
+// what a modal transform MEANS — which gesture kind each mode+axis emits and
+// with what numbers — and none of the plumbing. StageApp owns the pointer,
+// the rays and the capture-phase key listener; the store's gesture lane owns
+// what a delta DOES (base write, block, refusal). Nothing here imports three,
+// so every row of the mapping table is testable in node.
+//
+// ── THE ONE IDEA: A MODAL IS THE EXISTING GESTURE LANE, RE-DRIVEN ───────
+//
+// A modal transform opens the same `onGestureStart` / N× `onGesture` /
+// `onGestureEnd` scrub a pointer drag opens; only the input differs (mouse
+// MOTION with no button held, terminated by click/Enter/Escape). Every emit
+// is a TOTAL from the anchor, and the store re-derives from the scrub's base
+// per capture — which is what makes two properties safe by construction:
+//
+//   AXIS TOGGLES RE-PROJECT. Constraining mid-gesture changes the emitted
+//   KIND (move ↔ depth, roll ↔ tilt); the last delta wins wholesale from
+//   base, which is exactly Blender's re-projection behaviour.
+//
+//   PRECISION CANNOT DRIFT THE DOCUMENT. Shift scales the VIRTUAL CURSOR's
+//   steps (`advanceVirtual`), so only the accumulated travel is
+//   path-dependent — which is what precision means — while the document
+//   still re-derives from base on every emit.
+import type { FramingDelta, GestureDelta, GestureKind } from "../bridgeTypes.js";
+
+export type ModalMode = "move" | "rotate" | "scale";
+export type ModalAxis = "x" | "y" | "z" | null;
+
+export interface ModalState {
+  mode: ModalMode;
+  /** Layers when the selection is non-empty, else the CAMERA's framing — the
+   *  same implicit subject the frustum gizmo already has. The camera is
+   *  deliberately not selectable (see the keymap's starter lane). */
+  target: "layers" | "camera";
+  axis: ModalAxis;
+}
+
+/** Degrees of tilt/roll per CSS pixel dragged. A whole screen width should be
+ *  about a half turn, or rotating is either unusable or uncontrollable. ONE
+ *  definition for the drag lane and the modal lane — StageApp imports it from
+ *  here. */
+export const TILT_DEG_PER_PX = 0.4;
+
+/** Shift's precision factor on the virtual cursor's steps. */
+export const PRECISION_FACTOR = 0.1;
+
+/** Travel px for one e-fold of a modal scale. The same 320 the wheel dolly and
+ *  the frustum apex use, so "one notch" is the same proportion whichever of the
+ *  three the author reaches for. */
+export const SCALE_FALLOFF_PX = 320;
+
+/**
+ * What CTRL quantises to, per unit.
+ *
+ * Blender's own 15 degrees for a rotation. 10 design px is a round number in a
+ * 1080-tall canvas and the step the arrow keys already coarse-nudge by
+ * (`NUDGE_COARSE_PX`), so the two agree about what "a round move" is. A tenth
+ * is what a scale's round numbers are: 1.5x, 2x.
+ *
+ * There is deliberately NO second snap threshold here. The chrome's smart
+ * guides snap a drag to other layers' edges, which is a different question
+ * — "line this up with that" rather than "give me a round number" — and a
+ * quantise that also tried to be a guide would fight it.
+ */
+export const SNAP_PX = 10;
+export const SNAP_DEG = 15;
+export const SNAP_RATIO = 0.1;
+
+export function modalTarget(hasSelection: boolean): ModalState["target"] {
+  return hasSelection ? "layers" : "camera";
+}
+
+/**
+ * Toggle an axis constraint: the same axis again clears it, a different one
+ * replaces it — Blender's toggle. Three claimed-and-ignored cells: `z` in
+ * scale mode (size is a Vec2, there is no z to scale), any axis on the
+ * camera's zoom (a dolly has no axis), and `z` on the camera's move (a
+ * framing has no z). Ignoring rather than storing them keeps the label
+ * honest — a pill saying "Scale · Z" over a gesture that ignores z would be
+ * a lie.
+ */
+export function modalAxisToggle(state: ModalState, axis: "x" | "y" | "z"): ModalState {
+  if (state.mode === "scale" && axis === "z") return state;
+  if (state.target === "camera" && (state.mode === "scale" || axis === "z")) return state;
+  return { ...state, axis: state.axis === axis ? null : axis };
+}
+
+/**
+ * Why a claimed axis was ignored, or null when it was honoured.
+ *
+ * The three ignored cells used to be silent: `onModalKey` had already called
+ * `preventDefault` and `stopPropagation`, so pressing Z during a scale
+ * swallowed the key and changed nothing, with no way to tell that from a key
+ * that had not registered. A modal that eats input without saying so is the
+ * one place in this lane an author cannot debug by looking.
+ *
+ * Data rather than a thrown string, because the pill renders it.
+ */
+export function axisRefusal(state: ModalState, axis: "x" | "y" | "z"): string | null {
+  if (state.mode === "scale" && axis === "z") {
+    return "SIZE HAS NO Z";
+  }
+  if (state.target === "camera" && state.mode === "scale") return "A ZOOM HAS NO AXIS";
+  if (state.target === "camera" && axis === "z") return "A FRAMING HAS NO Z";
+  return null;
+}
+
+/**
+ * The live delta, as the pill shows it.
+ *
+ * NUMBERS, because "SCALE · X" says which transform is running and nothing at
+ * all about how far it has gone — and the working pane has no ruler. Blender
+ * puts the same figures in its header, and it is what makes a modal usable
+ * without numeric entry.
+ *
+ * Formatted from the DELTA the gesture actually emitted, not re-derived from
+ * the travel: a readout computed a second way is a readout that can disagree
+ * with the layer under it.
+ */
+export function modalReadout(delta: GestureDelta | FramingDelta | null): string {
+  if (delta === null) return "";
+  if (!("kind" in delta)) {
+    // A framing delta: the camera's own move or zoom.
+    return delta.dzoom === 1
+      ? `${round(delta.dx)}, ${round(delta.dy)}`
+      : `×${delta.dzoom.toFixed(2)}`;
+  }
+  switch (delta.kind) {
+    case "scale":
+      return `×${(delta.ratio ?? 1).toFixed(2)}`;
+    case "roll":
+    case "tilt":
+      return `${round(delta.dx || delta.dy)}°`;
+    case "depth":
+      return `${round(delta.dy)} z`;
+    default:
+      return `${round(delta.dx)}, ${round(delta.dy)}`;
+  }
+}
+
+/** One decimal at most, and no trailing `.0`: design px are integers in
+ *  practice and `12.0` reads as more precision than the gesture has. */
+function round(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  return (Math.round(n * 10) / 10).toString();
+}
+
+/** The gesture kind the scrub OPENS with. The kind may legally change per
+ *  capture (axis toggles); this is only the first. */
+export function initialGestureKind(state: ModalState): GestureKind {
+  switch (state.mode) {
+    case "move":
+      return "move";
+    case "rotate":
+      return "roll";
+    case "scale":
+      // The RATIO kind, not the additive `resize` one. It only decides which
+      // channel the scrub announces, and both write `scale`, but the kind the
+      // gesture actually emits and the kind it opened with disagreeing is the
+      // kind of drift this table exists to prevent.
+      return "scale";
+  }
+}
+
+/** The pill's text: the transform, its axis, and — for the camera — its
+ *  subject, so the implicit target is never ambiguous. */
+export function modalLabel(state: ModalState): string {
+  const axis = state.axis === null ? "" : ` · ${state.axis.toUpperCase()}`;
+  if (state.target === "camera") {
+    return state.mode === "scale" ? "CAMERA ZOOM" : `CAMERA MOVE${axis}`;
+  }
+  switch (state.mode) {
+    case "move":
+      return `MOVE${axis}`;
+    case "rotate":
+      return state.axis === null || state.axis === "z" ? "ROLL" : `TILT · ${state.axis.toUpperCase()}`;
+    case "scale":
+      return `SCALE${axis}`;
+  }
+}
+
+/** One virtual-cursor step: the raw pointer travel, scaled down while shift
+ *  is held. Pure so the accumulation rule is a testable table row. */
+export function advanceVirtual(
+  virtual: readonly [number, number],
+  from: readonly [number, number],
+  to: readonly [number, number],
+  precision: boolean,
+): [number, number] {
+  const k = precision ? PRECISION_FACTOR : 1;
+  return [virtual[0] + (to[0] - from[0]) * k, virtual[1] + (to[1] - from[1]) * k];
+}
+
+/**
+ * The layer mapping table — mode + axis + travel → the existing lane's delta.
+ *
+ * `travel` is the virtual cursor's total from the anchor, in pane CSS px.
+ * `planar` is `designDelta(anchorRay, virtualRay, framePlane)` — the flat
+ * "move it on the canvas" plane, matching what the letter G already means in
+ * this editor — or null when the mode does not need a plane (or the ray was
+ * edge-on, in which case a move emits nothing rather than NaN).
+ * `screenScale` is `workingScreenScale(...)`: CSS px per design px, dividing
+ * every screen-space kind exactly as the pointer lane divides by the zoom.
+ *
+ * Scale is driven by HORIZONTAL travel in every axis mode (right grows, left
+ * shrinks — additive design px, not Blender's pivot-distance ratio; "basic"
+ * scale, documented). `keepAspect` + `aboutCentre` on a corner handle IS
+ * uniform-about-the-centre in the resize model; the single-axis modes use the
+ * side handles the same model already has.
+ */
+export function layerGestureFor(
+  state: ModalState,
+  travel: { x: number; y: number },
+  planar: { dx: number; dy: number; dz?: number } | null,
+  screenScale: number,
+  /** The world DESIGN point a scale grows away from or a ROLL turns about, or
+   *  null to transform each layer in place. The stage passes the selection's
+   *  median for a multi-select and null for one layer, which is Blender's own
+   *  default pivot. Tilt is deliberately not on that list — see the rotate
+   *  case. */
+  pivot: readonly [number, number, number] | null = null,
+  /**
+   * A TYPED value, replacing whatever the pointer had travelled.
+   *
+   * Blender's `G X 200 Enter`. It is applied HERE, in the mapping table,
+   * because that is the one place that knows what each mode's number MEANS:
+   * design px for a move, degrees for a rotate, a factor for a scale. A caller
+   * that substituted it upstream would have to know the same three things.
+   *
+   * A planar move is the exception it cannot be applied to without an axis —
+   * `designDelta` answers two components off two rays and there is no single
+   * scalar to replace. That is Blender's own rule too, and the caller refuses
+   * by name rather than guessing which component the author meant.
+   */
+  exact: number | null = null,
+  /**
+   * CTRL quantises, Blender's own modifier and the partner to shift's
+   * precision.
+   *
+   * Per mode, because the units differ: design px for a move, degrees for a
+   * rotate, a proportion for a scale. Applied to the EMITTED value rather than
+   * to the travel, so the layer lands on the round number the author is aiming
+   * at instead of on a round amount of mouse movement.
+   *
+   * It does nothing to a TYPED value: an exact number is already exact, and
+   * rounding what the author literally spelled would be the tool arguing.
+   */
+  snap = false,
+): GestureDelta | null {
+  const s = screenScale > 0 && Number.isFinite(screenScale) ? screenScale : 1;
+  const quantise = (n: number, step: number): number =>
+    snap && exact === null ? Math.round(n / step) * step : n;
+  switch (state.mode) {
+    case "move": {
+      if (state.axis === "z") {
+        // The existing depth lane's sign: drag DOWN pushes away (+z).
+        //
+        // THROUGH `quantise`, like X and Y two rows down. `G Z` was the one
+        // move arm that skipped it, so ctrl rounded two axes to whole design px
+        // and left the third fractional — a snap that half works reads as a
+        // snap that is broken.
+        return { kind: "depth", dx: 0, dy: exact ?? quantise(travel.y / s, SNAP_PX) };
+      }
+      if (exact !== null) {
+        // AXIS-CONSTRAINED ONLY. With no axis there is no single component to
+        // put the number on, and setting both would move the layer diagonally
+        // by a distance the author never asked for. Blender requires an axis
+        // here too. Refused in the TABLE as well as in the stage, so the pure
+        // half and the plumbing cannot disagree about what is representable.
+        if (state.axis === null) return null;
+        return {
+          kind: "move",
+          dx: state.axis === "y" ? 0 : exact,
+          dy: state.axis === "x" ? 0 : exact,
+          dz: 0,
+        };
+      }
+      if (planar === null) return null;
+      return {
+        kind: "move",
+        dx: state.axis === "y" ? 0 : quantise(planar.dx, SNAP_PX),
+        dy: state.axis === "x" ? 0 : quantise(planar.dy, SNAP_PX),
+        dz: 0,
+      };
+    }
+    case "rotate": {
+      const deg = exact ?? quantise(travel.x * TILT_DEG_PER_PX, SNAP_DEG);
+      // transformFor's tilt arms: tilt.x (rx) rides `dy`, tilt.y (ry) rides
+      // `dx`. Roll is the default AND the z constraint — the view-axis-most
+      // rotation this lane has.
+      //
+      // ── THE PIVOT RIDES ROLL AND NOT TILT ─────────────────────────────
+      //
+      // `R` and the rotate ring are two ways to run one operation, and only the
+      // ring passed a pivot — so on a multi-selection the ring orbited the
+      // group about its median while `R` spun every member in place. One
+      // gesture, two documents.
+      //
+      // TILT STAYS PIVOT-FREE: `applyGesture` only orbits a pivot in the design
+      // z plane (`rollDeg`'s own plane), so a tilt about a shared point is not
+      // something the document model can express. A single-layer roll still
+      // passes `null`, which is byte-identical to before.
+      if (state.axis === "x") return { kind: "tilt", dx: 0, dy: deg };
+      if (state.axis === "y") return { kind: "tilt", dx: deg, dy: 0 };
+      return { kind: "roll", dx: deg, dy: 0, pivot: pivot === null ? null : [...pivot] };
+    }
+    case "scale": {
+      // ── A RATIO, NOT A DISTANCE ───────────────────────────────────────
+      //
+      // This used to emit `{kind:"resize", dx: travel.x / screenScale}` with a
+      // corner handle, and that was broken in two ways at once. `dx` is a WORLD
+      // DESIGN vector to everything downstream, so `localizeGesture` rotated a
+      // screen-horizontal number into the layer's own frame: at `rollDeg 90`
+      // the X row mapped to `[0, -d]`, `resizeTransform` computed `dx = 0` and
+      // `dy = 0` because `handle.sy === 0`, `applyToTransform` returned the same
+      // reference, and the whole gesture silently did nothing with no refusal.
+      // Plain `S` on the same layer inverted instead: rightward shrank it.
+      //
+      // A ratio has no vector to rotate, so both are gone, and `axis` now names
+      // the layer's OWN dimension — which is what `size` is measured in.
+      //
+      // EXPONENTIAL IN THE TRAVEL, so the factor is strictly positive at every
+      // input and one screen inch is the same proportion whatever the layer
+      // already is. It is also independent of `screenScale`, which is why a
+      // modal scale is correct even while isolation has swapped an orthographic
+      // rig into the pane the scale was measured against.
+      //
+      // ponytail: Blender measures the ratio as the cursor's distance from the
+      // pivot over the anchor's, which we cannot do without projecting the
+      // pivot every frame — and which is undefined when the anchor lands on it.
+      // Upgrade path is a projected pivot on `ModalLive`, if anyone reports the
+      // feel differing.
+      // A TYPED scale is the factor itself: `S 2` doubles it, which is what
+      // the number means everywhere else in this editor and in Blender.
+      // Quantised to a TENTH, which is what a scale's round numbers are —
+      // 1.5x, 2x — and floored so ctrl can never take a layer to nothing.
+      //
+      // ── THE FLOOR IS FOR THE POINTER, NOT FOR A TYPED NUMBER ──────────
+      //
+      // `Math.max` used to wrap `exact` as well, so `S 0 Enter` and `S -1
+      // Enter` were silently rewritten to 0.1 and the layer shrank to a tenth
+      // of itself instead of being refused. `applyGesture` refuses a
+      // non-positive factor BY NAME — and the clamp meant that refusal could
+      // never fire from the one lane an author can type a number into. Returning
+      // null here refuses in the TABLE too, so the pure half and the plumbing
+      // agree about what is representable, exactly as the axis-less numeric
+      // move does above.
+      if (exact !== null && !(exact > 0)) return null;
+      const ratio = exact ?? Math.max(SNAP_RATIO, quantise(Math.exp(travel.x / SCALE_FALLOFF_PX), SNAP_RATIO));
+      const axis = state.axis === "x" || state.axis === "y" ? state.axis : "both";
+      // Copied out of the readonly tuple the caller holds: `GestureDelta` is
+      // the wire shape the store re-derives from on every capture, and handing
+      // it an alias of the stage's own snapshot would let one mutate the other.
+      return { kind: "scale", dx: 0, dy: 0, ratio, axis, pivot: pivot === null ? null : [...pivot] };
+    }
+  }
+}
+
+/**
+ * The camera mapping — the same deltas the frustum gizmo's two grips emit.
+ * G is the body drag (`planar` on the z = 0 plane; an axis zeroes a
+ * component); S is the apex drag (exponential dzoom at the wheel's own
+ * falloff, so a modal zoom and a wheel notch are the same step).
+ */
+export function framingDeltaFor(
+  state: ModalState,
+  travel: { x: number; y: number },
+  planar: { dx: number; dy: number } | null,
+  dollyFalloffPx: number,
+  exact: number | null = null,
+): FramingDelta | null {
+  if (state.mode === "scale") {
+    // `dzoom` is a MULTIPLIER, so a typed value maps onto it directly — and
+    // must be positive, or `applyFramingDelta` takes the camera's zoom to zero
+    // or negative and `planeDistance` answers a non-finite distance. Refused
+    // rather than clamped, for the reason every refusal in this lane is.
+    if (exact !== null) {
+      return exact > 0 ? { dx: 0, dy: 0, dzoom: exact } : null;
+    }
+    return { dx: 0, dy: 0, dzoom: Math.exp(-travel.y / dollyFalloffPx) };
+  }
+  if (exact !== null) {
+    return {
+      dx: state.axis === "y" ? 0 : exact,
+      dy: state.axis === "x" ? 0 : exact,
+      dzoom: 1,
+    };
+  }
+  if (planar === null) return null;
+  return {
+    dx: state.axis === "y" ? 0 : planar.dx,
+    dy: state.axis === "x" ? 0 : planar.dy,
+    dzoom: 1,
+  };
+}
+
+/**
+ * One character into the numeric buffer, or `null` for a character that cannot
+ * extend it.
+ *
+ * `-` TOGGLES rather than appends, which is Blender's own behaviour and the
+ * only thing that makes it usable mid-number: it flips the sign of whatever is
+ * typed so far, at any point.
+ *
+ * A second `.` is rejected rather than swallowed, so `1.2.3` cannot exist.
+ */
+export function typeNumber(buffer: string, ch: string): string | null {
+  if (ch === "-") return buffer.startsWith("-") ? buffer.slice(1) : `-${buffer}`;
+  if (ch === ".") return buffer.includes(".") ? null : `${buffer}.`;
+  if (ch >= "0" && ch <= "9") return `${buffer}${ch}`;
+  return null;
+}
+
+/**
+ * What the buffer means as a number, or null while it means nothing yet.
+ *
+ * `""`, `"-"` and `"."` are all mid-typing states, not zeros: treating a bare
+ * minus as `-0` would snap the layer to the origin the instant the author
+ * pressed it, before they had typed the value they were negating.
+ */
+export function typedValue(buffer: string): number | null {
+  if (buffer === "" || buffer === "-" || buffer === "." || buffer === "-.") return null;
+  const n = Number(buffer);
+  return Number.isFinite(n) ? n : null;
+}