@dailies-studio/shot-editor 0.1.0

package/src/panels/toolbar/ViewModeBar.tsx

@@ -0,0 +1,49 @@
+// Which views the stage shows: working, split, or camera.
+//
+// A FLOATING SIBLING of the stage, never a wrapper. Every panel in this shell
+// is, and the reason is in App.tsx's header: the stage iframe must not remount
+// and no ancestor of it may create a containing block.
+//
+// The three modes are a table for the same reason the tool dock's are — the
+// glyph, the label and the key belong beside the mode they describe, so adding
+// a fourth is one row and forgetting its shortcut is a compile error.
+import { useShotEditor, useStore } from "../../state/context.js";
+import type { StageLayout } from "../../bridgeTypes.js";
+
+const MODES: ReadonlyArray<{
+  mode: StageLayout["mode"];
+  glyph: string;
+  label: string;
+  key: string;
+}> = [
+  // Left to right in the order the digits are, and in the order the panes
+  // themselves sit: the working pane is on the left of a split.
+  { mode: "working", glyph: "◱", label: "Working view", key: "1" },
+  { mode: "split", glyph: "▥", label: "Split", key: "2" },
+  { mode: "camera", glyph: "▣", label: "Camera view", key: "3" },
+];
+
+export function ViewModeBar() {
+  const store = useStore();
+  const layout = useShotEditor((s) => s.stageLayout);
+  const open = useShotEditor((s) => s.name !== null);
+  if (!open) return null;
+  return (
+    <div className="view-mode-bar" role="group" aria-label="View mode" data-testid="view-mode-bar">
+      {MODES.map(({ mode, glyph, label, key }) => (
+        <button
+          key={mode}
+          type="button"
+          className={`tool-button${layout.mode === mode ? " is-armed" : ""}`}
+          aria-pressed={layout.mode === mode}
+          title={`${label} (${key})`}
+          // The RATIO is carried through, not reset: flipping to the camera and
+          // back must return the split the author sized, not a fresh half.
+          onClick={() => store.setStageLayout({ ...layout, mode })}
+        >
+          {glyph}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/shotTokens.css

@@ -0,0 +1,131 @@
+/* The shot lane's palette, and the ONE place it is defined.
+ *
+ * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────
+ *
+ * This lane spans TWO documents: the chrome, and the stage in its iframe.
+ * They are separate CSS worlds, so a palette declared in the chrome's
+ * stylesheet is invisible to the stage — which is how the selection quad, the
+ * tilt handles and the snap guides ended up drawing in the house rose while
+ * every control around them was blue. The overlays were not wrong; they were
+ * reading a token nobody had overridden for them.
+ *
+ * So the palette lives here, both documents import it, and there is exactly
+ * one definition to change. This mirrors the split tokens.css/styles.css
+ * already models in @dailies-studio/ui: the stage takes the PALETTE and none
+ * of the widget rules.
+ *
+ * ── WHY IT OVERRIDES THE HOUSE ACCENT ───────────────────────────────────
+ *
+ * This lane is the Raylight clone, and Raylight's editor is near-black with a
+ * BLUE accent used sparingly: one primary button, the playhead, the armed
+ * tool. The house rose reads as an alert colour, and applied at once to every
+ * toggle, tab, scene bar and selection outline it made the editor look like a
+ * standing error state. The override is scoped to this lane; motion, canvas,
+ * scene and gallery keep the house palette untouched.
+ */
+:root {
+  /* NOT aliased to --font. That token is a `font:` SHORTHAND
+     (`12px/1.45 system-ui, …`), so feeding it to `font-family` is an invalid
+     declaration the browser drops, which lands the whole document on the
+     default serif. Rules that want a family use this; rules that want the
+     whole shorthand use `font: var(--font)`. */
+  --font-ui: system-ui, "Segoe UI", sans-serif;
+
+  /* Surfaces, darkest to lightest. Raylight sits the panels a shade off pure
+     black and the controls a shade above the panels, so a field reads as a
+     recess without needing a border on every side. */
+  --bg: #000000;
+  --panel: #0c0c0e;
+  --panel-raised: #141417;
+  --control: #1b1b1f;
+  --control-hover: #26262c;
+  --input-bg: #1b1b1f;
+
+  --border: #232328;
+  --border-soft: #1a1a1e;
+  --text: #f2f2f5;
+  --text-dim: #8e8e97;
+  --text-faint: #5d5d66;
+
+  --accent: #0a84ff;
+  --accent-hover: #3d9dff;
+  --accent-soft: rgba(10, 132, 255, 0.16);
+  --accent-quiet: rgba(10, 132, 255, 0.12);
+  --accent-warm: #f5a524;
+  --danger: #ff4d4f;
+  --danger-text: #ff8a8c;
+  --warn: #f5a524;
+
+  /* The stage's own vocabulary. All three were undefined, so the overlays ran
+     on their hardcoded fallbacks: red guides and a grey frame border that
+     read as a stray rectangle rather than as the exportable edge.
+
+     A SNAP GUIDE IS DELIBERATELY NOT THE ACCENT. It appears while a drag is
+     in flight, on top of a selection already drawn in accent, and two
+     identical colours mean the author cannot tell the thing they are moving
+     from the thing they are aligning to. */
+  --guide: #f5a524;
+  --frame-border: rgba(255, 255, 255, 0.22);
+  --marquee: var(--accent);
+
+  /* The shot camera drawn as an object in the working pane, and the badge that
+     says the camera is following that pane. A YELLOW, which is the one hue this
+     lane's palette does not already spend: the accent is the selection, the
+     guide amber is a live snap, and a camera gizmo drawn in either would read
+     as "you have selected this" or "this is snapping". Both documents need it —
+     the gizmo is a GL material in the stage, the badge is SVG in the same
+     document — so it lives here with the rest of the palette. */
+  --frustum: #eab308;
+
+  /* The working pane's placement aids: the ground grid, and the three DESIGN
+     axes shared by the drag gizmo and the corner nav ball.
+
+     RED / GREEN / BLUE FOR X / Y / Z is the one convention in this whole
+     palette that is not ours to pick. Every 3D tool an author has used draws
+     the axes this way, and a lane-consistent hue would cost them the one
+     thing the gizmo exists to say at a glance. They are needed in both halves —
+     GL materials in the stage, SVG in the same document — so they live here.
+
+     The grid is nearly the panel colour on purpose: it is furniture under a
+     picture being judged, and a bright floor competes with the shot. */
+  --grid: #2a2a31;
+  --axis-x: #ef4444;
+  --axis-y: #22c55e;
+  --axis-z: #3b82f6;
+
+  /* The seam between the two stage panes. Deliberately `--border` and not the
+     accent: it is furniture, drawn over a picture the author is judging, and
+     the moment it is bright it competes with the shot. Defined here rather than
+     in the chrome's stylesheet because the SVG that draws it lives in the STAGE
+     document, which inherits nothing from the chrome. */
+  --stage-divider: var(--border);
+
+  /* The timeline vocabulary. Raylight draws a block as a DARK FILL WITH A
+     BRIGHT BORDER rather than a solid bar, which keeps forty overlapping
+     blocks legible instead of a wall of colour and gives every lane its own
+     hue. One hue per lane defines both halves. */
+  --block-in: #38bdf8;
+  --block-during: #a78bfa;
+  --block-out: #f472b6;
+  --scene-bar: #34d399;
+  --playhead: var(--accent);
+
+  /* The audio lane. A distinct hue from every block slot AND from the scene
+     bar, because the whole point of putting the score under the video is that
+     the author can find it without reading a label: an audio clip that shared
+     the During purple would read as one more animation block. Teal is the one
+     band left between the scene green and the In blue. */
+  --audio-clip: #2dd4bf;
+  /* The gain rubber band and the fade ramps, which are drawn ON the clip and
+     must stay readable over the waveform under them. */
+  --audio-line: #fef08a;
+
+  /* The marker strip: an ORANGE band carrying WHITE diamonds, which is the
+     reference editor's own pairing and is not arbitrary. A marker is a note
+     rather than a thing on screen, so it must not read as one more bar in the
+     block vocabulary — orange is the one hue no lane above it uses, and a white
+     diamond on it is legible at the 8px the strip is drawn at, where a hue-on-
+     hue fill is a smudge. `MarkerRef.color` overrides the diamond only. */
+  --marker: #f97316;
+  --marker-pin: #ffffff;
+}

package/src/stage/FrustumGizmo.tsx

@@ -0,0 +1,184 @@
+// The shot camera, drawn in the working pane as the object it is.
+//
+// ── EDITOR-ONLY, BY CONSTRUCTION AND NOT BY CONVENTION ──────────────────
+//
+// Three separate things keep this out of the picture the author is judging, and
+// each of them fails safe on its own:
+//
+//   1. `layers.set(EDITOR_LAYER)` — bit 1 ONLY. The shot camera's mask is bit 0,
+//      so it cannot see this object at all; the working camera enables bit 1.
+//   2. `SplitRenderer` pins its post pass to `new Layers()` (bit 0), so even a
+//      camera that somehow enabled bit 1 could not get the gizmo into the
+//      graded image.
+//   3. It carries no `SHOT_LAYER_KEY` userData, so `collectFrames` never sees
+//      it and layer picking cannot return it.
+//
+// It also touches no document. Everything it draws is a pure function of the
+// resolved rig, which is a pure function of (document, frame).
+//
+// ── WHY THE MATERIAL REFUSES THE OVERRIDE ───────────────────────────────
+//
+// The working pane renders with `scene.overrideMaterial = clay`. three applies
+// an override to every material whose `allowOverride` is true — three's own
+// Background sets it false for exactly this reason — so without that flag the
+// gizmo would come out clay grey, which is the one colour it must not be.
+//
+// ── AND WHY THE COLOUR IS READ FROM CSS ─────────────────────────────────
+//
+// It is a MATERIAL colour, not a GL clear colour, and it is resolved once at
+// mount inside the stage document — which imports shotTokens.css. So `--frustum`
+// stays the single definition both documents share, and the overlay could draw
+// the same yellow tomorrow without a second literal. (SplitRenderer's clay is
+// hard-coded for the opposite reason: a clear colour is written before any
+// style has resolved.)
+import { useEffect, useMemo } from "react";
+import { useFrame } from "@react-three/fiber";
+import {
+  BufferAttribute,
+  BufferGeometry,
+  LineSegments,
+  Vector3,
+} from "three";
+import { LineBasicNodeMaterial } from "three/webgpu";
+import { EDITOR_LAYER } from "./StageTools.js";
+import { tokenColor } from "./tokenColor.js";
+import {
+  FRUSTUM_SEGMENT_FLOATS,
+  borderDistance,
+  frustumSegments,
+  frustumShape,
+  segmentsMoved,
+} from "./frustumGeometry.js";
+import type { CameraRig } from "./frustumGeometry.js";
+import { toScreen } from "./project.js";
+import type { StageFeed } from "./feed.js";
+import type { PaneRect } from "./panes.js";
+import type { FrameSize } from "./view.js";
+
+/** How close a press has to land to the apex to grab it, in CSS px. Larger
+ *  than the layer handles' 10: the apex is a single point with no box around
+ *  it, and it is the only way to reach the zoom. */
+export const APEX_GRAB_PX = 14;
+
+/** How close a press has to land to the base rectangle's DRAWN border to grab
+ *  the body. The interior is deliberately not a grab target — see
+ *  `borderDistance` for why an interior claim takes the whole pane away — so
+ *  the border is a line, and it gets the same slop the apex point does. */
+const BODY_GRAB_PX = 14;
+
+/** Over everything. Every material in this lane draws with `depthTest: false`,
+ *  so paint order is `renderOrder` alone (ShotRuntime's header) — a gizmo that
+ *  shared the layers' range would be hidden by whichever layer sorted after it. */
+const FRUSTUM_RENDER_ORDER = 1_000_000;
+
+const FRUSTUM_FALLBACK = "#eab308";
+
+/** Scratch for the border test's behind-camera check. */
+const _view = new Vector3();
+
+export interface FrustumGizmoProps {
+  feed: StageFeed;
+  panes: { working: PaneRect | null; camera: PaneRect | null };
+  /** The camera as resolved at the playhead. Null when no scene is on screen. */
+  rig: CameraRig | null;
+  frame: FrameSize;
+}
+
+export function FrustumGizmo({ feed, panes, rig, frame }: FrustumGizmoProps) {
+  const gizmo = useMemo(() => {
+    const geometry = new BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new BufferAttribute(new Float32Array(FRUSTUM_SEGMENT_FLOATS), 3),
+    );
+    const material = new LineBasicNodeMaterial();
+    material.color.copy(tokenColor("--frustum", FRUSTUM_FALLBACK));
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.toneMapped = false;
+    // See the header: the working pane renders under a clay override.
+    material.allowOverride = false;
+
+    const lines = new LineSegments(geometry, material);
+    lines.layers.set(EDITOR_LAYER);
+    lines.renderOrder = FRUSTUM_RENDER_ORDER;
+    // The vertices are WORLD positions rewritten in place, so the object stays
+    // at the origin and the bounding sphere the culler would test is never the
+    // one the buffer holds. Culling it against a stale sphere makes the gizmo
+    // vanish at some orbits and not others.
+    lines.frustumCulled = false;
+    lines.matrixAutoUpdate = false;
+    return { lines, geometry, material, apex: new Vector3(), quad: newQuad() };
+  }, []);
+
+  useEffect(
+    () => () => {
+      gizmo.geometry.dispose();
+      gizmo.material.dispose();
+    },
+    [gizmo],
+  );
+
+  useFrame(() => {
+    const working = panes.working;
+    if (rig === null) {
+      gizmo.lines.visible = false;
+      feed.frustumHit = null;
+      return;
+    }
+    gizmo.lines.visible = true;
+
+    const shape = frustumShape(rig, frame);
+    const next = frustumSegments(shape);
+    const attribute = gizmo.geometry.getAttribute("position") as BufferAttribute;
+    const buffer = attribute.array as Float32Array;
+    // The 0.5px gate `quadMoved` uses, for the same reason: this runs on every
+    // committed frame, and a parked playhead must not re-upload a buffer.
+    if (segmentsMoved(buffer, next)) {
+      buffer.set(next);
+      attribute.needsUpdate = true;
+    }
+
+    // The hit-test geometry follows every frame regardless of that gate: half a
+    // pixel of drift is invisible in the drawing and is still the difference
+    // between grabbing the apex and missing it.
+    gizmo.apex.set(shape.apex[0], shape.apex[1], shape.apex[2]);
+    for (let i = 0; i < 4; i++) {
+      gizmo.quad[i]!.set(shape.corners[i]![0], shape.corners[i]![1], shape.corners[i]![2]);
+    }
+
+    feed.frustumHit = (x, y) => {
+      const camera = feed.workingCamera;
+      if (camera === null || working === null) return null;
+      // THE APEX FIRST, and in SCREEN px: it is a point, so a world-space
+      // radius would be a grab target that shrinks as the author dollies out
+      // until it cannot be hit at all.
+      const [ax, ay] = toScreen(gizmo.apex, camera, working.width, working.height);
+      if (Math.hypot(ax - x, ay - y) <= APEX_GRAB_PX) return "apex";
+      // THE BODY BY ITS BORDER, in SCREEN px like the apex and for the same
+      // reason. A corner behind the working camera projects to garbage, so a
+      // quad that is not wholly in front answers null — its border is not on
+      // screen to be grabbed, and the press falls through to the orbit.
+      const corners: [number, number][] = [];
+      for (const corner of gizmo.quad) {
+        _view.copy(corner).applyMatrix4(camera.matrixWorldInverse);
+        if (_view.z >= 0) return null;
+        corners.push(toScreen(corner, camera, working.width, working.height));
+      }
+      return borderDistance(x, y, corners) <= BODY_GRAB_PX ? "body" : null;
+    };
+  }, 0);
+
+  useEffect(
+    () => () => {
+      feed.frustumHit = null;
+    },
+    [feed],
+  );
+
+  return <primitive object={gizmo.lines} />;
+}
+
+function newQuad(): [Vector3, Vector3, Vector3, Vector3] {
+  return [new Vector3(), new Vector3(), new Vector3(), new Vector3()];
+}

package/src/stage/GridPlane.tsx

@@ -0,0 +1,274 @@
+// The working pane's ground plane.
+//
+// Editor-only by exactly the three constructions FrustumGizmo's header states —
+// `layers.set(EDITOR_LAYER)`, SplitRenderer's post pass pinned to bit 0, and no
+// `SHOT_LAYER_KEY` userData — so it cannot reach the graded image, the camera
+// pane or a pick. It reads no document and writes nothing.
+//
+// ── WHY IT SITS UNDER THE FRAME AND NOT THROUGH THE ORIGIN ──────────────
+//
+// Blender's grid is at the world origin, and here that origin is the CENTRE OF
+// THE CANVAS — the one place the artwork always is. A grid there slices every
+// shot in half with a bright horizontal line and reads as a mistake.
+//
+// So the floor is at the frame's BOTTOM EDGE (design y = +height/2, which the
+// one mapping makes world y = -height/2), and the canvas stands on it. That
+// gives the pane the thing an orbit view is missing — a horizon and a sense of
+// which way is down — without drawing anything across the picture.
+//
+// ── WHY IT IS OPAQUE AND NOT A DIMMED TRANSPARENT ───────────────────────
+//
+// Every material in this lane draws with `depthTest: false`, so paint order is
+// `renderOrder` alone (ShotRuntime's header) — and three sorts the TRANSPARENT
+// list after the whole opaque one, whatever their render orders say. A
+// translucent grid would therefore draw ON TOP of an opaque mesh layer,
+// however negative its order. Opaque and dim is the same look with none of
+// that: it lands first in the opaque list and everything else covers it.
+//
+// It is also why the fade below mixes towards the BACKDROP COLOUR rather than
+// towards alpha, which is the usual way to end an infinite grid.
+//
+// ── AND WHY IT ENDS IN A FADE RATHER THAN AT AN EDGE ────────────────────
+//
+// A ground plane is not bounded by what the camera can see: look along it and
+// it runs to a horizon. So a patch sized against the visible height is a patch
+// the author finds the end of the moment they orbit low, which is what 24
+// cells did. `GRID_CELLS` now outreaches the fade at every legal dolly
+// (`gridExtent` vs `gridFade`, swept in `gizmoMath.test.ts`), and the lines
+// dissolve into the backdrop before the geometry runs out — so what the pane
+// shows is a horizon, and the edge is unreachable rather than merely far.
+//
+// ── AND WHY THE AXES LIE IN IT RATHER THAN AT THE ORIGIN ────────────────
+//
+// Blender's axes lie in its grid because its origin is ON the ground. Ours is
+// not: the world origin is the canvas CENTRE, half a frame height above the
+// floor. Axes drawn there put a red and a blue line in mid-air over the floor
+// with nothing relating the two aids, which reads as a bug rather than as a
+// pair of placement aids.
+//
+// So all three cross at the point the canvas STANDS on — (0, floor, 0) —
+// which is the same reading Blender gives. Each line is still infinite along
+// its own direction and still marks its own zero on the other two components;
+// only the shared crossing moved. They draw one render order ABOVE the floor
+// so they cross the gridlines rather than fight them, and still a million
+// below every layer, so the artwork covers both.
+import { useEffect, useMemo } from "react";
+import { BufferAttribute, BufferGeometry, LineSegments } from "three";
+import { LineBasicNodeMaterial } from "three/webgpu";
+import { cameraPosition, color, length, mix, positionWorld, smoothstep, uniform } from "three/tsl";
+import { EDITOR_LAYER } from "./StageTools.js";
+import { CLAY_BACKDROP } from "./SplitRenderer.js";
+import { WORKING_FOV_DEG } from "./workingView.js";
+import { GRID_CELLS, axisOrigin, axisPositions, gridFade, gridPositions, gridStep } from "./gizmoMath.js";
+import { tokenColor } from "./tokenColor.js";
+import type { FrameSize } from "./view.js";
+
+/** Behind everything. The mirror of the frustum's +1_000_000, for the reason
+ *  its own comment gives: with depth testing off, order is the only answer to
+ *  "what covers what". */
+const GRID_RENDER_ORDER = -1_000_000;
+
+/** One above the floor and still a million below the artwork: the axes cross
+ *  the grid lines rather than fighting them, and any layer covers both. */
+const AXIS_RENDER_ORDER = GRID_RENDER_ORDER + 1;
+
+/**
+ * Half-length of each world axis.
+ *
+ * Longer than any legal camera can see (the dolly band tops out around 42k
+ * design px of distance for a 1080-tall shot) and the segment RECENTRES along
+ * its own direction with the floor, so no pan finds an end either. Translating
+ * a line along itself is the identity on the infinite line, which is why this
+ * needs no snap quantum the way the grid does.
+ */
+const AXIS_EXTENT = 100_000;
+
+const GRID_FALLBACK = "#2a2a31";
+
+/** World axis index -> token. The one mapping (`world = (x, -y, -z)`) is a sign
+ *  flip, and a line through the origin is invariant under it, so the world axes
+ *  ARE the design axes here and these are the nav gizmo's own colours. */
+const AXES = [
+  { axis: 0 as const, token: "--axis-x", fallback: "#ef4444" },
+  { axis: 1 as const, token: "--axis-y", fallback: "#22c55e" },
+  { axis: 2 as const, token: "--axis-z", fallback: "#3b82f6" },
+];
+
+export function GridPlane({
+  frame,
+  target,
+  distance,
+}: {
+  frame: FrameSize;
+  target: readonly [number, number, number];
+  /** The working camera's eye-to-target distance. Drives the spacing through
+   *  `gridStep`'s ladder, so a dolly changes the geometry in jumps, and the
+   *  fade band continuously, which is a uniform write and no rebuild. */
+  distance: number;
+}) {
+  const step = gridStep(frame.height, distance, WORKING_FOV_DEG);
+  const height = -frame.height / 2;
+
+  const grid = useMemo(() => {
+    const geometry = new BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new BufferAttribute(new Float32Array(gridPositions(step, GRID_CELLS, height)), 3),
+    );
+    const material = new LineBasicNodeMaterial();
+    // ── THE FADE, AND WHY IT IS A COLOUR AND NOT AN ALPHA ─────────────────
+    //
+    // The obvious infinite grid fades its lines to transparent. This lane
+    // cannot: three sorts the whole TRANSPARENT list after the whole opaque
+    // one whatever their render orders say (see the header), so the moment
+    // this material turns transparent the floor draws OVER every opaque mesh
+    // layer in its bin instead of a million orders below them.
+    //
+    // Mixing towards the backdrop COLOUR is the same picture with none of
+    // that. At the far end the line is exactly the pane's clear colour, which
+    // is invisible without ever leaving the opaque list.
+    //
+    // The one place it is approximate is `rendered` shading, where the pane
+    // clears with the SHOT's background rather than the clay. The grid
+    // already draws over that background at full strength today, so a fade
+    // towards clay there is a softer version of what is drawn now, not a new
+    // disagreement.
+    const fadeStart = uniform(0);
+    const fadeEnd = uniform(1);
+    material.colorNode = mix(
+      color(tokenColor("--grid", GRID_FALLBACK)),
+      color(CLAY_BACKDROP),
+      smoothstep(fadeStart, fadeEnd, length(positionWorld.sub(cameraPosition))),
+    );
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.toneMapped = false;
+    // The working pane renders under a clay override in solid/wireframe mode;
+    // without this the grid comes out the same grey as the layers.
+    material.allowOverride = false;
+
+    const lines = new LineSegments(geometry, material);
+    lines.layers.set(EDITOR_LAYER);
+    lines.renderOrder = GRID_RENDER_ORDER;
+    // The vertices are WORLD positions, so the object stays at the origin and
+    // its bounding sphere is not the one the buffer holds — culling against a
+    // stale sphere makes the grid vanish at some orbits and not others.
+    lines.frustumCulled = false;
+    lines.matrixAutoUpdate = false;
+    return { lines, geometry, material, fadeStart, fadeEnd };
+    // Rebuilt when the shot's size changes (a document switch or a resolution
+    // edit) or when the dolly crosses a ladder rung — never within a rung, so a
+    // continuous dolly does no geometry work. The buffer stays static and the
+    // OBJECT moves; see the follow effect below.
+  }, [step, height]);
+
+  // The three world axes. Built ONCE — their geometry has nothing to do with
+  // the grid's spacing, and their extent is already past every legal view.
+  //
+  // Three objects with three materials rather than one buffer with vertex
+  // colours: `MoveGizmo` states the same choice for the same reason, that a
+  // node material's colour is a uniform and per-vertex colour on this stack
+  // costs a node graph the arms do not need. Three tiny draws is the cheaper
+  // half of that trade.
+  const axes = useMemo(
+    () =>
+      AXES.map(({ axis, token, fallback }) => {
+        const geometry = new BufferGeometry();
+        geometry.setAttribute(
+          "position",
+          new BufferAttribute(new Float32Array(axisPositions(axis, AXIS_EXTENT)), 3),
+        );
+        const material = new LineBasicNodeMaterial();
+        material.color.copy(tokenColor(token, fallback));
+        material.depthTest = false;
+        material.depthWrite = false;
+        material.toneMapped = false;
+        // Escapes the clay/wire override, like the grid and the gizmo arms.
+        material.allowOverride = false;
+
+        const lines = new LineSegments(geometry, material);
+        lines.layers.set(EDITOR_LAYER);
+        lines.renderOrder = AXIS_RENDER_ORDER;
+        lines.frustumCulled = false;
+        lines.matrixAutoUpdate = false;
+        return { axis, lines, geometry, material };
+      }),
+    [],
+  );
+
+  // ── THE GRID FOLLOWS THE AUTHOR ─────────────────────────────────────────
+  //
+  // It was 24 cells nailed to the world origin, so panning far enough left it
+  // behind entirely and the pane lost its floor — the one thing an orbit view
+  // has to say which way is down. Blender's grid is infinite; ours moves.
+  //
+  // SNAPPED TO A WHOLE CELL, which is what makes a moving grid read as a fixed
+  // one: the lines land on the same design coordinates whatever the target is,
+  // so nothing appears to slide underneath the artwork. Only x and z, because
+  // the floor's height is the frame's own bottom edge and must not drift.
+  //
+  // The MATRIX moves, not the buffer. `matrixAutoUpdate` is off, so this is one
+  // matrix write on the frames where the target actually crossed a cell.
+  useEffect(() => {
+    const snap = (n: number): number => Math.round(n / step) * step;
+    grid.lines.position.set(snap(target[0]), 0, snap(target[2]));
+    grid.lines.updateMatrix();
+  }, [grid, step, target]);
+
+  // ── AND THE FADE FOLLOWS THE DOLLY ──────────────────────────────────────
+  //
+  // Two uniform writes, not a rebuild: the fade band is CONTINUOUS in the
+  // distance while the spacing is quantised to a ladder rung, so this runs on
+  // every dolly frame and the geometry memo above still runs on almost none.
+  useEffect(() => {
+    const [start, end] = gridFade(frame.height, distance, WORKING_FOV_DEG);
+    grid.fadeStart.value = start;
+    grid.fadeEnd.value = end;
+  }, [grid, frame.height, distance]);
+
+  // ── AND SO DO THE AXES, ALONG THEMSELVES ────────────────────────────────
+  //
+  // Each axis follows the target on its OWN component only. That is an exact
+  // identity on the infinite line the segment stands for — the drawn set of
+  // points does not move at all — so it needs no snapping and can never appear
+  // to slide. What it buys is that the finite segment stays centred on the
+  // author, so no pan, however far, reaches an end.
+  //
+  // The OTHER components are the placement above: the floor's height for the
+  // two horizontal axes, zero for the vertical one, which crosses the floor at
+  // that same point without being told to.
+  useEffect(() => {
+    for (const a of axes) {
+      const [x, y, z] = axisOrigin(a.axis, target, height);
+      a.lines.position.set(x, y, z);
+      a.lines.updateMatrix();
+    }
+  }, [axes, target, height]);
+
+  useEffect(
+    () => () => {
+      grid.geometry.dispose();
+      grid.material.dispose();
+    },
+    [grid],
+  );
+
+  useEffect(
+    () => () => {
+      for (const a of axes) {
+        a.geometry.dispose();
+        a.material.dispose();
+      }
+    },
+    [axes],
+  );
+
+  return (
+    <>
+      <primitive object={grid.lines} />
+      {axes.map((a) => (
+        <primitive key={a.axis} object={a.lines} />
+      ))}
+    </>
+  );
+}