@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/main.tsx

@@ -13,21 +13,23 @@ import { createRoot } from "react-dom/client";
 import { StageAssetsContext, StudioSurfaceContext } from "@dailies-studio/runtime";
 import type { StageAssetResolver } from "@dailies-studio/runtime";
 // The stage is its OWN document and inherits nothing from the chrome's
-// stylesheet, so it adopts the design tokens by importing them. tokens.css and
-// NOT styles.css: the palette is inert until referenced, while the widget rules
-// and the global box-sizing reset would repaint the author's own content
-// differently here than in the export — which is exactly the preview != runtime
-// split this whole lane refuses.
-import "@dailies-studio/ui/tokens.css";
-// Then THIS LANE's palette on top, because the overlays drawn over the stage
-// read --accent, --guide and --frame-border, and the house values are not the
-// ones the chrome around them is using. Without it the selection quad and the
-// tilt handles paint in the house rose while every control beside them is
-// blue — the overlays were never wrong, they were reading a token nobody had
-// overridden for this document. Same file the chrome imports; one definition.
-import "../shotTokens.css";
-import { createStageClient } from "./bridgeClient.js";
+// stylesheet, so it adopts the design tokens itself: the house file and THIS
+// LANE's palette (the overlays read --accent, --guide, --frame-border), the same
+// two files the chrome imports, one definition. tokens.css and NOT styles.css:
+// the widget rules and the global box-sizing reset would repaint the author's
+// own content differently here than in the export.
+//
+// AS TEXT, rescoped onto the furniture (furnitureTokens.ts says why): imported
+// plainly they would declare every house name on the authored root.
+import houseTokens from "@dailies-studio/ui/tokens.css?raw";
+import laneTokens from "../shotTokens.css?raw";
+import { scopeToFurniture } from "./furnitureTokens.js";
+import { instanceComponentIdsOf, instanceModuleOf } from "@dailies-studio/shot/doc";
+import { createStageClient, reportFatalStage } from "./bridgeClient.js";
+import type { StageClient } from "./bridgeClient.js";
 import { StageApp } from "./StageApp.js";
+import { StageRootBoundary } from "./StageRootBoundary.js";
+import { STAGE_THEME_TOKENS_ID } from "./tokenColor.js";
 
 // WITHOUT THIS PROVIDER, IMAGE AND VIDEO LAYERS ARE BLANK. `useStageAssetResolver`
 // falls back to the bare content-addressed filename, which resolves against
@@ -44,7 +46,19 @@ export function boot(): void {
     return;
   }
   document.documentElement.style.height = "100%";
-  document.body.style.cssText = "margin:0;height:100%;overflow:hidden;background:#000";
+  document.body.style.cssText =
+    "margin:0;height:100%;overflow:hidden;background:var(--dailies-stage-boot-background,#050505)";
+  const tokens = document.createElement("style");
+  tokens.dataset.dailiesStageTokens = "";
+  tokens.textContent = scopeToFurniture(houseTokens) + scopeToFurniture(laneTokens);
+  document.head.appendChild(tokens);
+  // A sibling token probe lets editor-only GL materials resolve the light
+  // palette without putting changing custom properties on authored content.
+  const themeTokens = document.createElement("div");
+  themeTokens.id = STAGE_THEME_TOKENS_ID;
+  themeTokens.dataset.dailiesStageFurniture = "";
+  themeTokens.hidden = true;
+  document.body.appendChild(themeTokens);
   const container = document.createElement("div");
   container.style.cssText = "position:fixed;inset:0";
   document.body.appendChild(container);
@@ -57,6 +71,8 @@ export function boot(): void {
   client.setDisposer(() => {
     root.unmount();
     container.remove();
+    themeTokens.remove();
+    tokens.remove();
     delete window.__shotStudio;
   });
 
@@ -73,10 +89,19 @@ export function boot(): void {
     // frame and no wall clock; anything that reads "no ambient clock" as "a
     // real page" and arms an animation would be animating under the selection
     // handles while a gesture reads live geometry off a moving target.
+    // The boundary wraps StageApp ONLY — the providers stay outside, so a
+    // catch cannot cost them, and the bridge handle was installed before any
+    // render and survives regardless. See StageRootBoundary's header for why
+    // this is not the placement rule's "boundary above the stage".
     root.render(
       <StudioSurfaceContext.Provider value={true}>
         <StageAssetsContext.Provider value={stageAssets}>
-          <StageApp client={client} />
+          <StageRootBoundary
+            report={(m) => reportFatalStage(client, m)}
+            inset={() => client.getState().inset}
+          >
+            <StageApp client={client} />
+          </StageRootBoundary>
         </StageAssetsContext.Provider>
       </StudioSurfaceContext.Provider>,
     );
@@ -84,6 +109,30 @@ export function boot(): void {
   const unsubscribe = client.subscribe(renderOnConnect);
   renderOnConnect();
   forwardShotDocChanged();
+  const hot = typeof import.meta.hot?.on === "function" ? import.meta.hot : null;
+  if (hot !== null) watchHotUpdates(client, hot, (url) => import(/* @vite-ignore */ url), import.meta.env.BASE_URL ?? "/");
+
+  // An uncaught throw in this iframe used to die in ITS console — a surface
+  // the author has no reason to have open. Forwarded through the same lane
+  // every other stage failure takes, so the chrome names it. Listeners, not
+  // containment: the per-instance boundary, ClockDriver's frame containment,
+  // the stage-root boundary above and the panel boundaries own recovery; this
+  // is the last-resort report for whatever they do not cover (an event
+  // handler, an unawaited rejection).
+  // Kept in the stage's health too (bridge v35), which is how an agent that
+  // cannot see the strip hears of it.
+  window.addEventListener("error", (ev) => {
+    // Chromium's ResizeObserver notice is not an error of anything on stage
+    // (it reports a layout loop the browser already broke), so an agent is
+    // not told the stage failed over it.
+    if (!/^ResizeObserver loop/.test(ev.message)) client.recordError("stage", ev.message);
+    client.handlers()?.onError(`stage error: ${ev.message}`);
+  });
+  window.addEventListener("unhandledrejection", (ev) => {
+    const reason = ev.reason instanceof Error ? ev.reason.message : String(ev.reason);
+    client.recordError("stage", `unhandled rejection: ${reason}`);
+    client.handlers()?.onError(`stage rejection: ${reason}`);
+  });
 }
 
 /**
@@ -108,3 +157,54 @@ function forwardShotDocChanged(): void {
     }
   });
 }
+
+/** One module of a Vite `update` payload, as its HMR client imports it. */
+interface HotUpdate {
+  type?: string;
+  path?: string;
+  acceptedPath?: string;
+  timestamp?: number;
+  explicitImportRequired?: boolean;
+}
+
+/**
+ * What code the stage runs, told to its health (bridge v35 `health()`).
+ *
+ * A component edit is a Fast Refresh update here, never a reload: the stage
+ * keeps its document and its load time, and when the new module does not
+ * evaluate, Vite's client only logs it and the stage keeps the previous code.
+ * So each update's placed components are imported again at the URL Vite
+ * imported them at (its module map answers, nothing re-runs): one that
+ * rejects is a component failure in the stage's health, and the update moves
+ * `loadedAt`, which a code change's check waits on. Local only: the hosted
+ * code host serves no HMR and moves the module epoch instead.
+ */
+export function watchHotUpdates(
+  client: StageClient,
+  hot: { on(event: "vite:afterUpdate", listener: (payload: { updates?: HotUpdate[] }) => void): void },
+  importModule: (url: string) => Promise<unknown>,
+  base: string,
+): void {
+  hot.on("vite:afterUpdate", (payload) => {
+    const doc = client.getState().doc;
+    const placed = new Set(doc === null ? [] : instanceComponentIdsOf(doc).map((id) => `/${instanceModuleOf(id)}`));
+    const updates = (payload.updates ?? []).filter(
+      (u) => u.type === "js-update" && typeof u.path === "string" && placed.has(u.path),
+    );
+    void Promise.all(
+      updates.map(async (u): Promise<readonly [string, string | null]> => {
+        const [path = u.path!, query] = (u.acceptedPath ?? u.path!).split("?");
+        const url = `${base}${path.slice(1)}?${u.explicitImportRequired === true ? "import&" : ""}t=${u.timestamp ?? 0}${query === undefined ? "" : `&${query}`}`;
+        try {
+          await importModule(url);
+          return [u.path!, null];
+        } catch (e) {
+          return [
+            u.path!,
+            `instance module ${u.path!.slice(1)} did not hot-update, so the stage still runs its previous code: ${e instanceof Error ? e.message : String(e)}`,
+          ];
+        }
+      }),
+    ).then((checked) => client.noteHotUpdate(new Map(checked)));
+  });
+}

package/src/stage/modalState.ts

@@ -4,7 +4,7 @@
 // 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,
+// what a delta DOES (base write, keyframe, 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 ───────
@@ -35,6 +35,20 @@ export interface ModalState {
    *  deliberately not selectable (see the keymap's starter lane). */
   target: "layers" | "camera";
   axis: ModalAxis;
+  /**
+   * Is the constraint the PLANE normal to `axis`, rather than the axis itself?
+   *
+   * Blender's `⇧X`: "move in everything except x". The one thing a
+   * keyboard-only author could not say in this editor — the drawn gizmo grew
+   * plane pads for it, and this is the same constraint on the keys.
+   *
+   * MOVE ONLY, and `axisRefusal` says so by name for the other two. A rotation
+   * happens about one axis and has no plane; a `size` is a Vec2, so every
+   * "plane" of it is either a single-axis scale (which `S X` already is) or a
+   * uniform one (which bare `S` already is), and a second spelling for a row
+   * that exists is a row that can drift from it.
+   */
+  plane: boolean;
 }
 
 /** Degrees of tilt/roll per CSS pixel dragged. A whole screen width should be
@@ -68,6 +82,40 @@ export const SNAP_PX = 10;
 export const SNAP_DEG = 15;
 export const SNAP_RATIO = 0.1;
 
+/**
+ * The smallest factor a POINTER may ask for, matching `MIN_RATIO` in
+ * interactions/move.ts.
+ *
+ * ── WHY THIS IS NOT `SNAP_RATIO` ────────────────────────────────────────
+ *
+ * It was. One constant did two jobs — the ctrl step AND the floor — and while
+ * the scale was exponential in the travel that was harmless, because reaching
+ * 0.1 took 736px of leftward drag and nobody went further. Measured about the
+ * pivot instead, a cursor halfway to the pivot IS 0.5 and a cursor a tenth of
+ * the way IS 0.1, so the floor started biting in the middle of ordinary
+ * gestures and a selection could not be shrunk past a tenth in one drag.
+ *
+ * Two constants: the step stays a tenth (which is what a scale's round numbers
+ * are), and the floor drops to where it only does the job it is for — keeping
+ * `applyGesture`'s refusal of a non-positive factor from firing on every
+ * pointermove of an overshoot. CTRL still floors at a whole step, so a snap can
+ * never round a layer to nothing.
+ */
+export const MIN_SCALE_RATIO = 1e-3;
+
+/**
+ * Ctrl's quantise, as ONE function.
+ *
+ * The mapping table below had it as a local closure and the pointer lane had
+ * nothing at all, so a drag on an arm and `G X` rounded by different rules —
+ * or rather, one rounded and the other did not. Off by default in the sense
+ * that matters: `snap: false` returns the value byte-identical, so a drag with
+ * no modifier is exactly the drag that shipped.
+ */
+export function snapTo(n: number, step: number, snap: boolean): number {
+  return snap ? Math.round(n / step) * step : n;
+}
+
 export function modalTarget(hasSelection: boolean): ModalState["target"] {
   return hasSelection ? "layers" : "camera";
 }
@@ -81,10 +129,41 @@ export function modalTarget(hasSelection: boolean): ModalState["target"] {
  * 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 {
+export function modalAxisToggle(
+  state: ModalState,
+  axis: "x" | "y" | "z",
+  /** Shift was held: constrain to the PLANE normal to `axis` instead of to the
+   *  axis. Blender's `⇧X`. */
+  plane = false,
+): ModalState {
+  if (plane && state.mode !== "move") return state;
   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 };
+  // ── THE CAMERA'S CELLS, ROW BY ROW, MATCHING `axisRefusal` EXACTLY ──────
+  //
+  // This function is the GATE and `axisRefusal` is only its explanation: the
+  // caller refuses when this returns the state unchanged and then asks that
+  // one for the sentence. So a cell the two disagree about is a key that is
+  // swallowed with an empty pill — the silent-modal failure this file's header
+  // calls the one thing an author cannot debug by looking.
+  //
+  // A ROLL'S Z IS NOT A MISSING CHANNEL. `z` names the view axis, which is the
+  // only axis a framing turns about, so it is accepted and changes nothing —
+  // the same `z`-means-roll spelling the layer arm has.
+  if (state.target === "camera") {
+    if (state.mode === "scale") return state;
+    if (state.mode === "rotate" && (axis === "x" || axis === "y")) return state;
+    if (state.mode === "move" && axis === "z") return state;
+  }
+  // A CAMERA HAS ONE PLANE and it is the one it already moves in, so a plane
+  // lock there is a constraint that constrains nothing — refused rather than
+  // accepted as a label over unchanged behaviour.
+  if (plane && state.target === "camera") return state;
+  // The SAME constraint again clears it; a different one replaces it. Pressing
+  // `X` while `⇧X` is live is a different constraint, so it replaces — which is
+  // Blender's behaviour and the only one that lets an author correct a
+  // mis-pressed shift without leaving the gesture.
+  const same = state.axis === axis && state.plane === plane;
+  return { ...state, axis: same ? null : axis, plane: same ? false : plane };
 }
 
 /**
@@ -98,12 +177,33 @@ export function modalAxisToggle(state: ModalState, axis: "x" | "y" | "z"): Modal
  *
  * Data rather than a thrown string, because the pill renders it.
  */
-export function axisRefusal(state: ModalState, axis: "x" | "y" | "z"): string | null {
+export function axisRefusal(
+  state: ModalState,
+  axis: "x" | "y" | "z",
+  plane = false,
+): string | null {
+  // The PLANE rows first, because they are refused for reasons the axis rows
+  // are not: a rotation happens about one axis and has no plane at all, and a
+  // `size` is a Vec2 whose every plane is a row that already exists.
+  if (plane && state.mode === "rotate") return "A ROTATION HAS NO PLANE";
+  if (plane && state.mode === "scale") return "SIZE HAS NO PLANES · USE X OR Y";
+  if (plane && state.target === "camera") return "A FRAMING IS ALREADY FLAT";
   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";
+  // A CAMERA ROLL TURNS ABOUT THE VIEW AXIS AND NOTHING ELSE. Naming x or y
+  // here is asking to TILT the camera off the design-plane normal, which is the
+  // one thing the whole derived-framing model does not express: every layer's
+  // pixel-exactness at z = 0 is an arithmetic consequence of looking straight
+  // down -z, so a framing that leaned would not be a framing.
+  if (state.target === "camera" && state.mode === "rotate" && (axis === "x" || axis === "y")) {
+    return "A FRAMING ROLLS ABOUT THE VIEW AXIS ONLY";
+  }
+  // MOVE ONLY. `Z` on a camera ROTATE is not a missing channel, it is the roll
+  // axis being named explicitly — the same `z`-means-roll spelling the layer
+  // arm accepts — so it falls through to the accept below.
+  if (state.target === "camera" && state.mode === "move" && axis === "z") return "A FRAMING HAS NO Z";
   return null;
 }
 
@@ -122,7 +222,10 @@ export function axisRefusal(state: ModalState, axis: "x" | "y" | "z"): string |
 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.
+    // A framing delta: the camera's own move, zoom or roll. Roll is asked
+    // first because a roll delta carries `dzoom: 1` and zero travel, so the
+    // move row below would print "0, 0" over a camera that is visibly turning.
+    if (delta.droll !== undefined) return `${round(delta.droll)}°`;
     return delta.dzoom === 1
       ? `${round(delta.dx)}, ${round(delta.dy)}`
       : `×${delta.dzoom.toFixed(2)}`;
@@ -167,9 +270,24 @@ export function initialGestureKind(state: ModalState): GestureKind {
 /** 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()}`;
+  // A PLANE LOCK IS NAMED BY WHAT IT MOVES IN, not by the axis it is normal to
+  // — "MOVE · YZ" is what the author is about to do, and `⇧X` is only how they
+  // asked for it. The gizmo's plane pads name themselves the same way.
+  const axis =
+    state.axis === null
+      ? ""
+      : state.plane
+        ? ` · ${(["x", "y", "z"] as const)
+            .filter((a) => a !== state.axis)
+            .join("")
+            .toUpperCase()}`
+        : ` · ${state.axis.toUpperCase()}`;
   if (state.target === "camera") {
-    return state.mode === "scale" ? "CAMERA ZOOM" : `CAMERA MOVE${axis}`;
+    if (state.mode === "scale") return "CAMERA ZOOM";
+    // No axis suffix: a camera roll is about the view axis and has no other,
+    // which `axisRefusal` says out loud the moment an author asks for one.
+    if (state.mode === "rotate") return "CAMERA ROLL";
+    return `CAMERA MOVE${axis}`;
   }
   switch (state.mode) {
     case "move":
@@ -248,10 +366,32 @@ export function layerGestureFor(
    * rounding what the author literally spelled would be the tool arguing.
    */
   snap = false,
+  /**
+   * What the pointer did ABOUT THE PROJECTED PIVOT, when the stage could
+   * measure it: how far round it has swept, and how far from it the cursor now
+   * sits as a proportion of where the gesture started.
+   *
+   * ── WHY ROTATE AND SCALE STOPPED BEING HORIZONTAL TRAVEL ────────────────
+   *
+   * They were `travel.x * TILT_DEG_PER_PX` and `exp(travel.x / 320)`: the
+   * pointer's ANGULAR position round the selection was ignored entirely, so `R`
+   * did not feel like turning anything and pulling toward or away from the
+   * pivot during `S` did nothing. Blender measures both about the pivot, and
+   * the ponytail note that used to sit on the scale row named exactly this
+   * upgrade and exactly this way of getting it — "a projected pivot on
+   * `ModalLive`".
+   *
+   * Null when there is no pivot on screen to measure about (no working pane, a
+   * selection with no live frame at this playhead, a cursor sitting ON the
+   * projected pivot where the ratio is a division by nothing). The travel rows
+   * are the fallback, so the gesture degrades to its old feel rather than
+   * refusing — a rotation that stops responding is worse than one that responds
+   * the way it did last week.
+   */
+  measured: { sweepDeg: number; ratio: number } | null = null,
 ): 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;
+  const quantise = (n: number, step: number): number => snapTo(n, step, snap && exact === null);
   switch (state.mode) {
     case "move": {
       if (state.axis === "z") {
@@ -275,18 +415,49 @@ export function layerGestureFor(
           dx: state.axis === "y" ? 0 : exact,
           dy: state.axis === "x" ? 0 : exact,
           dz: 0,
+          // A TYPED VALUE IS THE STRONGEST "leave this alone" there is. `G X
+          // 200 Enter` has to land on 200, and a smart guide would move it to
+          // whatever edge happened to be near — silently, and against a number
+          // the author spelled out. Same field, stronger claim than ctrl's.
+          suppressGuides: true,
         };
       }
       if (planar === null) return null;
+      // ── A PLANE LOCK PASSES ALL THREE COMPONENTS ──────────────────────
+      //
+      // …because the CALLER has already done the constraining: the stage
+      // unprojects onto the lock plane itself, so the component along the
+      // locked-out axis is zero by construction rather than by a term here.
+      // Zeroing `dz` as the unconstrained row does would throw away the whole
+      // point of `⇧X` — a move in y and z is exactly a move with a z in it.
+      // CTRL asked for a round number, so the chrome's smart guides step aside
+      // for as long as it is held — see `GestureDelta.suppressGuides`. The same
+      // statement the pointer lane makes, from the lane that quantises the same
+      // way.
+      const rounded = snap && exact === null;
+      if (state.plane) {
+        return {
+          kind: "move",
+          dx: quantise(planar.dx, SNAP_PX),
+          dy: quantise(planar.dy, SNAP_PX),
+          dz: quantise(planar.dz ?? 0, SNAP_PX),
+          suppressGuides: rounded,
+        };
+      }
       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,
+        suppressGuides: rounded,
       };
     }
     case "rotate": {
-      const deg = exact ?? quantise(travel.x * TILT_DEG_PER_PX, SNAP_DEG);
+      // THE ANGLE SWEPT ABOUT THE PIVOT, when there is one to sweep about —
+      // Blender's measure, and the one that makes `R` feel like turning
+      // something. The horizontal-travel row below it is the fallback, for a
+      // pivot that is not on screen to be measured against.
+      const deg = exact ?? quantise(measured?.sweepDeg ?? 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.
@@ -321,17 +492,18 @@ export function layerGestureFor(
       // 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.
+      // THE CURSOR'S DISTANCE FROM THE PIVOT, over where it started —
+      // Blender's own measure, so pulling away grows the selection and pushing
+      // toward it shrinks. `measured` carries it; the stage refuses to measure
+      // when the cursor is ON the projected pivot, where the ratio is a
+      // division by nothing.
+      //
+      // THE FALLBACK IS THE OLD ROW, and it earns its keep: exponential in the
+      // horizontal travel, so the factor is strictly positive at every input,
+      // one screen inch is the same proportion whatever the layer already is,
+      // and it is independent of `screenScale` — which is what kept a modal
+      // scale correct while isolation had an orthographic rig in the pane.
       //
-      // 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 —
@@ -348,7 +520,12 @@ export function layerGestureFor(
       // 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 raw = measured?.ratio ?? Math.exp(travel.x / SCALE_FALLOFF_PX);
+      // Floored at a whole STEP while ctrl is held, so a quantise can never
+      // round a layer to nothing, and at `MIN_SCALE_RATIO` otherwise, so a free
+      // drag can shrink as far as the author drags — see that constant.
+      const floor = snap && exact === null ? SNAP_RATIO : MIN_SCALE_RATIO;
+      const ratio = exact ?? Math.max(floor, quantise(raw, 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
@@ -363,6 +540,11 @@ export function layerGestureFor(
  * 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).
+ *
+ * R has a drawn grip too now: the transform gizmo's `arc:z` on the camera
+ * (`framingArcDelta`). The modal is the keyboard path to the same fourth pose
+ * number, which until either existed could only be reached by typing into the
+ * inspector.
  */
 export function framingDeltaFor(
   state: ModalState,
@@ -370,7 +552,24 @@ export function framingDeltaFor(
   planar: { dx: number; dy: number } | null,
   dollyFalloffPx: number,
   exact: number | null = null,
+  measured?: { sweepDeg: number } | null,
+  snap = false,
 ): FramingDelta | null {
+  if (state.mode === "rotate") {
+    // THE LAYER ROTATE ROW'S OWN MEASURE, deliberately: the angle swept about
+    // the pivot when one is on screen, horizontal travel when it is not. `R`
+    // has to feel like one gesture whether the subject is a layer or the
+    // camera, and two mappings would make the same drag turn two things by
+    // different amounts. Ctrl quantises to the same `SNAP_DEG` for the same
+    // reason, through the shared `snapTo` rather than a second closure.
+    //
+    // Sign is NEGATED against the layer arm. Rolling the CAMERA clockwise
+    // turns the picture counter-clockwise, so sharing the layer's sign would
+    // make the same drag appear to rotate the frame backwards.
+    const raw = measured?.sweepDeg ?? travel.x * TILT_DEG_PER_PX;
+    const deg = exact ?? snapTo(raw, SNAP_DEG, snap && exact === null);
+    return { dx: 0, dy: 0, dzoom: 1, droll: -deg };
+  }
   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

package/src/stage/moduleEpoch.ts

@@ -0,0 +1,60 @@
+// The stage's MODULE EPOCH: which build of the project's modules it imports.
+//
+// Locally nothing ever posts, so the epoch stays null and every URL the stage
+// builds is exactly what the project's Vite serves (instanceModules.ts). The
+// hosted boot script compiles user code in the browser and posts
+// `{ epoch, version }` on this channel after each compile; the stage then
+// re-resolves its instance modules under `?v=<epoch>`, inside the same
+// readiness gates an id-set change already holds (StageApp.tsx
+// `useInstanceModules`).
+//
+// A BroadcastChannel, not the bridge: the epoch is a same-origin fact about
+// the served modules, not chrome-stage protocol, so the bridge and its version
+// constant do not move.
+import { useSyncExternalStore } from "react";
+import { MODULE_EPOCH_CHANNEL, MODULE_EPOCH_MESSAGE_VERSION } from "../hostApi.js";
+
+// The channel and the message version live with the host interface
+// (hostApi.ts), which the boot script bundles without React.
+export { MODULE_EPOCH_CHANNEL, MODULE_EPOCH_MESSAGE_VERSION };
+
+/** Null until the first epoch arrives, which locally is never. */
+export type ModuleEpoch = number | null;
+
+let epoch: ModuleEpoch = null;
+const listeners = new Set<() => void>();
+
+function receive(data: unknown): void {
+  if (data === null || typeof data !== "object") return;
+  const { epoch: next, version } = data as { epoch?: unknown; version?: unknown };
+  if (version !== MODULE_EPOCH_MESSAGE_VERSION) return;
+  if (typeof next !== "number" || !Number.isSafeInteger(next) || next < 0) return;
+  // Forward only: a late or repeated message never rolls the stage back to
+  // modules it has already replaced.
+  if (epoch !== null && next <= epoch) return;
+  epoch = next;
+  for (const listener of listeners) listener();
+}
+
+// Opened when the stage loads, before it can ask for a document, so an epoch
+// posted ahead of the first load is not missed.
+if (typeof BroadcastChannel === "function") {
+  const channel = new BroadcastChannel(MODULE_EPOCH_CHANNEL);
+  channel.onmessage = (event: MessageEvent<unknown>) => receive(event.data);
+  // Node (the test runner) would otherwise keep its process alive for an open
+  // channel. Browsers have no unref.
+  (channel as { unref?: () => void }).unref?.();
+}
+
+export function getModuleEpoch(): ModuleEpoch {
+  return epoch;
+}
+
+export function subscribeModuleEpoch(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useModuleEpoch(): ModuleEpoch {
+  return useSyncExternalStore(subscribeModuleEpoch, getModuleEpoch);
+}