@dailies-studio/shot-editor 0.1.0

package/src/stage/MoveGizmo.tsx

@@ -0,0 +1,411 @@
+// Three drag arms in the working pane, on whatever the author is transforming.
+//
+// ── 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.
+//
+// ── WHAT THIS ADDS THAT THE PANE DID NOT HAVE ───────────────────────────
+//
+// Dragging a layer's BODY in this pane unprojects onto a plane, so it can move
+// the layer in two axes at once but never along z. Everything else was on the
+// keyboard: G-X, G-Y, G-Z. This is the pointer's way to say the same three
+// things, which is the one an author reaching for "place it over there" tries
+// first. The camera had even less: a body drag that pans and an apex drag that
+// zooms, neither of which can be constrained to an axis.
+//
+// ROTATE AND SCALE STAY ON R AND S. They already exist, with axis constraints
+// and a live pill (modalState.ts); a second set of rings and boxes would be a
+// duplicate of a lane that works, and every one of them would need its own
+// screen-space arc maths. This gizmo is TRANSLATE ONLY, on purpose.
+//
+// ── WHY THE DRAG SOLVES A LINE AND NOT 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.
+//
+// ── 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 in this file opens.
+import { useEffect, useMemo } from "react";
+import { useFrame } from "@react-three/fiber";
+import { BufferAttribute, BufferGeometry, Color, LineSegments, Vector3 } from "three";
+import type { Camera, OrthographicCamera, PerspectiveCamera } from "three";
+import { LineBasicNodeMaterial } from "three/webgpu";
+import { EDITOR_LAYER } from "./StageTools.js";
+import { DESIGN_AXES, armGrabbable } from "./gizmoMath.js";
+import type { DesignAxis, Vec3 } from "./gizmoMath.js";
+// `GizmoGrab` lives in gizmoMath.ts with the rest of the axis vocabulary — the
+// pointer lane carries one and must not import a three-side module for a type.
+import { APEX_GRAB_PX } from "./FrustumGizmo.js";
+import { borderDistance, segmentsMoved } from "./frustumGeometry.js";
+import { modalTarget } from "./modalState.js";
+import { toScreen } from "./project.js";
+import { tokenColor } from "./tokenColor.js";
+import type { StageFeed } from "./feed.js";
+import type { PaneRect } from "./panes.js";
+
+/** Over everything, and over the frustum too: an arm that a camera gizmo could
+ *  hide is an arm the author cannot grab. */
+const GIZMO_RENDER_ORDER = 2_000_000;
+
+/** Arm tip distance in CSS px, held CONSTANT as the author dollies. A
+ *  world-space length would be a gizmo that fills the pane up close and
+ *  disappears far out — and, because the hit slop below is in screen px, one
+ *  whose grab target changed size with the zoom. */
+const ARM_PX = 90;
+
+/** How close a press has to land to an arm, in CSS px. The frustum's own 14 —
+ *  a line is a line, and the author's finger is the same size in both. */
+const GRAB_PX = 14;
+
+/**
+ * Where an arm STARTS, in CSS px from the anchor.
+ *
+ * It has to clear the anchor by more than BOTH slops added together, and that
+ * is not cosmetic. On the camera the anchor IS the frustum's apex, whose own
+ * grab is a 14px screen target (FrustumGizmo's APEX_GRAB_PX) tested AFTER this
+ * one in the pointer lane. At any start below `APEX_GRAB_PX + GRAB_PX` a press
+ * aimed at the apex lands within `GRAB_PX` of an arm as well, the arms win, and
+ * the apex dolly becomes unreachable — silently, because an arm drag looks like
+ * a working gesture.
+ *
+ * 30 > 14 + 14. It also keeps the three roots from piling into one ambiguous
+ * blob, which is why the layer gizmo wants it too.
+ */
+const ARM_START_PX = 30;
+
+/**
+ * How far an arm's ROOT must land from the anchor ON SCREEN to be grabbable.
+ *
+ * ── WHY `ARM_START_PX` IS NOT ENOUGH ────────────────────────────────────
+ *
+ * The note above asserts an inequality in SCREEN px ("30 > 14 + 14"), but the
+ * value is converted to WORLD units at the anchor's depth and then projected.
+ * So the distance the author actually sees is `ARM_START_PX * sin(angle to the
+ * view direction)`, and an axis pointing near the camera collapses:
+ *
+ *   At Numpad7 the polar angle clamps to 5 degrees, so the design y arm
+ *   projects to about 2.6 px and every press near the selection centre grabs
+ *   it. A 5 px twitch then throws the layer.
+ *
+ *   Under ISOLATION'S ORTHOGRAPHIC RIG there is no vanishing point at all: the
+ *   design z axis points exactly at the camera, so the z arm projects to a
+ *   mathematical POINT on the anchor. `borderDistance` to a degenerate segment
+ *   is the distance to that point, so every press within `GRAB_PX` of the
+ *   selection centre grabs it — and then `axisParam` divides by a zero
+ *   denominator, answers null, and `runGizmoGesture` returns before opening a
+ *   scrub. The press is completely dead, under a blue line that looks grabbable.
+ *
+ * So the test is done where it is true: after projection, in screen px. An arm
+ * that fails it is still DRAWN — it is a real axis and hiding it would be
+ * lying about the geometry — but it does not answer presses, so they fall
+ * through to the pick lane underneath.
+ *
+ * ── AND IT MEASURES THE DRAWN LENGTH, NOT THE ROOT OFFSET ───────────────
+ *
+ * The first version of this gate compared the ROOT's distance from the anchor,
+ * on the reasoning that the tip sits three times further out so the root test
+ * implies the length test. That is backwards: the root offset is at most
+ * `ARM_START_PX = 30` px and the threshold is 28, so at the SHIPPED DEFAULT
+ * view (theta 35, phi 65) all three arms measured 20 to 27 px, every one of
+ * them failed, `ends` came back empty and the gizmo was inert everywhere. The
+ * quantity that decides whether a segment can be grabbed is the segment's own
+ * length, so that is what is measured.
+ *
+ * The APEX CLEARANCE is a separate question and only applies to the camera
+ * subject, where the anchor IS the frustum's apex — see `ARM_START_PX`.
+ */
+const MIN_ARM_SCREEN_PX = GRAB_PX * 2;
+
+const AXIS_FALLBACK: Readonly<Record<DesignAxis, string>> = {
+  x: "#ef4444",
+  y: "#22c55e",
+  z: "#3b82f6",
+};
+
+/** How far a hovered arm blends towards white. Enough to read as hot at a
+ *  glance, little enough that red / green / blue still name the axis. */
+const HOVER_TINT = 0.45;
+const WHITE = new Color(1, 1, 1);
+
+const DEG = Math.PI / 180;
+const _origin = new Vector3();
+const _root = new Vector3();
+const _tip = new Vector3();
+const _view = new Vector3();
+/** One arm's six position floats, hoisted: the hot path allocates nothing. */
+const _next = new Float32Array(6);
+
+/** 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 MoveGizmoProps {
+  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. */
+  cameraApex: Vec3 | null;
+}
+
+export function MoveGizmo({ feed, panes, selection, cameraApex }: MoveGizmoProps) {
+  // One `LineSegments` per axis rather than one buffer with vertex colours:
+  // three objects and three materials is the whole cost, and vertex colours on
+  // a node material would be a second thing to keep working across the WebGPU
+  // and WebGL2 backends for no gain at three vertices apiece.
+  const arms = useMemo(
+    () =>
+      DESIGN_AXES.map(({ axis }) => {
+        const geometry = new BufferGeometry();
+        geometry.setAttribute("position", new BufferAttribute(new Float32Array(6), 3));
+        const material = new LineBasicNodeMaterial();
+        material.color.copy(tokenColor(`--axis-${axis}`, AXIS_FALLBACK[axis]));
+        material.depthTest = false;
+        material.depthWrite = false;
+        material.toneMapped = false;
+        // 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;
+        const lines = new LineSegments(geometry, material);
+        lines.layers.set(EDITOR_LAYER);
+        lines.renderOrder = GIZMO_RENDER_ORDER;
+        // World positions rewritten in place — same reason the frustum turns
+        // culling off: the bounding sphere is never the one the buffer holds.
+        lines.frustumCulled = false;
+        lines.matrixAutoUpdate = false;
+        // How far towards white the hover has taken this arm, so the frame loop
+        // can skip the colour write on every frame that changed nothing.
+        return { axis, lines, geometry, material, tint: 0 };
+      }),
+    [],
+  );
+
+  useEffect(
+    () => () => {
+      for (const arm of arms) {
+        arm.geometry.dispose();
+        arm.material.dispose();
+      }
+    },
+    [arms],
+  );
+
+  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);
+    const centre = subject === "camera" ? cameraApex : selectionCentre(feed, selection);
+    if (working === null || camera === null || centre === null) {
+      for (const arm of arms) arm.lines.visible = false;
+      feed.gizmoHit = null;
+      return;
+    }
+
+    _origin.set(centre[0], centre[1], centre[2]);
+    const perPixel = worldPerPixel(camera, _origin, working.height);
+    const start = ARM_START_PX * perPixel;
+    const length = ARM_PX * perPixel;
+    // 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);
+    // Screen ends, kept beside the world ones so the hit test measures the
+    // segment that was actually drawn.
+    const ends: {
+      axis: DesignAxis;
+      world: Vec3;
+      a: [number, number];
+      b: [number, number];
+    }[] = [];
+
+    for (const [i, { world }] of DESIGN_AXES.entries()) {
+      const arm = arms[i]!;
+      arm.lines.visible = true;
+      const from: Vec3 = [
+        centre[0] + world[0] * start,
+        centre[1] + world[1] * start,
+        centre[2] + world[2] * start,
+      ];
+      const to: Vec3 = [
+        centre[0] + world[0] * length,
+        centre[1] + world[1] * length,
+        centre[2] + world[2] * length,
+      ];
+      const attribute = arm.geometry.getAttribute("position") as BufferAttribute;
+      const buffer = attribute.array as Float32Array;
+      _next[0] = from[0];
+      _next[1] = from[1];
+      _next[2] = from[2];
+      _next[3] = to[0];
+      _next[4] = to[1];
+      _next[5] = to[2];
+      // The frustum's own half-pixel gate, for its reason: this runs on every
+      // committed frame, and a parked playhead with a selection must not
+      // re-upload three buffers per seek.
+      if (segmentsMoved(buffer, _next)) {
+        buffer.set(_next);
+        attribute.needsUpdate = true;
+      }
+
+      // 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.
+      _root.set(from[0], from[1], from[2]);
+      _tip.set(to[0], to[1], to[2]);
+      if (!anchorVisible || behind(_root, camera) || behind(_tip, camera)) continue;
+      const a = toScreen(_root, camera, working.width, working.height);
+      const b = toScreen(_tip, camera, working.width, working.height);
+      // AN ARM THAT COLLAPSED ON SCREEN IS DRAWN BUT NOT GRABBABLE, and on the
+      // camera it must also clear the apex. Both live in `armGrabbable`, which
+      // is pure so a gate that decides whether the whole widget works can be
+      // checked without a GL context.
+      if (!armGrabbable(a, b, anchor, subject, MIN_ARM_SCREEN_PX, APEX_GRAB_PX + GRAB_PX)) continue;
+      ends.push({ axis: arm.axis, world, a, b });
+    }
+
+    feed.gizmoHit = (x, y) => {
+      let best: (typeof ends)[number] | null = null;
+      let bestDistance = GRAB_PX;
+      for (const end of ends) {
+        // `borderDistance` walks a CLOSED polygon, so a two-point list is that
+        // one segment measured twice — the point-to-segment distance, out of
+        // the module that already owns it.
+        const distance = borderDistance(x, y, [end.a, end.b]);
+        if (distance <= bestDistance) {
+          best = end;
+          bestDistance = distance;
+        }
+      }
+      return best === null
+        ? null
+        : { subject, axis: best.axis, origin: centre, direction: best.world };
+    };
+
+    // ── THE HOVERED ARM LIGHTS UP ─────────────────────────────────────────
+    //
+    // Blender highlights the gizmo element under the cursor, and this pane did
+    // not — so "is this grabbable" was something the author learned by trying.
+    // Blended TOWARDS WHITE rather than swapped for it, so the axis is still
+    // identifiable by colour while it is hot.
+    //
+    // Here, in the frame loop, off a plain field the pointer lane wrote. A
+    // hover therefore costs one uniform write per frame and zero React renders,
+    // which is the whole reason `feed.hoverArm` is a field and not state.
+    for (const arm of arms) {
+      const hot = feed.hoverArm === arm.axis && ends.some((e) => e.axis === arm.axis);
+      const want = hot ? HOVER_TINT : 0;
+      if (arm.tint === want) continue;
+      arm.tint = want;
+      arm.material.color.copy(tokenColor(`--axis-${arm.axis}`, AXIS_FALLBACK[arm.axis])).lerp(WHITE, want);
+    }
+  }, 0);
+
+  useEffect(
+    () => () => {
+      feed.gizmoHit = null;
+    },
+    [feed],
+  );
+
+  return (
+    <>
+      {arms.map((arm) => (
+        <primitive key={arm.axis} object={arm.lines} />
+      ))}
+    </>
+  );
+}
+
+/**
+ * Where the arms sit: 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: an arm 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];
+}
+
+/**
+ * World units per CSS pixel AT A POINT, which is what turns the arm's fixed
+ * screen length into a world one.
+ *
+ * Both camera classes, because isolation swaps an ORTHOGRAPHIC camera into this
+ * pane's slot (StageTools) and a perspective-only formula would size the gizmo
+ * off a `fov` that camera does not have — reading `undefined` and drawing arms
+ * of length NaN, which is a gizmo that silently disappears inside isolation.
+ *
+ * Perspective: the visible height at the point's own view depth, over the pane.
+ * Orthographic: its frustum height over the pane, which has no depth term at
+ * all — that is what orthographic means.
+ */
+function worldPerPixel(camera: Camera, at: Vector3, paneHeight: number): number {
+  const height = Math.max(1, paneHeight);
+  const ortho = camera as OrthographicCamera;
+  if (ortho.isOrthographicCamera === true) {
+    const zoom = ortho.zoom > 0 ? ortho.zoom : 1;
+    return Math.abs(ortho.top - ortho.bottom) / zoom / height;
+  }
+  const perspective = camera as PerspectiveCamera;
+  const fov = Number.isFinite(perspective.fov) ? perspective.fov : 50;
+  // View-space z runs NEGATIVE in front of the camera, so the depth is its
+  // negation — and it is floored off zero, because a selection sitting exactly
+  // at the eye would otherwise give every arm zero length.
+  const depth = Math.max(-_view.copy(at).applyMatrix4(camera.matrixWorldInverse).z, 1e-3);
+  return (2 * Math.tan((fov * DEG) / 2) * depth) / height;
+}

package/src/stage/PerfHud.tsx

@@ -0,0 +1,206 @@
+// The stage's perf readout, behind `?perf=1` on the stage URL.
+//
+// Exists because every performance judgement about this lane used to be made
+// by reading code: there was no way to SEE where a frame went. The HUD prints
+// the five numbers that decide whether the stage is healthy, sampled on a
+// half-second interval so the HUD itself costs nothing worth measuring:
+//
+//   gl/s     GL frames drawn per second. Under `frameloop="never"` a draw IS
+//            a React commit, so this doubling the seek rate is the symptom of
+//            a double-commit bug (the overlay bump was one).
+//   ui ms    EMA of the gap between rAF ticks — main-thread health. 16.7 is
+//            a clean 60Hz; spikes mean something synchronous is eating the
+//            thread (a raster storm, a full-dock reconcile).
+//   draws    draw calls in the last GL frame, off `gl.info` (see PerfProbe
+//            for the drawCalls-vs-calls renderer-class split).
+//   raster   the module LRU: live MB (refcounted entries included — the
+//            honest live set), entry count, and hits/misses over the last
+//            interval. Misses during steady playback are a regression; see
+//            rasterCache.test.ts.
+//   layers   how many layers the open document's current scene holds.
+//
+// Two halves, same file: `PerfProbe` runs INSIDE the canvas (priority 2, after
+// the presenters, so its info read sees the finished frame) and writes into a
+// mutable box; `PerfHud` is DOM, polling the box and `rasterCacheStats()` on
+// an interval. The box is the same feed pattern the picking lane uses — the
+// probe must never cause a render, or the HUD would bend the number it shows.
+import { useEffect, useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { rasterCacheStats } from "@dailies-studio/shot";
+
+/** Read once: the stage URL is set at iframe mount and never rewritten. */
+export const PERF_HUD_ENABLED =
+  typeof window !== "undefined" && new URLSearchParams(window.location.search).get("perf") === "1";
+
+export interface PerfBox {
+  glFrames: number;
+  drawCalls: number;
+  /** Active GL programs, off `info.memory.programs`. A number that RISES on a
+   *  layout switch is the compile-storm symptom the warm-up exists to kill;
+   *  after warm-up it should be flat across every mode flip. */
+  programs: number;
+  /**
+   * Triangles the renderer submitted, off `info.render.triangles`.
+   *
+   * LAST BIN ONLY when a scene has more than one. `renderBins` calls
+   * `gl.render` once per bin and the info resets per render, so this reports
+   * the final pass rather than the frame — exactly the caveat `drawCalls`
+   * beside it already carries, and for exactly the same reason. The outliner's
+   * per-layer badges are the number to trust for authoring decisions; this one
+   * is for watching a pass get heavier while you drag.
+   */
+  triangles: number;
+  /** Wall-time spans from a `markPerf()` call to the NEXT presented frame,
+   *  keyed by the mark's name. The probe settles them; the HUD prints them. */
+  spans: Record<string, number>;
+}
+
+export function createPerfBox(): PerfBox {
+  return { glFrames: 0, drawCalls: 0, programs: 0, triangles: 0, spans: {} };
+}
+
+/**
+ * Marks pending until the next presented GL frame.
+ *
+ * Module scope, not the box: the callers (StageApp's doc/layout effects) run
+ * in React's commit and the settle runs inside `advance()`, and threading the
+ * box through both for two timestamps would put a perf-only field on the
+ * component contract. Cleared by the probe the moment they are measured.
+ */
+const pendingMarks = new Map<string, number>();
+
+/** Record "X happened; measure to the next presented frame". No-op unless the
+ *  HUD is on, so callers do not need their own gate. */
+export function markPerf(name: string): void {
+  if (!PERF_HUD_ENABLED) return;
+  pendingMarks.set(name, performance.now());
+}
+
+/** In-canvas half: counts GL frames and copies the renderer's draw-call count.
+ *
+ *  THE PRIORITY IS CONDITIONAL AND THAT IS LOAD-BEARING. Any useFrame with
+ *  priority > 0 makes fiber skip its own render (`!state.internal.priority`
+ *  gates the default draw), on the theory that a positive-priority subscriber
+ *  IS the renderer. In the camera-only layout nothing else takes over the
+ *  present, so a probe at priority 2 there would be the only "renderer" on
+ *  the canvas — and it draws nothing: a blank stage, only under ?perf=1, only
+ *  in the default layout. So: priority 2 only when a presenter is mounted
+ *  (SplitRenderer or ScenePresenter, both priority 1) so the probe reads the
+ *  FINISHED frame; priority 0 otherwise, where `drawCalls` is one frame stale
+ *  — fine for a 500ms-sampled HUD, and gl/s stays exact. */
+export function PerfProbe({ box, presenterMounted }: { box: PerfBox; presenterMounted: boolean }): null {
+  const gl = useThree((s) => s.gl);
+  useFrame(() => {
+    box.glFrames += 1;
+    const info = (gl as {
+      info?: {
+        render?: { calls?: number; drawCalls?: number; triangles?: number };
+        memory?: { programs?: number };
+      };
+    }).info;
+    // The common WebGPURenderer Info spells the per-frame count `drawCalls`
+    // (its `calls` is a LIFETIME total); a classic WebGLRenderer has no
+    // `drawCalls` and its `calls` is per-frame. Hence this fallback order —
+    // the split is renderer class, not backend.
+    box.drawCalls = info?.render?.drawCalls ?? info?.render?.calls ?? 0;
+    box.programs = info?.memory?.programs ?? 0;
+    // Spelled the same on both renderer classes, so no fallback is needed here.
+    box.triangles = info?.render?.triangles ?? 0;
+    // Settle pending marks: this frame is the first one PRESENTED after the
+    // mark, which is the moment the author saw the result.
+    if (pendingMarks.size > 0) {
+      const now = performance.now();
+      for (const [name, at] of pendingMarks) box.spans[name] = now - at;
+      pendingMarks.clear();
+    }
+  }, presenterMounted ? 2 : 0);
+  return null;
+}
+
+const SAMPLE_MS = 500;
+
+/** DOM half: the readout. `layers` is passed in because only the caller knows
+ *  which scene is current; everything else is sampled here. */
+export function PerfHud({ box, layers }: { box: PerfBox; layers: number }) {
+  const [text, setText] = useState("perf…");
+  // rAF gap EMA, sampled continuously but folded into state only per interval.
+  const uiMs = useRef(16.7);
+  useEffect(() => {
+    let raf = 0;
+    let last = performance.now();
+    const tick = (): void => {
+      const now = performance.now();
+      uiMs.current = uiMs.current * 0.9 + (now - last) * 0.1;
+      last = now;
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, []);
+  // Long tasks since the last sample: count and the worst one. This is the
+  // number that catches a synchronous compile or raster storm even when the
+  // rAF-gap EMA has already recovered by sample time.
+  const longTasks = useRef({ count: 0, maxMs: 0 });
+  useEffect(() => {
+    if (typeof PerformanceObserver === "undefined") return;
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        longTasks.current.count += 1;
+        longTasks.current.maxMs = Math.max(longTasks.current.maxMs, entry.duration);
+      }
+    });
+    try {
+      observer.observe({ entryTypes: ["longtask"] });
+    } catch {
+      return; // the entry type is Chromium-only; the HUD just drops the field
+    }
+    return () => observer.disconnect();
+  }, []);
+  useEffect(() => {
+    let lastFrames = box.glFrames;
+    let lastHits = rasterCacheStats().hits;
+    let lastMisses = rasterCacheStats().misses;
+    const timer = setInterval(() => {
+      const stats = rasterCacheStats();
+      const gps = ((box.glFrames - lastFrames) * 1000) / SAMPLE_MS;
+      const hits = stats.hits - lastHits;
+      const misses = stats.misses - lastMisses;
+      lastFrames = box.glFrames;
+      lastHits = stats.hits;
+      lastMisses = stats.misses;
+      const lt = longTasks.current;
+      const ltText = lt.count > 0 ? ` · lt ${lt.count}/${lt.maxMs.toFixed(0)}ms` : "";
+      longTasks.current = { count: 0, maxMs: 0 };
+      const spans = Object.entries(box.spans)
+        .map(([name, ms]) => ` · ${name} ${ms.toFixed(0)}ms`)
+        .join("");
+      setText(
+        `gl/s ${gps.toFixed(0)} · ui ${uiMs.current.toFixed(1)}ms · draws ${box.drawCalls} · ` +
+          `tris ${box.triangles} · progs ${box.programs} · ` +
+          `raster ${(stats.bytes / 1e6).toFixed(0)}MB/${stats.entries} (+${hits}h ${misses}m) · ` +
+          `layers ${layers}${ltText}${spans}`,
+      );
+    }, SAMPLE_MS);
+    return () => clearInterval(timer);
+  }, [box, layers]);
+  return (
+    <div
+      style={{
+        position: "fixed",
+        left: 8,
+        bottom: 8,
+        zIndex: 40,
+        padding: "4px 8px",
+        borderRadius: 4,
+        background: "rgba(10, 10, 12, 0.82)",
+        color: "#9be29b",
+        font: "11px/1.5 ui-monospace, monospace",
+        pointerEvents: "none",
+        whiteSpace: "nowrap",
+      }}
+      data-testid="perf-hud"
+    >
+      {text}
+    </div>
+  );
+}