@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/TransformGizmo.tsx

@@ -0,0 +1,696 @@
+// The transform gizmo in the working pane, on whatever the author is moving.
+//
+// ── ONE GIZMO, TWO SUBJECTS, AND THE FORK IS `modalTarget` ──────────────
+//
+// With a selection it hangs on the selection's centre and moves layers. With
+// NOTHING selected it hangs on the shot camera's apex and moves the camera —
+// which is not a second feature bolted on, it is the SAME rule `G` and `S`
+// already follow (modalState.ts: "layers when the selection is non-empty, else
+// the CAMERA's framing"). Importing `modalTarget` rather than restating it is
+// what keeps the drawn gizmo and the keyboard from ever disagreeing about whose
+// transform the author is about to change.
+//
+// The camera's arms mean something slightly different, and `framingArmDelta`
+// owns that: it has no free z, so its Z arm is the DOLLY. See that function.
+//
+// ── THE HANDLES, AND WHY THE CAMERA GETS FEWER ──────────────────────────
+//
+// Layers get three ARROWS (one design axis each), three PLANE PADS (two axes at
+// once) and a view-plane DISC at the centre. The camera gets the arrows and ONE
+// arc, and that is honesty rather than economy: a `Framing` is (x, y, zoom,
+// roll) with no free z, so the xz and yz pads would be pads for a motion it
+// cannot perform, and the xy pad would be an exact duplicate of the camera
+// body's own drag that already pans it. The arms start clear of the body's
+// grab box — see `GIZMO_PX.armStart` — and they outrank it in the pointer
+// lane, so both stay reachable.
+//
+// Layers also get three ROTATE ARCS, one per design axis, which is every
+// rotation the document model HAS: `arc:z` is `rollDeg` (and takes the
+// selection's median as its pivot, the way the camera pane's ring already
+// does), `arc:x` and `arc:y` are the two `tilt` channels (which are pivot-free,
+// because `applyGesture` can only orbit a pivot in the design z plane). There
+// is no fourth arc because there is no fourth channel. The camera keeps `arc:z`
+// alone: a roll is the one rotation its framing has, and the arc is the grip
+// the drawn camera never had for it (the `R` modal is the keyboard path).
+//
+// ── AND WHY THERE ARE NO SCALE HANDLES ──────────────────────────────────
+//
+// Because there already are. A selection quad in this pane draws the same
+// eight resize handles the camera pane does (Overlays' `SelectionQuad`), and a
+// multi-select draws the union box, whose corner IS a uniform scale about the
+// opposite corner (`unionScale`). Cubes on these arms would be a third way to
+// write `size`, competing for the same pixels as the arrowheads. `S` and its
+// axis constraints remain the keyboard path.
+//
+// ── WHY AN ARM DRAG SOLVES A LINE AND A PAD SOLVES A PLANE ──────────────
+//
+// An arm the author has grabbed must stay under the cursor, and only the
+// closest-approach solve between the axis line and the pointer ray does that
+// (`axisParam`). Unprojecting onto a plane and zeroing two components — what
+// the modal lane does, because it has no drawn arm to stay under — drifts away
+// from the pointer as the view turns and runs away entirely at a grazing angle.
+// A PAD has no line to stay on: the grabbed point stays under the cursor
+// exactly when both rays are unprojected onto the pad's own plane, which is
+// `designDelta`, the same solve a layer body drag uses.
+//
+// ── EDITOR-ONLY, THE SAME THREE WAYS THE FRUSTUM IS ─────────────────────
+//
+// `layers.set(EDITOR_LAYER)`, SplitRenderer's post pass pinned to bit 0, and no
+// `SHOT_LAYER_KEY` userData. It also writes no document: the DRAG does, through
+// the same `onGestureStart`/`onGesture`/`onGestureEnd` scrub every other
+// transform opens.
+//
+// ── AND WHY IT IS MESHES AND NOT LINES ──────────────────────────────────
+//
+// `LineSegments` has no line width on either backend, so the arms were 1px
+// hairlines with a 14px invisible grab slop around them: the affordance was
+// four times thinner than its own hit area, and nothing said which end of an
+// axis was positive. Cylinders and cones are `MeshBasicNodeMaterial`, which is
+// a node material like everything else in this lane and therefore correct on
+// the WebGPU backend as well as the WebGL2 one this stage pins.
+import { useEffect, useMemo } from "react";
+import { useFrame } from "@react-three/fiber";
+import {
+  BufferAttribute,
+  BufferGeometry as ThreeBufferGeometry,
+  CircleGeometry,
+  ConeGeometry,
+  CylinderGeometry,
+  Line,
+  Matrix4,
+  Mesh,
+  PlaneGeometry,
+  Quaternion,
+  Vector3,
+} from "three";
+import type { BufferGeometry, Camera, Object3D } from "three";
+import { LineBasicNodeMaterial, MeshBasicNodeMaterial } from "three/webgpu";
+import { EDITOR_LAYER } from "./StageTools.js";
+import {
+  ARC_SEGMENTS,
+  DESIGN_AXES,
+  GIZMO_PX,
+  MIN_ARM_SCREEN_PX,
+  MIN_PAD_SCREEN_AREA,
+  alongAxis,
+  arcPoints,
+  armGrabbable,
+  gizmoAxisOf,
+  gizmoHitAt,
+  padAxes,
+  padCentre,
+  padCorners,
+  screenArea,
+} from "./gizmoMath.js";
+import type { DesignAxis, GizmoHandleId, GizmoTarget, Vec3 } from "./gizmoMath.js";
+import { modalTarget } from "./modalState.js";
+import { toScreen, worldPerPixel } from "./project.js";
+import { tokenColor } from "./tokenColor.js";
+import type { StageTheme } from "./stageTheme.js";
+import type { StageFeed } from "./feed.js";
+import type { PaneRect } from "./panes.js";
+
+/** Over everything, and over the frustum too: a handle that a camera gizmo
+ *  could hide is a handle the author cannot grab. */
+const GIZMO_RENDER_ORDER = 2_000_000;
+
+const AXIS_FALLBACK: Readonly<Record<DesignAxis, string>> = {
+  x: "#ef4444",
+  y: "#22c55e",
+  z: "#3b82f6",
+};
+
+/** How far a hovered handle blends towards the theme's contrast ink. Enough to
+ *  read as hot at a glance, little enough that red / green / blue still name
+ *  the axis. */
+const HOVER_TINT = 0.45;
+
+/**
+ * What a handle that cannot answer a press is drawn at.
+ *
+ * `armGrabbable` has always had the answer and only the HIT TEST asked it, so
+ * a foreshortened arm — the design y at Numpad7, the design z under isolation's
+ * orthographic rig — was painted at full strength and then silently ignored
+ * every press. Hiding it would lie about the geometry; dimming it does not. The
+ * axis is still there and still that colour, it just stops claiming to be a
+ * handle.
+ *
+ * The same value dims every OTHER handle while one is being dragged, which is
+ * the same statement about the same thing: those cannot be grabbed either while
+ * a scrub is open.
+ */
+const DEAD_OPACITY = 0.3;
+
+/** A pad's fill is a wash, not a solid: it sits over the geometry the author is
+ *  placing, and a solid quad there hides exactly what they are aiming at. */
+const PAD_OPACITY = 0.45;
+
+/** The view-plane disc is the quietest handle on the widget — it does the least
+ *  constrained thing, so it makes the least visual claim. */
+const DISC_OPACITY = 0.32;
+
+/** An arc is a hairline (line width has no setting on either backend), so it
+ *  sits closer to full strength than the filled handles do or it would read as
+ *  already dimmed. */
+const ARC_OPACITY = 0.8;
+
+/** three's cylinder and cone are authored along +y, so an arm's orientation is
+ *  one `setFromUnitVectors` off this. (A pad's is NOT — it needs an explicit
+ *  basis, see where it is built.) */
+const UP = new Vector3(0, 1, 0);
+const _origin = new Vector3();
+const _point = new Vector3();
+const _view = new Vector3();
+
+/** Is a world point behind the camera's own plane? View-space z runs NEGATIVE
+ *  in front, so anything at or past zero has no honest projection. */
+function behind(point: Vector3, camera: Camera): boolean {
+  return _view.copy(point).applyMatrix4(camera.matrixWorldInverse).z >= 0;
+}
+
+export interface TransformGizmoProps {
+  /** Resolved editor theme. It rebuilds only token-backed GL materials. */
+  theme: StageTheme;
+  feed: StageFeed;
+  panes: { working: PaneRect | null; camera: PaneRect | null };
+  selection: readonly string[];
+  /** The shot camera's own position at this frame, or null when no scene is on
+   *  screen. Passed in rather than read off the feed: `FrustumGizmo` writes its
+   *  own copy at priority 0 too, and two priority-0 subscribers have no defined
+   *  order — so this comes from `rig`, which `StageApp` already memoizes. */
+  /** Where the camera IS at the clock's frame, read at FRAME time (StageApp's
+   *  `playhead`): the arms hang on it when nothing is selected. */
+  cameraApexAt: () => Vec3 | null;
+}
+
+/**
+ * One drawable piece of the widget: an object, the handle it belongs to, and
+ * the cached appearance so the frame loop can skip writes that change nothing.
+ *
+ * `base` is the handle's own colour at rest, and `restAlpha` its own opacity at
+ * rest — a pad and an arrow on the same axis are the same hue and deliberately
+ * not the same weight.
+ *
+ * `kind` is carried rather than sniffed off the geometry's `type`, because two
+ * pieces share one handle (an arm is a shaft AND a head) and the placement
+ * differs between them.
+ */
+type PieceKind = "shaft" | "head" | "pad" | "disc" | "arc";
+
+interface Piece {
+  handle: GizmoHandleId;
+  kind: PieceKind;
+  object: Object3D;
+  material: MeshBasicNodeMaterial | LineBasicNodeMaterial;
+  geometry: BufferGeometry;
+  base: string;
+  fallback: string;
+  restAlpha: number;
+  tint: number;
+  alpha: number;
+}
+
+export function TransformGizmo({ theme, feed, panes, selection, cameraApexAt }: TransformGizmoProps) {
+  const hotColor = useMemo(
+    () => tokenColor("--gizmo-hot", theme === "light" ? "#1c1c1c" : "#ffffff"),
+    [theme],
+  );
+
+  // ── ONE MESH PER PIECE, ONE MATERIAL PER PIECE ────────────────────────
+  //
+  // Not one buffer with vertex colours: vertex colours on a node material would
+  // be a second thing to keep working across the WebGPU and WebGL2 backends,
+  // and the per-piece opacity the dimming needs is a uniform either way. Ten
+  // meshes is the whole cost, and nothing here allocates per frame.
+  const pieces = useMemo(() => {
+    const built: Piece[] = [];
+    /** Shared by every piece: the editor-only flags, the token colour, and the
+     *  transparency the dimming needs. */
+    const dress = (
+      handle: GizmoHandleId,
+      kind: PieceKind,
+      object: Object3D,
+      material: MeshBasicNodeMaterial | LineBasicNodeMaterial,
+      geometry: BufferGeometry,
+      base: string,
+      fallback: string,
+      restAlpha: number,
+    ): void => {
+      material.color.copy(tokenColor(base, fallback));
+      material.depthTest = false;
+      material.depthWrite = false;
+      material.toneMapped = false;
+      // Always transparent, so a handle going dead or being dimmed under a drag
+      // is one `opacity` write rather than a material recompile mid-gesture.
+      material.transparent = true;
+      material.opacity = restAlpha;
+      // The working pane renders under a clay override in solid/wireframe mode,
+      // and a grey gizmo is the one thing this must not be.
+      material.allowOverride = false;
+      object.layers.set(EDITOR_LAYER);
+      object.renderOrder = GIZMO_RENDER_ORDER;
+      // Position and scale are rewritten every frame from the screen-constant
+      // sizing (and an arc's vertices in place), so the bounding sphere the
+      // culler would test is never the one the geometry holds.
+      object.frustumCulled = false;
+      object.matrixAutoUpdate = false;
+      built.push({
+        handle,
+        kind,
+        object,
+        material,
+        geometry,
+        base,
+        fallback,
+        restAlpha,
+        tint: 0,
+        alpha: restAlpha,
+      });
+    };
+    const add = (
+      handle: GizmoHandleId,
+      kind: PieceKind,
+      geometry: BufferGeometry,
+      quaternion: Quaternion,
+      base: string,
+      fallback: string,
+      restAlpha: number,
+    ): void => {
+      const material = new MeshBasicNodeMaterial();
+      const mesh = new Mesh(geometry, material);
+      mesh.quaternion.copy(quaternion);
+      dress(handle, kind, mesh, material, geometry, base, fallback, restAlpha);
+    };
+
+    for (const { axis, world } of DESIGN_AXES) {
+      // The arm's direction is FIXED (a design axis in world), so its rotation
+      // is computed once here and never again — only position and scale move.
+      const along = new Quaternion().setFromUnitVectors(UP, new Vector3(world[0], world[1], world[2]));
+      // Unit primitives: height 1 and radius 1, centred on the origin along +y.
+      // Every real dimension is a `scale`, which is what makes the per-frame
+      // update three number writes and no geometry rebuild.
+      add(`axis:${axis}`, "shaft", new CylinderGeometry(1, 1, 1, 8, 1), along, `--axis-${axis}`, AXIS_FALLBACK[axis], 1);
+      add(`axis:${axis}`, "head", new ConeGeometry(1, 1, 16, 1), along, `--axis-${axis}`, AXIS_FALLBACK[axis], 1);
+      // The PAD normal to this axis, drawn in the plane of the other two. Its
+      // colour is the NORMAL's, matching Blender: the pad you grab to move in
+      // x and y is the one that leaves z alone, and naming it "z" is the only
+      // label that survives an orbit.
+      //
+      // ── ITS BASIS IS EXPLICIT, NOT THE SHORTEST ROTATION ───────────────
+      //
+      // `setFromUnitVectors(FORWARD, normal)` lands the square at whatever
+      // in-plane angle the shortest rotation happens to give, while the HIT
+      // QUAD is built from `padAxes` — same plane, different square, and a
+      // handle whose drawn corners answer no press. Building the rotation from
+      // the same two axes the hit test uses is what makes the two one shape.
+      const [pu, pv] = padAxes(axis);
+      const basis = new Matrix4().makeBasis(
+        new Vector3(pu[0], pu[1], pu[2]),
+        new Vector3(pv[0], pv[1], pv[2]),
+        new Vector3(world[0], world[1], world[2]),
+      );
+      const facing = new Quaternion().setFromRotationMatrix(basis);
+      add(`plane:${axis}`, "pad", new PlaneGeometry(1, 1), facing, `--axis-${axis}`, AXIS_FALLBACK[axis], PAD_OPACITY);
+      // ── THE ROTATE ARC ────────────────────────────────────────────────
+      //
+      // A `Line` rather than a mesh, and its vertices are WORLD points written
+      // in place every frame — a torus would have to be posed AND scaled
+      // anisotropically to stay screen-constant, and a tube's own thickness
+      // would then be wrong. Same construction the frustum uses.
+      const geometry = new ThreeBufferGeometry();
+      geometry.setAttribute(
+        "position",
+        new BufferAttribute(new Float32Array((ARC_SEGMENTS + 1) * 3), 3),
+      );
+      const material = new LineBasicNodeMaterial();
+      const line = new Line(geometry, material);
+      dress(
+        `arc:${axis}`,
+        "arc",
+        line,
+        material,
+        geometry,
+        `--axis-${axis}`,
+        AXIS_FALLBACK[axis],
+        ARC_OPACITY,
+      );
+    }
+    // The view-plane disc faces the camera, so its rotation is the ONE that has
+    // to be rewritten per frame. Accent rather than an axis colour: it is the
+    // handle that belongs to no axis.
+    add("screen", "disc", new CircleGeometry(1, 24), new Quaternion(), "--accent", "#0099ff", DISC_OPACITY);
+    return built;
+  }, [theme]);
+
+  useEffect(
+    () => () => {
+      for (const piece of pieces) {
+        piece.geometry.dispose();
+        piece.material.dispose();
+      }
+    },
+    [pieces],
+  );
+
+  useFrame(() => {
+    const working = panes.working;
+    const camera = feed.workingCamera;
+    // `modalTarget` and not `selection.length` written out again: this is the
+    // same fork `G` takes, and one of them drifting is a gizmo that moves
+    // something other than what the pill says it will.
+    //
+    // A selection whose layers are all off-frame at this playhead anchors
+    // NOWHERE rather than falling through to the camera — silently retargeting
+    // a live selection's gizmo at the camera is the worst answer available.
+    const subject = modalTarget(selection.length > 0);
+    // A DRIVEN camera has no rig to hang arms on: a component is writing the
+    // camera the picture shows, and dragging the rig would move nothing in it.
+    // `FrustumGizmo` writes the bit one frame behind, which is invisible.
+    const centre =
+      subject === "camera"
+        ? feed.cameraDriven
+          ? null
+          : cameraApexAt()
+        : selectionCentre(feed, selection);
+    if (working === null || camera === null || centre === null) {
+      for (const piece of pieces) piece.object.visible = false;
+      feed.gizmoHit = null;
+      return;
+    }
+
+    _origin.set(centre[0], centre[1], centre[2]);
+    const perPixel = worldPerPixel(camera, _origin, working.height);
+    // The anchor ON SCREEN, which is what every arm's own screen length is
+    // measured against below. An anchor behind the camera projects to garbage,
+    // so nothing is grabbable at all — the same refusal each arm makes.
+    const anchorVisible = !behind(_origin, camera);
+    const anchor = toScreen(_origin, camera, working.width, working.height);
+    // THE HIT TABLE, built innermost-first. The order IS the priority — see
+    // `gizmoHitAt`, which takes the first target that contains the point rather
+    // than the nearest, because a pad sits on top of the two arms bounding it.
+    const disc: GizmoTarget[] = [];
+    const pads: GizmoTarget[] = [];
+    const arms: GizmoTarget[] = [];
+    const arcs: GizmoTarget[] = [];
+    /** Each arc's projected polyline, kept so the DRAW pass writes the very
+     *  points the HIT test measured — one curve, not two that agree. */
+    const arcWorld = new Map<GizmoHandleId, readonly Vec3[]>();
+    // Which handles turned out to be grabbable this frame, so the draw pass can
+    // dim the ones that are not without asking the geometry a second time.
+    const live = new Set<GizmoHandleId>();
+    // THE CAMERA GETS ARROWS ONLY — see the header. Its framing has no free z,
+    // and the pads would either duplicate the body drag or promise a motion the
+    // document cannot store.
+    const full = subject === "layers";
+
+    for (const { axis, world } of DESIGN_AXES) {
+      const root = alongAxis(centre, world, GIZMO_PX.armStart * perPixel);
+      const tip = alongAxis(centre, world, GIZMO_PX.arm * perPixel);
+      // An arm with EITHER end behind the working camera projects to garbage,
+      // so it is drawn but not grabbable — the same refusal the frustum's body
+      // makes, and for the same reason: there is no screen segment to measure
+      // against.
+      let grabbable = anchorVisible && !isBehind(root, camera) && !isBehind(tip, camera);
+      if (grabbable) {
+        const a = toScreen(_point.set(root[0], root[1], root[2]), camera, working.width, working.height);
+        const b = toScreen(_point.set(tip[0], tip[1], tip[2]), camera, working.width, working.height);
+        // AN ARM THAT COLLAPSED ON SCREEN IS DRAWN BUT NOT GRABBABLE. The gate
+        // lives in `armGrabbable`, which is pure so a decision about whether
+        // the whole widget works can be checked without a GL context.
+        grabbable = armGrabbable(a, b, MIN_ARM_SCREEN_PX);
+        if (grabbable) {
+          arms.push({
+            handle: `axis:${axis}`,
+            origin: centre,
+            direction: world,
+            shape: { type: "path", points: [a, b], slop: GIZMO_PX.grab },
+          });
+          live.add(`axis:${axis}`);
+        }
+      }
+      // The camera's widget stops here on x and y; it keeps the z ARC below.
+      if (!full && axis !== "z") continue;
+      if (full) {
+        // The pad NORMAL to this axis, spanning the other two — the SAME four
+        // world corners the mesh is drawn at, out of the module that owns them.
+        const corners: [number, number][] = [];
+        let padVisible = anchorVisible;
+        for (const p of padCorners(
+          centre,
+          axis,
+          GIZMO_PX.padAt * perPixel,
+          (GIZMO_PX.pad / 2) * perPixel,
+        )) {
+          if (isBehind(p, camera)) {
+            padVisible = false;
+            break;
+          }
+          corners.push(toScreen(_point.set(p[0], p[1], p[2]), camera, working.width, working.height));
+        }
+        // A pad seen EDGE-ON projects to a sliver nothing can be inside, exactly
+        // as a collapsed arm does — and `designDelta` on its plane would then be
+        // a division by a grazing angle. `screenArea` is the same claim
+        // `armGrabbable` makes, in the units a quad has.
+        if (padVisible && screenArea(corners) >= MIN_PAD_SCREEN_AREA) {
+          pads.push({
+            handle: `plane:${axis}`,
+            origin: centre,
+            // The pad's own NORMAL: what its drag unprojects onto. See
+            // `GizmoGrab.direction`.
+            direction: world,
+            shape: { type: "quad", corners },
+          });
+          live.add(`plane:${axis}`);
+        }
+      }
+
+      // ── THE ROTATE ARC ──────────────────────────────────────────────────
+      //
+      // The SAME polyline is drawn and hit-tested, so an arc seen at an angle
+      // cannot have a grab shape that is a different curve from its picture.
+      // The whole arc is dropped when any point falls behind the camera, for
+      // the arm's reason: a projected ghost is not a curve anyone can aim at.
+      const points = arcPoints(centre, axis, GIZMO_PX.arc * perPixel, ARC_SEGMENTS);
+      arcWorld.set(`arc:${axis}`, points);
+      const screen: [number, number][] = [];
+      let arcVisible = anchorVisible;
+      for (const p of points) {
+        if (isBehind(p, camera)) {
+          arcVisible = false;
+          break;
+        }
+        screen.push(toScreen(_point.set(p[0], p[1], p[2]), camera, working.width, working.height));
+      }
+      // An arc seen EDGE-ON collapses to a straight line lying along its own
+      // chord — `ringAngle` still answers, but the projected curve gives the
+      // author nothing to aim along and every press near the anchor would grab
+      // it. `screenArea` of the closed polyline is the same claim `armGrabbable`
+      // and the pads make, in the units a curve has.
+      if (arcVisible && screenArea(screen) >= MIN_PAD_SCREEN_AREA) {
+        arcs.push({
+          handle: `arc:${axis}`,
+          origin: centre,
+          // The arc's own NORMAL: the axis the rotation turns ABOUT, and the
+          // plane its drag unprojects onto. See `GizmoGrab.direction`.
+          direction: world,
+          shape: { type: "path", points: screen, slop: GIZMO_PX.arcGrab },
+        });
+        live.add(`arc:${axis}`);
+      }
+    }
+
+    if (full && anchorVisible) {
+      // The disc's normal is the camera's own forward, so a drag on it moves
+      // the selection in the plane of the screen — the one placement gesture
+      // that needs no axis at all.
+      const forward = cameraForward(camera);
+      disc.push({
+        handle: "screen",
+        origin: centre,
+        direction: forward,
+        shape: { type: "disc", at: anchor, radius: GIZMO_PX.screen },
+      });
+      live.add("screen");
+    }
+
+    // ORDER IS PRIORITY: innermost first, which is the only order in which every
+    // handle stays reachable — and the ARMS outrank the ARCS deliberately, so
+    // the two points where each quarter arc crosses the axes that bound it
+    // belong to the arms.
+    const targets = [...disc, ...pads, ...arms, ...arcs];
+    feed.gizmoHit = (x, y) => {
+      const hit = gizmoHitAt(targets, x, y);
+      return hit === null
+        ? null
+        : { subject, handle: hit.handle, origin: hit.origin, direction: hit.direction };
+    };
+
+    // ── DRAW ──────────────────────────────────────────────────────────────
+    const held = feed.activeHandle;
+    for (const piece of pieces) {
+      const axis = gizmoAxisOf(piece.handle);
+      // ARROWS AND THE ROLL ARC ARE THE CAMERA'S WHOLE WIDGET — see the header
+      // for why its framing gets no pads, no disc and no other arc.
+      const shown =
+        piece.kind === "shaft" || piece.kind === "head" || piece.handle === "arc:z" ? true : full;
+      piece.object.visible = shown;
+      if (!shown) continue;
+      if (piece.kind === "disc") {
+        // The only piece whose ROTATION moves: it faces the camera, which turns
+        // under the author's orbit while everything else is pinned to a design
+        // axis.
+        piece.object.quaternion.copy(camera.quaternion);
+        const r = GIZMO_PX.screen * perPixel;
+        placeAt(piece.object, centre, r, r, 1);
+      } else if (piece.kind === "pad" && axis !== null) {
+        const side = GIZMO_PX.pad * perPixel;
+        placeAt(piece.object, padCentre(centre, axis, GIZMO_PX.padAt * perPixel), side, side, 1);
+      } else if (piece.kind === "arc") {
+        // WORLD vertices, rewritten in place from the very points the hit test
+        // measured — the object stays at the origin with an identity matrix,
+        // which is the same construction the frustum gizmo uses.
+        const points = arcWorld.get(piece.handle);
+        if (points !== undefined) writeArc(piece.geometry, points);
+      } else if (axis !== null) {
+        const world = DESIGN_AXES.find((a) => a.axis === axis)!.world;
+        const shaftEnd = (GIZMO_PX.arm - GIZMO_PX.arrowHead) * perPixel;
+        const start = GIZMO_PX.armStart * perPixel;
+        // Two pieces share `axis:*`, and `kind` is what tells them apart: the
+        // SHAFT is the cylinder, the HEAD is the cone. Neither is a handle of
+        // its own — a press on either is a press on the arm.
+        if (piece.kind === "shaft") {
+          placeAt(
+            piece.object,
+            alongAxis(centre, world, (start + shaftEnd) / 2),
+            GIZMO_PX.shaft * perPixel,
+            Math.max(shaftEnd - start, 0),
+            GIZMO_PX.shaft * perPixel,
+          );
+        } else {
+          placeAt(
+            piece.object,
+            alongAxis(centre, world, shaftEnd + (GIZMO_PX.arrowHead * perPixel) / 2),
+            GIZMO_PX.arrowWidth * perPixel,
+            GIZMO_PX.arrowHead * perPixel,
+            GIZMO_PX.arrowWidth * perPixel,
+          );
+        }
+      }
+
+      // ── HOT, DIM, OR AT REST ────────────────────────────────────────────
+      //
+      // Blender highlights the gizmo element under the cursor and dims the rest
+      // once a transform is running, and this pane did neither — so "is this
+      // grabbable" was something the author learned by trying, and a live drag
+      // kept three full-strength lines across the geometry being judged.
+      //
+      // Here, in the frame loop, off two plain fields the pointer lane wrote. A
+      // hover therefore costs one uniform write and zero React renders, which
+      // is the whole reason `feed.hoverHandle` is a field and not state.
+      const hot = held === null ? feed.hoverHandle === piece.handle : held === piece.handle;
+      const dim = held === null ? !live.has(piece.handle) : held !== piece.handle;
+      const wantTint = hot ? HOVER_TINT : 0;
+      const wantAlpha = dim ? DEAD_OPACITY * piece.restAlpha : piece.restAlpha;
+      if (piece.tint !== wantTint) {
+        piece.tint = wantTint;
+        piece.material.color.copy(tokenColor(piece.base, piece.fallback)).lerp(hotColor, wantTint);
+      }
+      if (piece.alpha !== wantAlpha) {
+        piece.alpha = wantAlpha;
+        piece.material.opacity = wantAlpha;
+      }
+    }
+  }, 0);
+
+  useEffect(
+    () => () => {
+      feed.gizmoHit = null;
+    },
+    [feed],
+  );
+
+  return (
+    <>
+      {pieces.map((piece, i) => (
+        <primitive key={`${piece.handle}-${i}`} object={piece.object} />
+      ))}
+    </>
+  );
+}
+
+/** An arc's world points into its position buffer, past the frustum gizmo's own
+ *  half-pixel gate: this runs on every committed frame, and a parked playhead
+ *  with a selection must not re-upload three buffers per seek. */
+function writeArc(geometry: BufferGeometry, points: readonly Vec3[]): void {
+  const attribute = geometry.getAttribute("position") as BufferAttribute;
+  const buffer = attribute.array as Float32Array;
+  let moved = false;
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i]!;
+    for (let c = 0; c < 3; c++) {
+      const at = i * 3 + c;
+      if (Math.abs(buffer[at]! - p[c]!) > 0.5) moved = true;
+      buffer[at] = p[c]!;
+    }
+  }
+  if (moved) attribute.needsUpdate = true;
+}
+
+function isBehind(point: Vec3, camera: Camera): boolean {
+  return behind(_point.set(point[0], point[1], point[2]), camera);
+}
+
+/** The camera's own forward, in world. The third basis column of its world
+ *  matrix points BACK from the eye, so the forward is its negation. */
+function cameraForward(camera: Camera): Vec3 {
+  const e = camera.matrixWorld.elements;
+  return [-e[8]!, -e[9]!, -e[10]!];
+}
+
+/** One piece's per-frame update: three position writes, three scale writes and
+ *  one matrix compose. No allocation, because a parked playhead with a
+ *  selection has to cost nothing. */
+function placeAt(object: Object3D, at: Vec3, sx: number, sy: number, sz: number): void {
+  object.position.set(at[0], at[1], at[2]);
+  object.scale.set(sx, sy, sz);
+  object.updateMatrix();
+}
+
+/**
+ * Where the gizmo sits: the mean of the selected layers' own origins.
+ *
+ * The GROUP origin out of `feed.frames`, never the mesh's centre — a paint
+ * layer's plane is grown by the rasterizer's shadow padding, so the mesh would
+ * put the gizmo a blur radius away from the thing it moves (the same reason
+ * `collectFrames` reads userData).
+ *
+ * Null when nothing selected is on screen this frame, which includes a
+ * selection whose lifetime has ended: a handle drawn for a layer that is not
+ * there would drag something the author cannot see.
+ */
+function selectionCentre(feed: StageFeed, selection: readonly string[]): Vec3 | null {
+  const frames = feed.frames;
+  if (frames === null || selection.length === 0) return null;
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  let count = 0;
+  // ONE FRAME PER ID, the first — the same rule `StageTools`' `byId` follows.
+  // A cloner stamps its children N times under one id, and averaging all the
+  // clones put the gizmo in the empty space between them rather than on the
+  // layer the author selected.
+  const seen = new Set<string>();
+  for (const frame of frames) {
+    if (!selection.includes(frame.id) || seen.has(frame.id)) continue;
+    seen.add(frame.id);
+    const e = frame.matrixWorld.elements;
+    x += e[12]!;
+    y += e[13]!;
+    z += e[14]!;
+    count += 1;
+  }
+  return count === 0 ? null : [x / count, y / count, z / count];
+}
+
+// `worldPerPixel` lives in project.ts now: the camera body (FrustumGizmo) sizes
+// itself with the same function, and one copy is how the two stay one rule.