@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/PerfHud.tsx

@@ -2,7 +2,7 @@
 //
 // 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
+// the six 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
@@ -11,26 +11,147 @@
 //   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).
+//   gpu      the GPU's own time per frame, p50/p95 over the frames resolved
+//            since the last sample, off three's timestamp queries
+//            (`GpuTimer`, gpuTimer.ts); `n/a` when the renderer has no
+//            timer, `-` when nothing drew.
+//   scale    the playback render scale (renderScaleController.ts): the share
+//            of the display's density a played frame renders at, the mode,
+//            a step waiting for its cut, the last judged window's GPU p75
+//            against its frame period and its frames that came late, and
+//            why it last moved.
+//   draws    draw calls in the last frame, every render of it summed, off
+//            `gl.info` (see PerfProbe for the reset and 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.
+// Two halves, same file: `PerfProbe` runs INSIDE the canvas (the scheduler's
+// finish phase, after the presenters, so its info read sees the finished
+// frame) and writes into a mutable box, which StageApp's `GpuTimer` feeds
+// too; `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";
+import {
+  canvasUploadStats,
+  enableShotPerf,
+  layerMaterialPoolStats,
+  planeCacheStats,
+  rasterCacheStats,
+  rendererCompileBusy,
+  shotPerfStats,
+} from "@dailies-studio/shot";
+import type { PresentationQuality } from "./adaptivePresentation.js";
+import {
+  createJsSelfProfilerController,
+  isLocalJsSelfProfileOptIn,
+} from "./jsSelfProfiler.js";
+import type { JsSelfProfilerController } from "./jsSelfProfiler.js";
+import type { StageInset } from "../bridgeTypes.js";
+import { GpuSamples, NO_GPU_STATS } from "./gpuTimer.js";
+import type { GpuStats, GpuTimerKind } from "./gpuTimer.js";
+import type { RenderScaleController, RenderScaleReading } from "./renderScaleController.js";
+import { stagePerformanceInterval, stagePerformanceLine } from "./stagePerformanceTelemetry.js";
+import type {
+  StagePerformanceDebugSnapshot,
+  StagePresentationSample,
+  StagePerformanceTelemetry,
+} from "./stagePerformanceTelemetry.js";
 
 /** 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";
+  typeof window !== "undefined" && new URLSearchParams(window.location.search).get("perf") !== null;
+
+/** `?perf=log` as well as the HUD: echo every sample to the console.
+ *
+ * OPT-IN SEPARATELY, because it is two lines a second forever and the console
+ * is also where three's own deprecation warnings and any real error land. The
+ * overlay and `window.__perf` cover reading a number; this covers watching one
+ * move over time, which is the rarer want. */
+export const PERF_LOG_ENABLED =
+  typeof window !== "undefined" && new URLSearchParams(window.location.search).get("perf") === "log";
+
+/** The stack sampler is stricter than the counter HUD: exact query value and
+ * a loopback document. A hosted page carrying a copied query remains inert. */
+export const PERF_SELF_PROFILE_ENABLED =
+  typeof window !== "undefined" && isLocalJsSelfProfileOptIn(window.location.href);
+
+// The runtime's own counters cost a `performance.now()` per draw, so they stay
+// off until something asks. This is the only caller, and asking once at module
+// evaluation means the very first frames are measured too — a compile storm on
+// load is exactly the kind of thing that would hide behind a later switch-on.
+if (PERF_HUD_ENABLED && !PERF_SELF_PROFILE_ENABLED) enableShotPerf();
+
+/**
+ * The counters themselves, not the line: `window.__perfProbe`.
+ *
+ * `window.__perf` is a STRING sampled on an interval, and a hidden tab clamps
+ * that interval to about a second — useless for asking what one frame cost.
+ * The obvious answer, importing `@dailies-studio/shot` from the console and
+ * calling `shotPerfStats()`, does not work: Vite hands an `?t=` -stamped URL
+ * to the module graph and a console import of the bare path gets a SECOND
+ * instance, whose counters are all zero while the real ones move. That failure
+ * is silent and reads exactly like "the runtime is not drawing".
+ *
+ * So the HUD, which is already inside the stage and already holds the live
+ * bindings, publishes them. Behind the same flag as everything else here, so a
+ * shipped stage has no such property.
+ */
+/** The live renderer, parked by `PerfProbe` on its first frame.
+ *
+ *  Module scope rather than a field on the box: `PerfProbe` is the only thing
+ *  in the stage that already holds `gl`, and every question worth asking of it
+ *  is a one-off from a console. Publishing the OBJECT rather than a chosen
+ *  statistic is deliberate — the last three diagnostics each needed a different
+ *  number off it, and each one cost a source edit and a reload to get. */
+let probeRenderer: unknown = null;
+
+interface WindowPerfProbe {
+  shot: typeof shotPerfStats;
+  raster: typeof rasterCacheStats;
+  planes: typeof planeCacheStats;
+  mats: typeof layerMaterialPoolStats;
+  uploads: typeof canvasUploadStats;
+  renderer: () => unknown;
+  /** A compile is queued or running on the live renderer
+   *  (`rendererCompileBusy`): what a proof that steps frames one at a time
+   *  waits out, so a pipeline made in a draw means nothing warmed it, whatever
+   *  the host's speed. */
+  compileBusy: () => boolean;
+  stage?: (afterSequence?: number) => StagePerformanceDebugSnapshot | null;
+  stageSequence?: () => number | null;
+  subscribeStage?: (
+    listener: (sample: StagePresentationSample) => void,
+  ) => (() => void) | null;
+  /** GPU time per frame over the frames whose resolve landed in
+   *  `[fromMs, toMs)` (this document's `performance.now()`, every frame kept
+   *  when absent), and which timer measured it (`pending` before the renderer
+   *  was asked, `n/a` without one). */
+  gpu?: (fromMs?: number, toMs?: number) => GpuStats & { timer: PerfBox["gpuTimer"] };
+  profile?: JsSelfProfilerController;
+}
+
+const windowPerfProbe: WindowPerfProbe | null = PERF_HUD_ENABLED
+  ? {
+      shot: shotPerfStats,
+      raster: rasterCacheStats,
+      planes: planeCacheStats,
+      mats: layerMaterialPoolStats,
+      uploads: canvasUploadStats,
+      renderer: () => probeRenderer,
+      compileBusy: () => probeRenderer !== null && typeof probeRenderer === "object" && rendererCompileBusy(probeRenderer),
+      ...(PERF_SELF_PROFILE_ENABLED ? { profile: createJsSelfProfilerController() } : {}),
+    }
+  : null;
+
+if (windowPerfProbe !== null) {
+  (window as unknown as { __perfProbe?: WindowPerfProbe }).__perfProbe = windowPerfProbe;
+}
 
 export interface PerfBox {
   glFrames: number;
@@ -42,21 +163,53 @@ export interface PerfBox {
   /**
    * 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.
+   * EVERY RENDER OF THE LAST FRAME, like `drawCalls` beside it: each bin, each
+   * post pass and both split panes, summed (PerfProbe owns the reset). The
+   * outliner's per-layer badges are the number to trust for authoring
+   * decisions; this one is for watching a frame get heavier while you drag.
    */
   triangles: number;
+  /**
+   * Textures and geometries the renderer is HOLDING, off `info.memory`.
+   *
+   * The counterpart to `programs`, and the number that finally made a
+   * progressive slowdown visible. Every cache this lane owns reports itself
+   * (raster MB/entries, planes, mats), so when a document got slower on each
+   * successive pass while all of them stayed flat, there was nothing left to
+   * look at. These two are what an INSTANCE component's own textures and
+   * geometries land in, and nothing else on this line can see those.
+   */
+  textures: number;
+  geometries: 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>;
+  /** What `GpuTimer` found: `pending` until it has asked the renderer, then
+   *  the backend it times, or `n/a` when the renderer cannot time a pass. */
+  gpuTimer: GpuTimerKind | "pending" | "n/a";
+  /** The frames `GpuTimer` resolved (`perfGpuFrame`), made at the first, so
+   *  a stage without the HUD never allocates it. */
+  gpu: GpuSamples | null;
+}
+
+/** One frame `GpuTimer` resolved, into the box's ring: what the HUD's `gpu`
+ *  reading and `__perfProbe.gpu()` read. Nothing without the HUD. */
+export function perfGpuFrame(box: PerfBox, ms: number): void {
+  if (PERF_HUD_ENABLED) (box.gpu ??= new GpuSamples()).push(performance.now(), ms);
 }
 
 export function createPerfBox(): PerfBox {
-  return { glFrames: 0, drawCalls: 0, programs: 0, triangles: 0, spans: {} };
+  return {
+    glFrames: 0,
+    drawCalls: 0,
+    programs: 0,
+    triangles: 0,
+    textures: 0,
+    geometries: 0,
+    spans: {},
+    gpuTimer: "pending",
+    gpu: null,
+  };
 }
 
 /**
@@ -72,38 +225,57 @@ 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;
+  if (!PERF_HUD_ENABLED || PERF_SELF_PROFILE_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 {
+ *  THE PHASE IS LOAD-BEARING. The probe subscribes in the scheduler's
+ *  `finish` phase, which runs after the `render` phase, so it reads the
+ *  FINISHED frame in every layout. fiber only stands its own draw down for
+ *  jobs in the `render` phase (`hasUserJobsInPhase`) or a legacy positive
+ *  priority, so a finish-phase probe can never leave the camera-only layout
+ *  blank the way a positive-priority one could in v9. This replaces the v9
+ *  conditional (priority 2 with a presenter mounted, else a one-frame-stale
+ *  priority 0): the v10 phase gives the fresh reading unconditionally.
+ *
+ *  AND THE PROBE OWNS THE RESET. three's Info clears its per-frame counters on
+ *  its own rAF tick (`autoReset`), which has nothing to do with when this
+ *  stage draws: two draws inside one tick are read as one frame, and a
+ *  hidden tab, which gets no ticks, never resets at all. So the probe turns
+ *  that off and clears the counters at the START of every frame, and the
+ *  finish phase reads every render the frame made. At the start rather than
+ *  after the read, because a reader that runs after the frame (the
+ *  benchmark's resource rows, from the presentation callback) must still
+ *  find it. */
+export function PerfProbe({ box }: { box: PerfBox }): null {
   const gl = useThree((s) => s.gl);
+  useEffect(() => {
+    const info = infoOf(gl);
+    if (PERF_SELF_PROFILE_ENABLED || info === undefined) return;
+    const previous = info.autoReset;
+    info.autoReset = false;
+    return () => {
+      info.autoReset = previous ?? true;
+    };
+  }, [gl]);
   useFrame(() => {
+    if (!PERF_SELF_PROFILE_ENABLED) infoOf(gl)?.reset?.();
+  }, { phase: "start" });
+  useFrame(() => {
+    if (PERF_HUD_ENABLED && probeRenderer === null) probeRenderer = gl;
+    if (PERF_SELF_PROFILE_ENABLED) return;
     box.glFrames += 1;
-    const info = (gl as {
-      info?: {
-        render?: { calls?: number; drawCalls?: number; triangles?: number };
-        memory?: { programs?: number };
-      };
-    }).info;
+    const info = infoOf(gl);
     // 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;
+    box.textures = info?.memory?.textures ?? 0;
+    box.geometries = info?.memory?.geometries ?? 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
@@ -113,19 +285,97 @@ export function PerfProbe({ box, presenterMounted }: { box: PerfBox; presenterMo
       for (const [name, at] of pendingMarks) box.spans[name] = now - at;
       pendingMarks.clear();
     }
-  }, presenterMounted ? 2 : 0);
+  }, { phase: "finish" });
   return null;
 }
 
+/** The slice of three's renderer `Info` the probe reads and resets. */
+interface RendererInfo {
+  autoReset?: boolean;
+  reset?: () => void;
+  render?: { calls?: number; drawCalls?: number; triangles?: number };
+  memory?: { programs?: number; textures?: number; geometries?: number };
+}
+
+function infoOf(gl: unknown): RendererInfo | undefined {
+  return (gl as { info?: RendererInfo }).info;
+}
+
 const SAMPLE_MS = 500;
 
+/** The HUD's `scale` segment. */
+export function renderScaleText(reading: RenderScaleReading): string {
+  const next = reading.next === null ? "" : `→${reading.next.toFixed(2)}`;
+  const gpu = !reading.timer
+    ? "gpu n/a"
+    : reading.gpuP75Ms === null
+      ? "p75 -"
+      : `p75 ${reading.gpuP75Ms.toFixed(1)}/${reading.periodMs.toFixed(1)}ms`;
+  const late = reading.late === null ? "" : ` late ${reading.late.frames}/${reading.late.of}`;
+  const why = reading.reason === null ? "" : ` (${reading.reason})`;
+  return `scale ${reading.scale.toFixed(2)}${next} ${reading.mode} ${gpu}${late}${why}`;
+}
+
 /** 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 }) {
+ *  which scene is current; everything else is sampled here.
+ *
+ *  `quality` and the render scale are printed, and mirrored onto data
+ *  attributes, so a drop in either is VISIBLE while it happens: a downgrade
+ *  nobody can see is the kind that gets blamed on the renderer. */
+export function PerfHud({
+  box,
+  layers,
+  telemetry,
+  quality,
+  renderScale,
+  inset,
+}: {
+  box: PerfBox;
+  layers: number;
+  telemetry: StagePerformanceTelemetry;
+  quality: PresentationQuality;
+  /** The playback render scale's controller, read inside the interval. */
+  renderScale: RenderScaleController;
+  /** Where the chrome covers the stage; the HUD sits just inside it. */
+  inset: StageInset;
+}) {
   const [text, setText] = useState("perf…");
+  const [scale, setScale] = useState(1);
+  useEffect(() => {
+    if (windowPerfProbe === null) return;
+    const readStage = (afterSequence = 0): StagePerformanceDebugSnapshot | null =>
+      telemetry.debugSnapshot(afterSequence);
+    const readStageSequence = (): number | null => telemetry.debugSampleSequence();
+    windowPerfProbe.stage = readStage;
+    windowPerfProbe.stageSequence = readStageSequence;
+    const subscribeStage = (listener: (sample: StagePresentationSample) => void) =>
+      telemetry.subscribeDebugSample(listener);
+    // Event-shaped diagnostics are useful to pixel gates as well as to the
+    // sampling profiler. Publishing the function under the existing `?perf`
+    // boundary adds no per-frame work until a caller actually subscribes.
+    windowPerfProbe.subscribeStage = subscribeStage;
+    const readGpu = (fromMs?: number, toMs?: number): GpuStats & { timer: PerfBox["gpuTimer"] } => ({
+      timer: box.gpuTimer,
+      ...(box.gpu?.stats(fromMs, toMs) ?? NO_GPU_STATS),
+    });
+    windowPerfProbe.gpu = readGpu;
+    return () => {
+      if (windowPerfProbe.stage === readStage) delete windowPerfProbe.stage;
+      if (windowPerfProbe.stageSequence === readStageSequence) {
+        delete windowPerfProbe.stageSequence;
+      }
+      if (windowPerfProbe.subscribeStage === subscribeStage) delete windowPerfProbe.subscribeStage;
+      if (windowPerfProbe.gpu === readGpu) delete windowPerfProbe.gpu;
+    };
+  }, [box, telemetry]);
+  // A ref, not a dependency: the rung changes on its own schedule and must not
+  // restart the sampling interval (which would reset every delta baseline).
+  const qualityRef = useRef(quality);
+  qualityRef.current = quality;
   // rAF gap EMA, sampled continuously but folded into state only per interval.
   const uiMs = useRef(16.7);
   useEffect(() => {
+    if (PERF_SELF_PROFILE_ENABLED) return;
     let raf = 0;
     let last = performance.now();
     const tick = (): void => {
@@ -142,6 +392,7 @@ export function PerfHud({ box, layers }: { box: PerfBox; layers: number }) {
   // rAF-gap EMA has already recovered by sample time.
   const longTasks = useRef({ count: 0, maxMs: 0 });
   useEffect(() => {
+    if (PERF_SELF_PROFILE_ENABLED) return;
     if (typeof PerformanceObserver === "undefined") return;
     const observer = new PerformanceObserver((list) => {
       for (const entry of list.getEntries()) {
@@ -157,38 +408,173 @@ export function PerfHud({ box, layers }: { box: PerfBox; layers: number }) {
     return () => observer.disconnect();
   }, []);
   useEffect(() => {
+    if (PERF_SELF_PROFILE_ENABLED) return;
     let lastFrames = box.glFrames;
     let lastHits = rasterCacheStats().hits;
     let lastMisses = rasterCacheStats().misses;
+    let lastPerf = shotPerfStats();
+    let lastUploads = canvasUploadStats();
+    let lastStage = telemetry.snapshot();
     const timer = setInterval(() => {
       const stats = rasterCacheStats();
+      const perf = shotPerfStats();
+      const stage = telemetry.snapshot();
       const gps = ((box.glFrames - lastFrames) * 1000) / SAMPLE_MS;
       const hits = stats.hits - lastHits;
       const misses = stats.misses - lastMisses;
+      // Per-INTERVAL deltas, so the numbers describe the last half second
+      // rather than the session. `passes` is the double-draw detector: GL
+      // passes divided by the distinct playhead frames they were drawn for.
+      // 1.0 is one draw per frame; 2.0 means every frame is rendered twice,
+      // which is what a live video layer used to cost.
+      const drawDelta = perf.draws - lastPerf.draws;
+      const frameDelta = perf.frames - lastPerf.frames;
+      const passes = frameDelta > 0 ? drawDelta / frameDelta : 0;
+      // Splits a doubling into its two possible causes, which is the whole
+      // reason `sceneRenders` is counted: renders-per-frame above 1 means a
+      // second COMMIT upstream, while passes above renders means one render
+      // drawing twice. Printing only `passes` left the two indistinguishable,
+      // so every judgement about a doubling was made by reading code.
+      const renderDelta = perf.sceneRenders - lastPerf.sceneRenders;
+      const renders = frameDelta > 0 ? renderDelta / frameDelta : 0;
+      // Where those renders CAME FROM. `host` rising with `renders` means the
+      // editor pushed the commits down; `host` flat while `renders` climbs
+      // means state inside the canvas subtree is doing it.
+      const hostDelta = perf.runtimeRenders - lastPerf.runtimeRenders;
+      const hostRenders = frameDelta > 0 ? hostDelta / frameDelta : 0;
+      const rootDelta = perf.rootRenders - lastPerf.rootRenders;
+      const rootRenders = frameDelta > 0 ? rootDelta / frameDelta : 0;
+      // TRUE renderer entries per playhead frame, from the call sites rather
+      // than from ClockDriver advances. A plain scene is 1; a bin list, a post
+      // chain or a transition legitimately draw more, and this is the only
+      // number that says how much the GPU was actually asked to do.
+      const passDelta = perf.renderPasses - lastPerf.renderPasses;
+      const glPasses = frameDelta > 0 ? passDelta / frameDelta : 0;
+      const armDelta = perf.mediaArms - lastPerf.mediaArms;
+      const repaintDelta = perf.repaints - lastPerf.repaints;
+      // Which setter inside the canvas asked for the extra scene render.
+      const bumps: Array<[string, number]> = [
+        ["f", perf.bumpFonts - lastPerf.bumpFonts],
+        ["h", perf.bumpHtml - lastPerf.bumpHtml],
+        ["m", perf.bumpMedia - lastPerf.bumpMedia],
+        ["e", perf.bumpEnv - lastPerf.bumpEnv],
+      ];
+      const bumpText = bumps
+        .filter((row) => row[1] > 0)
+        .map((row) => `${row[0]}${row[1]}`)
+        .join("");
+      const compilePer = drawDelta > 0 ? (perf.compileMs - lastPerf.compileMs) / drawDelta : 0;
+      const advancePer = drawDelta > 0 ? (perf.advanceMs - lastPerf.advanceMs) / drawDelta : 0;
+      const watchPer = drawDelta > 0 ? (perf.watchMs - lastPerf.watchMs) / drawDelta : 0;
+      // The runtime subtree's whole render and commit — see `treeMs`. Printed
+      // beside `adv` because the pair is the split that matters: a seek is
+      // `tree` plus what the host component above it costs, and until this
+      // number existed the two were one unattributed remainder.
+      const treePer = drawDelta > 0 ? (perf.treeMs - lastPerf.treeMs) / drawDelta : 0;
+      // The frame program's two halves per draw, and how the transport's
+      // frames split between the clock listener (no commit) and a structure
+      // commit (with its whole cost per commit). `tree` above covers only the
+      // commits that rendered the runtime; `commit` is the one to read during
+      // playback.
+      const evalPer = drawDelta > 0 ? (perf.evaluateMs - lastPerf.evaluateMs) / drawDelta : 0;
+      const applyPer = drawDelta > 0 ? (perf.applyMs - lastPerf.applyMs) / drawDelta : 0;
+      const clockDelta = perf.clockFrames - lastPerf.clockFrames;
+      const commitDelta = perf.commitFrames - lastPerf.commitFrames;
+      const commitPer = commitDelta > 0 ? (perf.commitMs - lastPerf.commitMs) / commitDelta : 0;
+      const clockShare = drawDelta > 0 ? (100 * clockDelta) / drawDelta : 0;
+      // Request → publish → present, and everything lost between them. This
+      // is the signal the quality policy actually acts on, so it is worth
+      // seeing beside the numbers that explain WHY a window was slow.
+      //
+      // `renderPasses` is the runtime's ClockDriver advances here. The lane
+      // this came from counted true renderer entry points instead, which also
+      // sees the bins, transition and split presenters; without that counter
+      // `effective` reads as advances-per-presentation rather than
+      // passes-per-presentation.
+      const stageInterval = stagePerformanceInterval(lastStage, stage, drawDelta);
+      const stageText = stagePerformanceLine(stage, stageInterval, qualityRef.current);
+      // CanvasTexture upload requests: the one cost `gl.info` cannot see. Per
+      // PRESENTED frame when frames moved; raw interval totals otherwise,
+      // because uploads on a paused stage are themselves the anomaly worth
+      // printing (the budget for them is zero — see docs/shot.md).
+      const uploadsNow = canvasUploadStats();
+      const uploadDelta = uploadsNow.uploads - lastUploads.uploads;
+      const uploadMpx = uploadsNow.mpx - lastUploads.mpx;
+      lastUploads = uploadsNow;
+      const upText =
+        uploadDelta > 0
+          ? frameDelta > 0
+            ? ` · up ${(uploadDelta / frameDelta).toFixed(1)}/${(uploadMpx / frameDelta).toFixed(1)}MPx`
+            : ` · up ${uploadDelta}/${uploadMpx.toFixed(1)}MPx paused`
+          : "";
+      lastStage = stage;
       lastFrames = box.glFrames;
       lastHits = stats.hits;
       lastMisses = stats.misses;
+      lastPerf = perf;
       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}`,
-      );
+      // GPU time per frame over the frames resolved since the last sample; a
+      // dash when nothing drew.
+      const sampledAt = performance.now();
+      const gpu = box.gpu?.stats(sampledAt - SAMPLE_MS, sampledAt) ?? NO_GPU_STATS;
+      const gpuText =
+        box.gpuTimer === "n/a"
+          ? "n/a"
+          : gpu.p50Ms === null || gpu.p95Ms === null
+            ? "-"
+            : `${gpu.p50Ms.toFixed(1)}/${gpu.p95Ms.toFixed(1)}ms`;
+      // The render scale, off the controller in this interval: no React state
+      // above the runtime moves per window.
+      const reading = renderScale.reading();
+      // Only while something is actually drawing: a paused stage draws nothing,
+      // and printing "passes 0.0 · compile 0.0ms" there would read as a broken
+      // renderer rather than an idle one.
+      const drawText =
+        drawDelta > 0
+          ? ` · passes ${passes.toFixed(2)} · renders ${renders.toFixed(2)} · host ${hostRenders.toFixed(2)} · root ${rootRenders.toFixed(2)} · gl ${glPasses.toFixed(2)} · arm ${armDelta}/rep ${repaintDelta}${bumpText === "" ? "" : ` · bump ${bumpText}`}${repaintDelta > 0 ? ` (${perf.lastRepaintTrigger})` : ""} · compile ${compilePer.toFixed(1)}ms · adv ${advancePer.toFixed(1)}ms · watch ${watchPer.toFixed(1)}ms · tree ${treePer.toFixed(1)}ms · eval ${evalPer.toFixed(2)}ms · apply ${applyPer.toFixed(2)}ms · clock ${clockShare.toFixed(0)}% · commit ${commitDelta}/${commitPer.toFixed(1)}ms`
+          : "";
+      const line =
+        `gl/s ${gps.toFixed(0)} · ui ${uiMs.current.toFixed(1)}ms · gpu ${gpuText} · draws ${box.drawCalls} · ` +
+        `tris ${box.triangles} · progs ${box.programs} · ` +
+        `raster ${(stats.bytes / 1e6).toFixed(0)}MB/${stats.entries} (+${hits}h ${misses}m) · ` +
+        `planes ${planeCacheStats().entries} · ` +
+        `mats ${layerMaterialPoolStats().parked} · ` +
+        `tex ${box.textures}/geo ${box.geometries}${upText} · ` +
+        `layers ${layers} · ${renderScaleText(reading)} · ${stageText}${drawText}${ltText}${spans}`;
+      setText(line);
+      setScale(reading.scale);
+      // ── AND SOMEWHERE THE DOCK CANNOT COVER ─────────────────────────────
+      //
+      // The overlay below is inside the stage IFRAME, and `.stage-frame` is
+      // `position: fixed; inset: 0`: the iframe fills the whole window and
+      // every chrome panel is docked above it. The iframe is one element in the
+      // chrome's stacking order, so no z-index in here can beat a docked cell:
+      // the HUD sits in the visible canvas's corner, but a long line still
+      // runs under the right column. A reading that has to be transcribed off
+      // a translucent overlay is also the one thing nobody does accurately.
+      //
+      // So the line also goes to `window.__perf`, which can be grabbed at any
+      // instant from the console, and under `?perf=log` to the console itself
+      // for watching a number move over a whole playback.
+      (window as unknown as { __perf?: string }).__perf = line;
+      if (PERF_LOG_ENABLED) console.log("[perf] " + line);
     }, SAMPLE_MS);
     return () => clearInterval(timer);
-  }, [box, layers]);
+  }, [box, layers, telemetry, renderScale]);
+  if (PERF_SELF_PROFILE_ENABLED) return null;
   return (
     <div
       style={{
         position: "fixed",
-        left: 8,
-        bottom: 8,
+        // Just inside the docked cells, in the corner of the visible canvas.
+        // A literal once put it under the timeline, where it was unreadable.
+        left: inset.left + 8,
+        top: inset.top + 8,
         zIndex: 40,
         padding: "4px 8px",
         borderRadius: 4,
@@ -199,6 +585,10 @@ export function PerfHud({ box, layers }: { box: PerfBox; layers: number }) {
         whiteSpace: "nowrap",
       }}
       data-testid="perf-hud"
+      data-quality-level={quality.level}
+      data-quality-dpr={quality.dpr}
+      data-quality-raster={quality.rasterScale}
+      data-render-scale={scale}
     >
       {text}
     </div>