@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/stagePerformanceTelemetry.ts

@@ -0,0 +1,717 @@
+// Correlated stage frame telemetry and the one-second window sampler behind
+// the editor's fps readout and the playback gate.
+//
+// The minimal sampler is product-always WHILE PLAYING: one timestamp when a
+// frame is requested and one when the runtime confirms that revision was
+// presented. Those readings used to control backing-store DPR; the ladder is
+// gone (adaptivePresentation.ts), so a closed window is reported, with the
+// GPU frame times that landed in it (`noteGpu`). Each presented frame of the
+// transport goes to the playback render scale (`subscribePresented`), whose
+// deadlines it is (renderScaleController.ts), timed by its request; its
+// windows are its own, and this one's rate is a readout.
+// Rich history is opt-in under `?perf=1`; when it is off, paused scrubs and
+// incidental redraws perform no telemetry-only wall-clock reads or
+// ring-buffer work.
+import { ADAPTIVE_WINDOW_MS } from "./adaptivePresentation.js";
+import type { AdaptivePresentationLevel, PresentationQuality } from "./adaptivePresentation.js";
+import { canonicalJSON } from "@dailies-studio/contract";
+import { DEFAULT_SHOT_FPS } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+
+export interface StageFrameRequest {
+  requestSequence: number;
+  frame: number;
+  requestedAt: number | null;
+}
+
+interface PublishedFrame extends StageFrameRequest {
+  publicationToken: number;
+}
+
+export interface StagePresentedFrameLike {
+  revision: number;
+  frame: number;
+  /** Editor publication identity echoed by ShotRuntime. */
+  presentationToken?: number;
+}
+
+export interface StagePerformanceSnapshot {
+  requestedFrames: number;
+  publishedFrames: number;
+  presentedFrames: number;
+  matchedPresentations: number;
+  unmatchedPresentations: number;
+  droppedPublications: number;
+  requestCoalesced: number;
+  publicationCoalesced: number;
+  latencySamples: number;
+  latencyP50Ms: number | null;
+  latencyP95Ms: number | null;
+  latencyP99Ms: number | null;
+  lastWindowP95Ms: number | null;
+  lastWindowPresentedFrames: number;
+  lastWindowExpectedFrames: number;
+  lastWindowDroppedPublications: number;
+  lastPresentedRevision: number;
+  qualityLevel: AdaptivePresentationLevel;
+}
+
+/** One closed adaptive window: what the stage actually put on screen against
+ *  what the document's cadence asked of it. `durationMs` is carried rather
+ *  than assumed so a reader can turn frames into a rate without importing
+ *  `ADAPTIVE_WINDOW_MS`. */
+export interface StagePerformanceWindow {
+  presentedFrames: number;
+  expectedFrames: number;
+  droppedPublications: number;
+  durationMs: number;
+  /** The p95 of the GPU frame times that landed in the window (`noteGpu`),
+   *  or null when none did. */
+  gpuP95Ms: number | null;
+}
+
+export interface StagePerformanceInterval {
+  requestedFrames: number;
+  publishedFrames: number;
+  presentedFrames: number;
+  matchedPresentations: number;
+  unmatchedPresentations: number;
+  droppedPublications: number;
+  requestCoalesced: number;
+  publicationCoalesced: number;
+  renderPasses: number;
+  effectivePasses: number;
+}
+
+export interface StagePresentationSample {
+  sequence: number;
+  publicationToken: number;
+  requestSequence: number;
+  frame: number;
+  revision: number;
+  requestedAt: number;
+  presentedAt: number;
+  latencyMs: number;
+}
+
+export interface StageDebugDocumentIdentity {
+  id: string;
+  name: string;
+  title: string | null;
+  size: [number, number];
+  fps: [number, number];
+  scenes: Array<[string, number, number]>;
+}
+
+export interface StageDebugDocumentPresentation {
+  frame: number;
+  revision: number;
+  presentedAt: number;
+}
+
+/**
+ * The document that crossed the stage bridge, plus proof that this exact
+ * object reached ShotRuntime's presentation callback.
+ *
+ * Object identity stays stage-local. Only the compact structural identity is
+ * published, so a diagnostics poll never serializes the authored document or
+ * puts its size on the measured frame path.
+ */
+export interface StageDebugDocumentSnapshot {
+  identity: StageDebugDocumentIdentity;
+  fingerprint: string | null;
+  fingerprintError: string | null;
+  loadSequence: number;
+  loadedAtSampleSequence: number;
+  presentationCount: number;
+  lastPresentation: StageDebugDocumentPresentation | null;
+}
+
+const DEBUG_DOCUMENT_FINGERPRINT_PREFIX = "sha256-canonical-json-v1:";
+
+/**
+ * Whole-value document fingerprint shared by the stage and browser gate.
+ *
+ * `canonicalJSON` sorts object keys and preserves array order, so equivalent
+ * values do not depend on insertion order while every authored array remains
+ * order-sensitive. SHA-256 makes accidental acceptance of different values
+ * computationally negligible. This is an audit identity, not an authenticity
+ * claim: both sides run in the same local process and no secret is involved.
+ */
+export async function debugDocumentFingerprint(doc: Doc3D): Promise<string> {
+  if (globalThis.crypto?.subtle === undefined) {
+    throw new Error("Web Crypto SHA-256 is unavailable");
+  }
+  const bytes = new TextEncoder().encode(canonicalJSON(doc));
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+  return (
+    DEBUG_DOCUMENT_FINGERPRINT_PREFIX +
+    Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")
+  );
+}
+
+/** Read-only opt-in query used by the browser benchmark. */
+export interface StagePerformanceDebugSnapshot {
+  counters: StagePerformanceSnapshot;
+  samples: readonly StagePresentationSample[];
+  latestSampleSequence: number;
+  /** First row retained. A cursor is stale when `cursor + 1` is below it. */
+  oldestSampleSequence: number;
+  /** Present only in rich diagnostics, and only while a document is loaded. */
+  document: StageDebugDocumentSnapshot | null;
+}
+
+export interface StagePerformanceTelemetryOptions {
+  rich?: boolean;
+  now?: () => number;
+  richLatencyCapacity?: number;
+  /** Whether the stage is on screen at all. A hidden tab has its rAF throttled
+   *  to seconds apart, so the transport requests almost nothing and the window
+   *  reads as a scene in deep trouble — which it is not. Defaults to the
+   *  document's own visibility; a test passes its own. */
+  visible?: () => boolean;
+}
+
+const DEFAULT_RICH_LATENCY_CAPACITY = 512;
+const MAX_PENDING_PUBLICATIONS = 512;
+
+export class StagePerformanceTelemetry {
+  readonly #now: () => number;
+  readonly #visible: () => boolean;
+  readonly #richLatencyCapacity: number;
+  readonly #qualityListeners = new Set<() => void>();
+  /** Told once per CLOSED window, with what that window actually held. The
+   *  quality listeners above fire only when the policy changes rung, which is
+   *  rare by design; a readout of the current rate needs every window. */
+  readonly #windowListeners = new Set<(window: StagePerformanceWindow) => void>();
+  /** Told of every frame of the transport that reached the canvas, with the
+   *  clock read its request took and its frame (`subscribePresented`). */
+  readonly #presentedListeners = new Set<(requestedAt: number, frame: number) => void>();
+  readonly #debugSampleListeners = new Set<(sample: StagePresentationSample) => void>();
+  readonly #pendingByToken = new Map<number, PublishedFrame>();
+  readonly #windowLatencies: number[] = [];
+  readonly #windowGpu: number[] = [];
+  readonly #richSamples: StagePresentationSample[] = [];
+
+  #rich: boolean;
+  #debugDocumentSource: Doc3D | null = null;
+  #debugDocument: StageDebugDocumentSnapshot | null = null;
+  #debugDocumentLoadSequence = 0;
+  #playing = false;
+  // The lane's own default rate until `setFrameRate` hears from a document,
+  // with the period derived exactly as that setter derives it.
+  #fpsNumerator = DEFAULT_SHOT_FPS.num;
+  #fpsDenominator = DEFAULT_SHOT_FPS.den;
+  #expectedFrameRemainder = 0;
+  #windowStartedAt = 0;
+  #requestSequence = 0;
+  #publishSequence = 0;
+  #sampleSequence = 0;
+  #lastPresentedRevision = 0;
+  #requestedFrames = 0;
+  #publishedFrames = 0;
+  #presentedFrames = 0;
+  #matchedPresentations = 0;
+  #unmatchedPresentations = 0;
+  #droppedPublications = 0;
+  #requestCoalesced = 0;
+  #publicationCoalesced = 0;
+  #lastWindowP95Ms: number | null = null;
+  #windowPresentedFrames = 0;
+  #windowDroppedPublications = 0;
+  #lastWindowPresentedFrames = 0;
+  #lastWindowExpectedFrames = 0;
+  #lastWindowDroppedPublications = 0;
+
+  constructor(options: StagePerformanceTelemetryOptions = {}) {
+    this.#rich = options.rich === true;
+    this.#now = options.now ?? (() => performance.now());
+    this.#visible =
+      options.visible ??
+      (() => typeof document === "undefined" || document.visibilityState === "visible");
+    const requestedCapacity = options.richLatencyCapacity ?? DEFAULT_RICH_LATENCY_CAPACITY;
+    this.#richLatencyCapacity = Number.isFinite(requestedCapacity)
+      ? Math.max(1, Math.round(requestedCapacity))
+      : DEFAULT_RICH_LATENCY_CAPACITY;
+  }
+
+  setRichEnabled(enabled: boolean): void {
+    this.#rich = enabled;
+    if (enabled) return;
+    this.#richSamples.length = 0;
+    this.#debugSampleListeners.clear();
+    this.#debugDocumentSource = null;
+    this.#debugDocument = null;
+  }
+
+  /**
+   * Records the bridge's accepted document for local rich diagnostics.
+   *
+   * The source reference never leaves this class. `present` receives the
+   * document rendered by StageApp and only confirms a presentation when the
+   * references are identical. A late callback from a replaced document,
+   * including one that reused the same persisted id, therefore cannot satisfy
+   * the browser gate.
+   */
+  setDebugDocument(doc: Doc3D | null): void {
+    if (!this.#rich || this.#debugDocumentSource === doc) return;
+    this.#debugDocumentSource = doc;
+    if (doc === null) {
+      this.#debugDocument = null;
+      return;
+    }
+    this.#debugDocumentLoadSequence += 1;
+    const debugDocument: StageDebugDocumentSnapshot = {
+      identity: {
+        id: doc.id,
+        name: doc.name,
+        title: doc.title ?? null,
+        size: [doc.size.width, doc.size.height],
+        fps: [doc.fps.num, doc.fps.den],
+        scenes: doc.scenes.map((id) => {
+          const scene = doc.scenesById[id]!;
+          return [id, scene.durationFrames, Object.keys(scene.layersById).length];
+        }),
+      },
+      fingerprint: null,
+      fingerprintError: null,
+      loadSequence: this.#debugDocumentLoadSequence,
+      loadedAtSampleSequence: this.#sampleSequence,
+      presentationCount: 0,
+      lastPresentation: null,
+    };
+    this.#debugDocument = debugDocument;
+    // The canonical walk and digest exist only under rich diagnostics. The
+    // generation checks keep a late digest from labelling a replacement doc.
+    void debugDocumentFingerprint(doc).then(
+      (fingerprint) => {
+        if (this.#debugDocumentSource !== doc || this.#debugDocument !== debugDocument) return;
+        debugDocument.fingerprint = fingerprint;
+      },
+      (error: unknown) => {
+        if (this.#debugDocumentSource !== doc || this.#debugDocument !== debugDocument) return;
+        debugDocument.fingerprintError = error instanceof Error ? error.message : String(error);
+      },
+    );
+  }
+
+  setFrameRate(fps: { num: number; den: number } | null): void {
+    if (
+      fps === null ||
+      !Number.isFinite(fps.num) ||
+      !Number.isFinite(fps.den) ||
+      fps.num <= 0 ||
+      fps.den <= 0
+    ) {
+      return;
+    }
+    this.#fpsNumerator = fps.num;
+    this.#fpsDenominator = fps.den;
+    this.#expectedFrameRemainder = 0;
+  }
+
+  /** A document/topology replacement invalidates every outstanding token. */
+  resetPublications(): void {
+    this.#pendingByToken.clear();
+  }
+
+  setPlaying(playing: boolean): void {
+    if (playing === this.#playing) return;
+    this.#playing = playing;
+    this.#windowLatencies.length = 0;
+    this.#windowGpu.length = 0;
+    this.#expectedFrameRemainder = 0;
+    this.#lastWindowP95Ms = null;
+    this.#pendingByToken.clear();
+    this.#windowPresentedFrames = 0;
+    this.#windowDroppedPublications = 0;
+    this.#lastWindowPresentedFrames = 0;
+    this.#lastWindowExpectedFrames = 0;
+    this.#lastWindowDroppedPublications = 0;
+    if (playing) {
+      this.#windowStartedAt = this.#now();
+      return;
+    }
+    this.#windowStartedAt = 0;
+  }
+
+  request(frame: number): StageFrameRequest | null {
+    // A paused stage without the opt-in diagnostics has no latency policy to
+    // drive. Return the null token before allocating, reading the clock, or
+    // touching diagnostic counters.
+    if (!this.#playing && !this.#rich) return null;
+    const requestedAt = this.#now();
+    if (this.#playing) this.#rollWindowsBefore(requestedAt);
+    this.#requestedFrames += 1;
+    this.#requestSequence += 1;
+    return { requestSequence: this.#requestSequence, frame, requestedAt };
+  }
+
+  coalesceRequest(request: StageFrameRequest | null): void {
+    if (request === null) return;
+    this.#requestCoalesced += 1;
+  }
+
+  publish(request: StageFrameRequest | null): number | null {
+    if (request === null) return null;
+    this.#publishedFrames += 1;
+    this.#publishSequence += 1;
+    const publicationToken = this.#publishSequence;
+    this.#pendingByToken.set(publicationToken, { ...request, publicationToken });
+    if (this.#pendingByToken.size > MAX_PENDING_PUBLICATIONS) {
+      const oldest = this.#pendingByToken.keys().next().value as number | undefined;
+      if (oldest !== undefined) {
+        this.#pendingByToken.delete(oldest);
+        this.#publicationCoalesced += 1;
+        this.#droppedPublications += 1;
+        if (this.#playing) this.#windowDroppedPublications += 1;
+      }
+    }
+    return publicationToken;
+  }
+
+  present(info: StagePresentedFrameLike, document: Doc3D | null = null): void {
+    if (!this.#playing && !this.#rich) return;
+    const presentedAt = this.#now();
+    if (
+      this.#rich &&
+      document !== null &&
+      document === this.#debugDocumentSource &&
+      this.#debugDocument !== null
+    ) {
+      this.#debugDocument.presentationCount += 1;
+      this.#debugDocument.lastPresentation = {
+        frame: info.frame,
+        revision: info.revision,
+        presentedAt,
+      };
+    }
+    if (this.#playing) this.#rollWindowsBefore(presentedAt);
+    this.#presentedFrames += 1;
+    this.#lastPresentedRevision = Math.max(this.#lastPresentedRevision, info.revision);
+    const token = info.presentationToken;
+    const pending = token === undefined ? undefined : this.#pendingByToken.get(token);
+    if (pending === undefined || pending.frame !== info.frame) {
+      this.#unmatchedPresentations += 1;
+      if (this.#playing) this.#rollWindowsThrough(presentedAt);
+      return;
+    }
+
+    // Any older pending publication was superseded before it reached the
+    // canvas. Identity is the publication token, never the authored frame: a
+    // seek away and back may publish the same frame several times.
+    for (const [pendingToken, row] of this.#pendingByToken) {
+      if (row.publicationToken < pending.publicationToken) {
+        this.#publicationCoalesced += 1;
+        this.#droppedPublications += 1;
+        if (this.#playing) this.#windowDroppedPublications += 1;
+      }
+      if (row.publicationToken <= pending.publicationToken) this.#pendingByToken.delete(pendingToken);
+    }
+    this.#matchedPresentations += 1;
+    if (this.#playing) {
+      this.#windowPresentedFrames += 1;
+      this.#notifyPresented(pending.requestedAt ?? presentedAt, pending.frame);
+    }
+
+    if (pending.requestedAt === null) {
+      if (this.#playing) this.#rollWindowsThrough(presentedAt);
+      return;
+    }
+    const latency = Math.max(0, presentedAt - pending.requestedAt);
+    if (this.#rich) {
+      this.#pushRichSample({
+        publicationToken: pending.publicationToken,
+        requestSequence: pending.requestSequence,
+        frame: pending.frame,
+        revision: info.revision,
+        requestedAt: pending.requestedAt,
+        presentedAt,
+        latencyMs: latency,
+      });
+    }
+    if (!this.#playing) return;
+    this.#windowLatencies.push(latency);
+    this.#rollWindowsThrough(presentedAt);
+  }
+
+  /** One frame's GPU time, ms, as the stage's `GpuTimer` resolved it: into
+   *  the open window while playing, for the report's `gpuMs`. A paused
+   *  stage's draws are dropped, as its presentations are. */
+  noteGpu(ms: number): void {
+    if (this.#playing && Number.isFinite(ms)) this.#windowGpu.push(ms);
+  }
+
+  /** Always 0. The DPR ladder is gone; the method survives for the HUD, the
+   *  gate and the counters that print it. The playback render scale is not a
+   *  rung of it: the canvas keeps its density (renderScaleController.ts). */
+  qualityLevel(): AdaptivePresentationLevel {
+    return 0;
+  }
+
+  /** Never fires. Kept so a caller written against the ladder still type
+   *  checks; nothing changes rung any more. */
+  subscribeQuality(listener: () => void): () => void {
+    this.#qualityListeners.add(listener);
+    return () => this.#qualityListeners.delete(listener);
+  }
+
+  /**
+   * Every closed, VISIBLE window: what was presented against what the cadence
+   * asked for.
+   *
+   * Windows roll only while playing (`#rollWindowsBefore`/`Through` both guard
+   * on `#playing`), so this is one call a second during playback and silent
+   * otherwise. A window nobody could see returns early above without notifying:
+   * a hidden tab presents nothing, and reporting 0 fps for it would be a
+   * measurement of the tab rather than of the scene.
+   */
+  subscribeWindow(listener: (window: StagePerformanceWindow) => void): () => void {
+    this.#windowListeners.add(listener);
+    return () => this.#windowListeners.delete(listener);
+  }
+
+  /**
+   * Every frame of the transport that reached the canvas while playing, with
+   * its document frame, timed by the clock read its request took (`request`,
+   * in the transport's tick before the frame was drawn): the playback render
+   * scale's deadlines (renderScaleController.ts `presented`). Timed by the
+   * echo, after the draw in the same task, a frame drawn 10 ms slower than the
+   * one before it, in time for its refresh, followed it by more than a
+   * refresh and a half at 60 fps, late.
+   *
+   * A publication the transport made and the runtime presented, so neither a
+   * preparing pass's frames (the stage is not playing for this sampler), nor a
+   * superseded publication, nor a redraw of a frame already on screen, nor a
+   * frame the playback scale held off the canvas, which the runtime never
+   * echoes. One call per presented frame and nothing else while it plays.
+   */
+  subscribePresented(listener: (requestedAt: number, frame: number) => void): () => void {
+    this.#presentedListeners.add(listener);
+    return () => this.#presentedListeners.delete(listener);
+  }
+
+  snapshot(): StagePerformanceSnapshot {
+    const richLatencies = this.#richSamples.map((sample) => sample.latencyMs);
+    return {
+      requestedFrames: this.#requestedFrames,
+      publishedFrames: this.#publishedFrames,
+      presentedFrames: this.#presentedFrames,
+      matchedPresentations: this.#matchedPresentations,
+      unmatchedPresentations: this.#unmatchedPresentations,
+      droppedPublications: this.#droppedPublications,
+      requestCoalesced: this.#requestCoalesced,
+      publicationCoalesced: this.#publicationCoalesced,
+      latencySamples: this.#richSamples.length,
+      latencyP50Ms: percentile(richLatencies, 0.5),
+      latencyP95Ms: percentile(richLatencies, 0.95),
+      latencyP99Ms: percentile(richLatencies, 0.99),
+      lastWindowP95Ms: this.#lastWindowP95Ms,
+      lastWindowPresentedFrames: this.#lastWindowPresentedFrames,
+      lastWindowExpectedFrames: this.#lastWindowExpectedFrames,
+      lastWindowDroppedPublications: this.#lastWindowDroppedPublications,
+      lastPresentedRevision: this.#lastPresentedRevision,
+      qualityLevel: 0,
+    };
+  }
+
+  /**
+   * Exact samples after a caller-owned cursor. Null while rich diagnostics are
+   * disabled, so production callers cannot accidentally turn the ring on by
+   * reading it.
+   */
+  debugSnapshot(afterSequence = 0): StagePerformanceDebugSnapshot | null {
+    if (!this.#rich) return null;
+    const cursor = Number.isFinite(afterSequence) ? Math.max(0, Math.floor(afterSequence)) : 0;
+    const oldestSampleSequence = this.#richSamples[0]?.sequence ?? this.#sampleSequence + 1;
+    return {
+      counters: this.snapshot(),
+      samples: this.#richSamples
+        .filter((sample) => sample.sequence > cursor)
+        .map((sample) => ({ ...sample })),
+      latestSampleSequence: this.#sampleSequence,
+      oldestSampleSequence,
+      document:
+        this.#debugDocument === null
+          ? null
+          : {
+              ...this.#debugDocument,
+              identity: {
+                ...this.#debugDocument.identity,
+                size: [...this.#debugDocument.identity.size],
+                fps: [...this.#debugDocument.identity.fps],
+                scenes: this.#debugDocument.identity.scenes.map((scene) => [...scene]),
+              },
+              lastPresentation:
+                this.#debugDocument.lastPresentation === null
+                  ? null
+                  : { ...this.#debugDocument.lastPresentation },
+            },
+    };
+  }
+
+  /**
+   * O(1) cursor for callers that only need to ignore presentations that
+   * happened before they subscribed. Null keeps the rich-mode boundary
+   * explicit without copying or walking the retained sample ring.
+   */
+  debugSampleSequence(): number | null {
+    return this.#rich ? this.#sampleSequence : null;
+  }
+
+  /**
+   * Event-shaped access for the local profiler harness. Polling this ring once
+   * per animation frame would put the harness itself into the sampled stacks.
+   * Normal stages cannot subscribe because rich diagnostics are off, and an
+   * empty listener set adds no per-presentation work.
+   */
+  subscribeDebugSample(
+    listener: (sample: StagePresentationSample) => void,
+  ): (() => void) | null {
+    if (!this.#rich) return null;
+    this.#debugSampleListeners.add(listener);
+    return () => this.#debugSampleListeners.delete(listener);
+  }
+
+  #pushRichSample(sample: Omit<StagePresentationSample, "sequence">): void {
+    if (this.#richSamples.length >= this.#richLatencyCapacity) this.#richSamples.shift();
+    this.#sampleSequence += 1;
+    const row = { sequence: this.#sampleSequence, ...sample };
+    this.#richSamples.push(row);
+    for (const listener of this.#debugSampleListeners) {
+      try {
+        listener({ ...row });
+      } catch {
+        // Diagnostics cannot break the runtime's onPresented callback.
+      }
+    }
+  }
+
+  /** Close buckets strictly before an event, so a presentation exactly on the
+   * boundary completes the bucket whose cadence it satisfies. */
+  #rollWindowsBefore(now: number): void {
+    while (this.#playing && now > this.#windowStartedAt + ADAPTIVE_WINDOW_MS) {
+      this.#finishWindow();
+    }
+  }
+
+  /** Close the boundary bucket after its presentation has been attributed. */
+  #rollWindowsThrough(now: number): void {
+    while (this.#playing && now >= this.#windowStartedAt + ADAPTIVE_WINDOW_MS) {
+      this.#finishWindow();
+    }
+  }
+
+  #finishWindow(): void {
+    const durationMs = ADAPTIVE_WINDOW_MS;
+    const cadenceTotal = this.#expectedFrameRemainder + this.#fpsNumerator;
+    const wholeExpectedFrames = Math.floor(cadenceTotal / this.#fpsDenominator + 1e-9);
+    this.#expectedFrameRemainder =
+      cadenceTotal - wholeExpectedFrames * this.#fpsDenominator;
+    // The rational accumulator above is exact, so the reported cadence stays
+    // honest across fractional rates. Nothing judges it any more: the window
+    // is a readout, and the authored expectation is the honest denominator.
+    const expectedFrames = Math.max(1, wholeExpectedFrames);
+    // A window nobody could see is not evidence about this scene. Close the
+    // bucket and forget what it held.
+    if (!this.#visible()) {
+      this.#windowLatencies.length = 0;
+      this.#windowGpu.length = 0;
+      this.#windowPresentedFrames = 0;
+      this.#windowDroppedPublications = 0;
+      this.#windowStartedAt += ADAPTIVE_WINDOW_MS;
+      return;
+    }
+    const p95 = percentile(this.#windowLatencies, 0.95);
+    this.#lastWindowP95Ms = p95;
+    this.#lastWindowPresentedFrames = this.#windowPresentedFrames;
+    this.#lastWindowExpectedFrames = expectedFrames;
+    this.#lastWindowDroppedPublications = this.#windowDroppedPublications;
+    // READ BEFORE THE RESET: the three counters below are zeroed on the next
+    // line, and a listener that read them from the instance afterwards would
+    // report an empty window.
+    const closed: StagePerformanceWindow = {
+      presentedFrames: this.#windowPresentedFrames,
+      expectedFrames,
+      droppedPublications: this.#windowDroppedPublications,
+      durationMs,
+      gpuP95Ms: percentile(this.#windowGpu, 0.95),
+    };
+    this.#windowLatencies.length = 0;
+    this.#windowGpu.length = 0;
+    this.#windowPresentedFrames = 0;
+    this.#windowDroppedPublications = 0;
+    this.#windowStartedAt += ADAPTIVE_WINDOW_MS;
+    this.#notifyWindow(closed);
+  }
+
+  #notifyPresented(requestedAt: number, frame: number): void {
+    for (const listener of this.#presentedListeners) {
+      try {
+        listener(requestedAt, frame);
+      } catch {
+        // The window listeners' rule: a reader never breaks the runtime's
+        // presentation path.
+      }
+    }
+  }
+
+  #notifyWindow(window: StagePerformanceWindow): void {
+    for (const listener of this.#windowListeners) {
+      try {
+        listener(window);
+      } catch {
+        // A readout cannot break the runtime's presentation path, which is the
+        // same rule the sample listeners above follow.
+      }
+    }
+  }
+}
+
+/** Nearest-rank percentile, total over an empty or non-finite sample set. */
+export function percentile(values: readonly number[], quantile: number): number | null {
+  const finite = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (finite.length === 0) return null;
+  const q = Math.max(0, Math.min(1, quantile));
+  const index = Math.max(0, Math.ceil(q * finite.length) - 1);
+  return finite[index] ?? null;
+}
+
+export function stagePerformanceInterval(
+  before: StagePerformanceSnapshot,
+  after: StagePerformanceSnapshot,
+  renderPasses: number,
+): StagePerformanceInterval {
+  const presentedFrames = Math.max(0, after.presentedFrames - before.presentedFrames);
+  return {
+    requestedFrames: Math.max(0, after.requestedFrames - before.requestedFrames),
+    publishedFrames: Math.max(0, after.publishedFrames - before.publishedFrames),
+    presentedFrames,
+    matchedPresentations: Math.max(0, after.matchedPresentations - before.matchedPresentations),
+    unmatchedPresentations: Math.max(0, after.unmatchedPresentations - before.unmatchedPresentations),
+    droppedPublications: Math.max(0, after.droppedPublications - before.droppedPublications),
+    requestCoalesced: Math.max(0, after.requestCoalesced - before.requestCoalesced),
+    publicationCoalesced: Math.max(0, after.publicationCoalesced - before.publicationCoalesced),
+    renderPasses: Math.max(0, renderPasses),
+    effectivePasses: presentedFrames > 0 ? Math.max(0, renderPasses) / presentedFrames : 0,
+  };
+}
+
+const latencyText = (value: number | null): string => (value === null ? "-" : value.toFixed(1));
+
+/** One compact diagnostic segment consumed by PerfHud and benchmark capture. */
+export function stagePerformanceLine(
+  snapshot: StagePerformanceSnapshot,
+  interval: StagePerformanceInterval,
+  quality: PresentationQuality,
+): string {
+  const dpr = quality.dpr.toFixed(2);
+  return (
+    `frames req ${interval.requestedFrames}/pub ${interval.publishedFrames}/pres ${interval.presentedFrames}` +
+    ` · match ${interval.matchedPresentations}/unmatched ${interval.unmatchedPresentations}` +
+    ` · coal req ${interval.requestCoalesced}/pub ${interval.publicationCoalesced}/drop ${interval.droppedPublications}` +
+    ` · lat p50 ${latencyText(snapshot.latencyP50Ms)}/p95 ${latencyText(snapshot.latencyP95Ms)}/p99 ${latencyText(snapshot.latencyP99Ms)}ms` +
+    ` · passes ${interval.renderPasses} · effective ${interval.effectivePasses.toFixed(2)}` +
+    ` · q L${quality.level} dpr ${dpr} raster ${quality.rasterScale}`
+  );
+}