@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/renderScaleController.ts

@@ -0,0 +1,730 @@
+// The playback render scale's controller (the playback plan's Phase 5): the
+// share of the display's density a played frame renders at, lowered only while
+// played frames miss their deadline and the GPU's measured time says the
+// drawing is why. The stage hands it to the runtime as
+// `ShotRuntimeProps.presentationScale`, whose child asks it once per played
+// frame and draws the frame at that scale into an offscreen target, never
+// resizing the canvas (packages/shot/src/presentationScale.ts).
+//
+// ── A REAL PROBLEM, AND THE GPU'S ──────────────────────────────────────────
+//
+// Two inputs, and a step down needs both:
+//
+// - THE DEADLINES. Every frame of the transport that reaches the canvas, as
+//   the stage's telemetry matches the runtime's echo to its publication
+//   (`presented`), timed by the clock read its request took before it was
+//   drawn: a gap between two frames is the first one's draw and the wait for
+//   the next refresh, so a frame drawn slower than the one before, in time
+//   for its refresh, is not late. A frame is late when it follows the one
+//   before by more than its cadence holds a frame on a 60 Hz display, plus
+//   half a refresh (`deadlineMs`), or when a refresh went by without a frame
+//   and it skipped a document frame (`MISSED_REFRESH_MS`): the transport runs
+//   on wall time, so a stage that cannot keep up skips frames rather than
+//   showing them late, and at 24, 25 and 50 fps a stage held to 20, 20 and 30
+//   fps shows only gaps the cadence shows too. A late frame counts once,
+//   however late, and a window has a problem only when `LATE_SHARE` of its
+//   frames came late: one long stall is one late frame, where an fps average
+//   reads it as many.
+// - THE GPU'S TIME. three's timestamp queries time the render passes and
+//   nothing outside them (gpuTimer.ts). A frame missed because a texture
+//   uploaded, a pipeline compiled, a raster was cut or the main thread was
+//   busy costs the same at any resolution, and none of that is in the GPU's
+//   time, so such a film misses deadlines with its GPU time under the budget
+//   and never steps. A GPU whose clocks fell with such a film's load can read
+//   over it (cero's on the integrated GPU did): then the step's own verdict
+//   undoes it ("A STEP DOWN MUST PAY").
+//
+// Neither alone. GPU timestamps follow the GPU's clocks, and a lightly loaded
+// GPU lowers its clocks, so its frame's milliseconds rise toward the period
+// while it still has headroom (the RTX 3060 Laptop's graphics clock ranged
+// 210 to 1965 MHz within single runs). Stepping on GPU time alone, the
+// controller stepped down with every deadline met, and judged a step's relief
+// by clocks coming back.
+//
+// ── THE RULES ──────────────────────────────────────────────────────────────
+//
+// - The budget is the document's frame period, and the steps are 1, 0.85, 0.7
+//   and 0.5 of the display's density (`RENDER_SCALE_STEPS`).
+// - A window is the document's frame rate's worth of GPU samples, or a second
+//   of them once it holds `MIN_WINDOW_SAMPLES`, whichever closes it first:
+//   frames dropped to a GPU that is behind would otherwise stretch a window
+//   over several seconds, and three's WebGL timer loses the queries of the
+//   frames drawn while a resolve is out, so there it sees one frame in two or
+//   three. Its deadlines are the frames presented while it gathered them. With
+//   fewer than `MIN_WINDOW_SAMPLES` of those it says nothing of deadlines: it
+//   steps nothing down and judges no step.
+// - A WINDOW IS ONE SHOT'S (`PresentationFrame.shot`). A frame of another
+//   Shot ends the window in progress, judged if it holds `MIN_WINDOW_SAMPLES`
+//   and dropped if not, and the `SAMPLE_LAG_FRAMES` samples after it are
+//   dropped too, the old Shot's last frames' that land after its ask. No gap
+//   ends or starts at a cut's frame (`PresentationFrame.cut`): the one ending
+//   there follows another picture, or a jump of the transport (a loop's wrap,
+//   a seek), and the one starting there is the cut's own draw, its compiles
+//   and uploads, which no resolution buys back. Two Shots draw two pictures,
+//   so a p75 of both describes neither, and a step is judged by its own
+//   Shot's windows ("A STEP DOWN MUST PAY").
+// - A window whose frames miss their deadline while its GPU p75 is over
+//   `DOWN_SHARE` of the period steps DOWN, predictively: to the largest step
+//   s' predicted to fit under it. A p75 over the whole period is a severe miss
+//   and lands at the next frame; every other step lands at a cut, because
+//   pixel-sized post effects the chain cannot keep at the canvas's size (the
+//   tilt-shift spread, the bloom chain) change their look with the scale. A
+//   later window that steps nothing down, its deadlines met or its GPU inside
+//   the budget, withdraws a step still waiting for its cut.
+// - `UP_WINDOWS` windows in a row whose prediction puts the step above under
+//   `UP_SHARE` of the period step UP one, at a cut, late frames or not: a film
+//   late for its main thread is made no later by pixels its GPU has room for.
+//   The gap between the two shares is the hysteresis. Under DVFS the rule can
+//   only err toward staying: below a step, a GPU with headroom lowers its
+//   clocks, so its time there overstates what the step above costs once its
+//   clocks follow the load up. And a step up that puts the GPU's time over the
+//   budget with every deadline met stays, where on GPU time alone it stepped
+//   back down, and climbed again four windows later.
+// - THE PREDICTION. A frame below 1 is its own passes, which shrink with the
+//   area, and one pass up to the canvas, which covers the canvas whatever the
+//   scale (gpuTimer.ts times it apart): the present, three's output pass drawn
+//   at the canvas's density, for a Shot without post, or the copy of P for one
+//   with. So a step s' costs the window's content p75 times (s'/s)^2, plus the
+//   present's p75 at every scale, plus the copy's p75 when s' is below 1.
+//   Folded into the per-pixel term instead, the copy priced every step up too
+//   dear, and a film that fits at full density could stay below it for good.
+//   Priced as a copy, the present left a step up to 1 a canvas pass too cheap:
+//   a film whose output pass costs more than the hysteresis stepped up into a
+//   window over the budget, and down again, every few windows. A frame at 1
+//   draws the present's pass as three's own output pass, untagged, and a Shot
+//   with post draws none, so the two are each Shot's own, from its last window
+//   below 1 (`CanvasPasses`), and a window at 1 takes its Shot's present out of
+//   its time before the time scales. Counted in the per-pixel term and again
+//   whole, the output pass priced every step down from 1 too dear and chose a
+//   step lower than the film needed. A Shot that has not drawn below 1 is
+//   priced with the last window's passes below 1, another Shot's, which may be
+//   the other kind; before any, with none, which errs toward the higher step,
+//   and the next window takes another. The s^2 model is conservative upward
+//   besides: a pass's fixed cost does not shrink with the area, so a
+//   measurement below a step overstates it.
+// - The window after every step is not judged: the timer's samples land one
+//   to three frames late, and the first frames at a new size allocate.
+// - A STEP DOWN MUST PAY, in deadlines. Each Shot's step down is on trial
+//   until the first window of that Shot at the step's scale or below judges
+//   it (`#trials`). A window of another Shot says nothing of the step, and a
+//   step that waits for a cut is followed by the next Shot's windows: compared
+//   with them, a heavier Shot read as no relief, and a lighter one as relief.
+//   Another Shot's step down meanwhile leaves it on trial, judged below its
+//   scale. With one trial for the film the later step took its place, and the
+//   first stayed in force with no verdict: two Shots of a film late for its
+//   main thread, each stepping in turn, settled at 0.7 with a floor in each,
+//   though no step had paid. A scale above a step's ends its trial, the step
+//   no longer in force. The step paid when that window met its deadlines,
+//   whatever its GPU time: a GPU whose load fell lowers its clocks, so its
+//   time no longer falls with its work. Still late, it paid when its frames
+//   came faster (`typicalGap`) and its GPU p75 fell, each by `RELIEF_SHARE`:
+//   both, because frames that came faster while the GPU's time held came
+//   faster for something else, and GPU time that fell while the frames came
+//   no faster was not what held them (a film bound by its main thread: on GPU
+//   time alone, the integrated GPU kept cero at 0.85 though it played 24 to 26
+//   fps of 60 at every scale). Otherwise the step bought nothing, as it does
+//   for a film whose GPU time is draw calls and fixed passes, not pixels,
+//   which draws as long at 0.5 as at 1 and pays the copy on top. Such a step
+//   is undone at the next cut, back to the scale it was taken from with every
+//   step taken after it, whatever the windows before that cut say, and no
+//   window of that Shot steps below the scale the step was taken from until
+//   conditions change: one of its windows at that
+//   scale over `RETRY_LOAD` times the GPU load that prompted the step, or
+//   another Project, canvas size, mode or timer. Another Shot is not held back
+//   by it. Before this rule such a film stepped down window after window, each
+//   step predicted to fit, to the lowest step, and stayed there, softer and
+//   slower than at full density.
+// - A transition window keeps the scale its first frame got
+//   (`PresentationSchedule`), and its frames are no samples and no deadlines:
+//   a dissolve draws both Shots, and a step it decided could land only at its
+//   own closing cut, softening the Shot after it to pay for frames already
+//   gone.
+// - Pause draws at 1, because the child asks nothing while paused, and a
+//   stopped controller answers 1 whoever asks. What it settled on is kept for
+//   the next Play of the same Project at the same canvas size (`resting`, for
+//   which the stage holds its scaled targets while paused): another Project,
+//   or a canvas of another size, starts again from the top.
+// - With no timer, Auto stays at 1: nothing measured, nothing lowered.
+//
+// `full` pins 1. `fast` is the steps from 0.7 down: it starts there, steps to
+// 0.5 when the GPU needs it, and never goes above 0.7.
+//
+// ── THE THRESHOLDS ─────────────────────────────────────────────────────────
+//
+// Gate G1 (2026-10-24: an RTX 3060 Laptop on WebGPU, six films at device scale
+// 1.5 and 2) measured GPU p95 at 0.5 to 3.7 ms against frame periods of 16.7
+// to 41.7 ms, at most 0.15 of a period. That is far under `DOWN_SHARE`, so
+// Auto never leaves 1 on such a GPU and full density alone is safe there. On
+// the Linux test box's integrated GPU (AMD RDNA 2 through Vulkan, headless,
+// device scale 2), tabs-a-launch-film played 19.2 fps of 60 at full density
+// with a GPU p50 of 22 ms, and 26.9 to 27.8 at Auto, stepped to 0.5, with
+// 11 ms. `LATE_SHARE` and `RELIEF_SHARE` are this rule's own, and no run has
+// tuned them yet. With skipped frames counted, a fifth is the same bar at every
+// rate: a stage that shows under five sixths of a film's frames, each of its
+// frames skipping at most one. A 24 fps stage held to 20 fps, every frame
+// three refreshes, skips one frame in five, the bar exactly, so whether its
+// window reads late turns on where the window's edges fall.
+import { DEFAULT_SHOT_FPS } from "@dailies-studio/shot/doc";
+import type { PresentationFrame, PresentationScaleSource } from "@dailies-studio/shot";
+import type { PlaybackResolution } from "../bridgeTypes.js";
+import { percentile } from "./stagePerformanceTelemetry.js";
+
+/** The scales a played frame may render at, as shares of the display's
+ *  density, highest first. */
+export const RENDER_SCALE_STEPS: readonly number[] = [1, 0.85, 0.7, 0.5];
+/** `fast`: the steps from this one down. */
+export const FAST_RENDER_SCALE = 0.7;
+/** A window whose frames miss their deadline steps down while its GPU p75 is
+ *  over this share of the frame period. */
+export const DOWN_SHARE = 0.8;
+/** One over the whole period is severe: it lands at the next frame. */
+export const SEVERE_SHARE = 1;
+/** A window is clean when the step above is predicted under this share. */
+export const UP_SHARE = 0.7;
+/** Clean windows in a row before a step up. */
+export const UP_WINDOWS = 4;
+/** A window misses its deadlines when this share of its presented frames, or
+ *  more, came late (`deadlineMs`). */
+export const LATE_SHARE = 0.2;
+/** A window closes after this long once it holds `MIN_WINDOW_SAMPLES`: the
+ *  second the stage's telemetry windows span (`ADAPTIVE_WINDOW_MS`,
+ *  adaptivePresentation.ts), restated so this pure class imports no React. */
+export const WINDOW_MS = 1_000;
+/** The fewest samples a window closed by its second holds, and the fewest
+ *  presented frames that say anything of its deadlines. */
+export const MIN_WINDOW_SAMPLES = 8;
+/** A step down whose Shot's next window is still late paid when that window's
+ *  typical gap and its GPU p75 each fell by at least this share. */
+export const RELIEF_SHARE = 0.1;
+/** A step that did not pay is tried again once the load at the scale it was
+ *  taken from is this many times the one that prompted it. */
+export const RETRY_LOAD = 1.25;
+/** The frames a timer sample lands after its draw, at most (gpuTimer.ts): the
+ *  samples dropped after a Shot change, the old Shot's. */
+export const SAMPLE_LAG_FRAMES = 3;
+/** The most gaps a window keeps, its latest: ten seconds at 60 fps. Only a
+ *  window no GPU sample closes for that long (no timer, or one that resolves
+ *  nothing) gets that far. */
+const GAPS_KEPT = 600;
+
+/** A 60 Hz display's refresh, the one the playback benchmark judges its floor
+ *  by (scripts/performance/floor.ts). */
+const REFRESH_MS = 1_000 / 60;
+
+// ponytail: a 60 Hz display assumed, so a faster one reads a frame one of its
+// own refreshes late as on time; measure the refresh if that must count.
+/** A gap past this went by a refresh without a frame. A frame of such a gap
+ *  that skipped a document frame is late, whatever the cadence: the transport
+ *  runs on wall time. Within one refresh a frame may skip by design, at a
+ *  shuttle speed or a rate over the display's, which the stage is never told. */
+export const MISSED_REFRESH_MS = 1.5 * REFRESH_MS;
+
+/**
+ * The longest a presented frame may follow the one before and still have met
+ * its deadline: the most refreshes a 60 Hz display holds a frame of this
+ * cadence for, plus half a refresh. 24 fps alternates 33.3 and 50 ms there, so
+ * 58.3 ms; 30 and 60 fps hold every frame alike, so 41.7 and 25 ms. A rational
+ * rate a hair over a whole number of refreshes (29.97, 59.94) is held to that
+ * number, and its rare extra refresh reads as late. A stage that holds every
+ * frame that long and skips the ones it cannot show is caught by the frames
+ * it skips (`MISSED_REFRESH_MS`).
+ */
+export function deadlineMs(periodMs: number): number {
+  return (Math.ceil(periodMs / REFRESH_MS - 0.05) + 0.5) * REFRESH_MS;
+}
+
+/** The gap a window's frames typically followed one another by: the mean of
+ *  those at or under their p75. A stall is past it, and a mean is not held to
+ *  the display's refreshes as a median is, so a film whose gaps straddle two
+ *  refreshes does not read a refresh faster or slower from window to window. */
+export function typicalGap(gaps: readonly number[]): number {
+  const p75 = percentile(gaps, 0.75)!;
+  const kept = gaps.filter((gap) => gap <= p75);
+  return kept.reduce((sum, gap) => sum + gap, 0) / kept.length;
+}
+
+/** `?renderScale=` on the stage URL, forwarded by the chrome's `stageSrc`:
+ *  the heavy proofs' arm. `off` is no scale source at all, the stage before
+ *  the playback render scale existed; a step answers that step on every
+ *  played frame, whatever the GPU or the Preferences row says. Anything else,
+ *  absent included, is null: the controller decides. */
+export function stageRenderScaleArm(value: string | null): "off" | number | null {
+  if (value === "off") return "off";
+  return RENDER_SCALE_STEPS.find((step) => String(step) === value) ?? null;
+}
+
+/** The arm, read once, like `?rasterDensity` (adaptivePresentation.ts): the
+ *  stage URL is set at iframe mount and never rewritten. */
+export const STAGE_RENDER_SCALE: "off" | number | null =
+  typeof window === "undefined" ? null : stageRenderScaleArm(new URLSearchParams(window.location.search).get("renderScale"));
+
+const ARM_SOURCE: PresentationScaleSource | null =
+  typeof STAGE_RENDER_SCALE === "number" ? fixedScale(STAGE_RENDER_SCALE) : null;
+
+function fixedScale(scale: number): PresentationScaleSource {
+  return { scale: () => scale, resting: () => scale };
+}
+
+/** The source the stage hands the runtime and the split view: the
+ *  controller, or the arm's (`STAGE_RENDER_SCALE`), null for `off`. The same
+ *  object every call. */
+export function stageScaleSource(controller: RenderScaleController): PresentationScaleSource | null {
+  if (STAGE_RENDER_SCALE === null) return controller;
+  return STAGE_RENDER_SCALE === "off" ? null : ARM_SOURCE;
+}
+
+/** The controller as the HUD prints it. */
+export interface RenderScaleReading {
+  mode: PlaybackResolution;
+  /** What a played frame renders at now (`inForce`). */
+  scale: number;
+  /** A step decided and waiting for its frame, or null. */
+  next: number | null;
+  /** The budget: the document's frame period, ms. */
+  periodMs: number;
+  /** The last judged window's GPU p75, ms, at the scale it drew at. */
+  gpuP75Ms: number | null;
+  /** The last judged window's frames that missed their deadline, of those it
+   *  presented, or null when it presented too few to say. */
+  late: { frames: number; of: number } | null;
+  /** The renderer has a GPU timer. */
+  timer: boolean;
+  /** Why the scale last moved, or null before it did. */
+  reason: string | null;
+}
+
+/** One frame's GPU time, and the shares of it its passes up to the canvas
+ *  took: the copy of P, and the present (the header's prediction). */
+interface Sample {
+  gpuMs: number;
+  copyMs: number;
+  presentMs: number;
+}
+
+/** A window's deadlines: how many of its presented frames came late, of how
+ *  many, and the gap they typically followed one another by. */
+interface Deadlines {
+  late: number;
+  presented: number;
+  typicalMs: number;
+}
+
+/** How long a presented frame followed the one before, and how many document
+ *  frames it moved on. */
+interface Gap {
+  ms: number;
+  frames: number;
+}
+
+/** A Shot's passes up to the canvas, p75 ms, from its last window below 1:
+ *  what a frame of it adds at every scale (the present, which a frame at 1
+ *  draws untagged as three's output pass, and a Shot with post never draws)
+ *  and below 1 (the copy of P). */
+interface CanvasPasses {
+  copyMs: number;
+  presentMs: number;
+}
+
+const NO_CANVAS_PASSES: CanvasPasses = { copyMs: 0, presentMs: 0 };
+
+/** A step down and what decided it: the p75 it was taken at, what the
+ *  prediction said it would cost, the Shot of the window that did, and that
+ *  window's typical gap. */
+interface Step {
+  from: number;
+  to: number;
+  p75: number;
+  predicted: number;
+  shot: string | null;
+  typicalMs: number;
+}
+
+/** In one Shot, a step below `scale` did not pay at `load` there. */
+interface Floor {
+  scale: number;
+  load: number;
+}
+
+const ms = (value: number): string => `${value.toFixed(1)}ms`;
+const lateText = (deadlines: Deadlines): string => `${deadlines.late} of ${deadlines.presented} frames late`;
+
+export class RenderScaleController implements PresentationScaleSource {
+  #mode: PlaybackResolution = "auto";
+  #timer = false;
+  #playing = false;
+  #periodMs = 0;
+  #windowSize = 1;
+  /** The canvas's backing pixels the kept scale was settled for. */
+  #pixels = 0;
+  /** The scale the frames render at: applied only as a frame asks, or by a
+   *  mode or timer change. Kept across Pause, so the next Play starts here. */
+  #scale = 1;
+  /** A frame asked this run, so `#scale` is in force. Nothing asks in a
+   *  layout the child does not draw, and no window is judged there. */
+  #asked = false;
+  /** The frame asking last was inside a transition window. */
+  #blending = false;
+  /** The controller's own step, waiting for a cut, or for the next frame
+   *  when `#now`. */
+  #pending: number | null = null;
+  #now = false;
+  /** `#pending` undoes a step that did not pay: no window moves it before
+   *  the cut it waits for. */
+  #undoing = false;
+  #samples: Sample[] = [];
+  /** The gaps between the frames presented while the window in progress
+   *  gathered its samples. */
+  #gaps: Gap[] = [];
+  /** The last frame presented that a gap may start at: when its request was
+   *  timed and its document frame. Null at the start of a run, at a cut's
+   *  frame and inside a transition window (the header's "A WINDOW IS ONE
+   *  SHOT'S"). */
+  #shown: { atMs: number; frame: number } | null = null;
+  /** The frame asking last is a cut's, until it is presented. */
+  #cut = false;
+  /** The Shot the window in progress draws: undefined until a frame asks. */
+  #windowShot: string | null | undefined = undefined;
+  /** Samples still to drop after a Shot change. */
+  #skip = 0;
+  /** When the window in progress took its first sample. */
+  #windowStart = 0;
+  /** The next whole window is not judged: the one after a step. */
+  #settle = false;
+  #clean = 0;
+  #lastP75: number | null = null;
+  #lastDeadlines: Deadlines | null = null;
+  /** By Shot, its passes up to the canvas, from its last window judged below
+   *  1 (the header's prediction). */
+  #canvas = new Map<string | null, CanvasPasses>();
+  /** The last window's below 1, any Shot's: what a Shot that has not drawn
+   *  below 1 is priced with. */
+  #lastCanvas: CanvasPasses = NO_CANVAS_PASSES;
+  #reason: string | null = null;
+  /** The step down waiting in `#pending`, with what decided it. */
+  #decided: Step | null = null;
+  /** By Shot, its step down in force, until the first window of that Shot at
+   *  the step's scale or below says whether it paid. */
+  #trials = new Map<string, Step>();
+  /** By Shot: a step below `scale` did not pay at `load` there, so no window
+   *  of the Shot tries one while they stay under `RETRY_LOAD` times it. */
+  #floors = new Map<string, Floor>();
+
+  constructor() {
+    this.setFrameRate(DEFAULT_SHOT_FPS);
+  }
+
+  /** The Preferences row (bridge v52 `EditorChrome.playbackResolution`). */
+  setMode(mode: PlaybackResolution): void {
+    if (mode === this.#mode) return;
+    this.#mode = mode;
+    this.#retarget(mode);
+  }
+
+  /** Whether the renderer can time a pass (`GpuTimer`'s answer). */
+  setTimer(available: boolean): void {
+    if (available === this.#timer) return;
+    this.#timer = available;
+    this.#retarget(available ? "gpu timer" : "no gpu timer");
+  }
+
+  /** The document's rate: the budget, and how many frames make a window. */
+  setFrameRate(fps: { num: number; den: number }): void {
+    if (!(fps.num > 0 && fps.den > 0 && Number.isFinite(fps.num / fps.den))) return;
+    this.#periodMs = (1000 * fps.den) / fps.num;
+    this.#windowSize = Math.max(1, Math.round(fps.num / fps.den));
+  }
+
+  /** The canvas's backing pixels (CSS size times density). A scale settled
+   *  for another size says nothing about this one: a step that fit a smaller
+   *  canvas misses on a larger one, and one a larger canvas needed is too soft
+   *  for a smaller, so it starts again from the top. */
+  setCanvasPixels(pixels: number): void {
+    if (!(pixels > 0) || pixels === this.#pixels) return;
+    const first = this.#pixels === 0;
+    this.#pixels = pixels;
+    if (!first) this.reset();
+  }
+
+  /** The transport runs. Only its frames are samples and deadlines: a
+   *  preparing pass's and a paused stage's draw at full density and decide
+   *  nothing. */
+  setPlaying(playing: boolean): void {
+    if (playing === this.#playing) return;
+    this.#playing = playing;
+    this.#samples = [];
+    this.#gaps = [];
+    this.#shown = null;
+    this.#cut = false;
+    this.#windowShot = undefined;
+    this.#skip = 0;
+    this.#asked = false;
+    this.#blending = false;
+  }
+
+  /** Another Project: what this one settled on says nothing about it. */
+  reset(): void {
+    this.#scale = this.#steps()[0]!;
+    this.#pending = null;
+    this.#now = false;
+    this.#undoing = false;
+    this.#samples = [];
+    this.#gaps = [];
+    this.#shown = null;
+    this.#cut = false;
+    this.#settle = false;
+    this.#clean = 0;
+    this.#lastP75 = null;
+    this.#lastDeadlines = null;
+    this.#canvas.clear();
+    this.#lastCanvas = NO_CANVAS_PASSES;
+    this.#reason = null;
+    this.#decided = null;
+    this.#trials.clear();
+    this.#floors.clear();
+  }
+
+  /** The scale the next Play's first frame gets (`PresentationScaleSource
+   *  .resting`): the one kept across Pause, or a step waiting for that frame,
+   *  which is a cut. The stage's idle warm-up holds its scaled targets for it. */
+  resting(): number {
+    return this.#pending ?? this.#scale;
+  }
+
+  /** One frame's GPU time, ms, as the timer resolved it at `atMs`, and how
+   *  much of it was the copy of P and the present (gpuTimer.ts). A frame
+   *  inside a transition window is no sample. */
+  observe(gpuMs: number, atMs: number, copyMs = 0, presentMs = 0): void {
+    if (!this.#playing || this.#blending || !(gpuMs >= 0 && Number.isFinite(gpuMs))) return;
+    if (this.#skip > 0) {
+      this.#skip -= 1;
+      return;
+    }
+    if (this.#samples.length === 0) this.#windowStart = atMs;
+    const copy = copyMs > 0 && Number.isFinite(copyMs) ? Math.min(copyMs, gpuMs) : 0;
+    const present = presentMs > 0 && Number.isFinite(presentMs) ? Math.min(presentMs, gpuMs - copy) : 0;
+    this.#samples.push({ gpuMs, copyMs: copy, presentMs: present });
+    const full = this.#samples.length >= this.#windowSize;
+    const timed = this.#samples.length >= MIN_WINDOW_SAMPLES && atMs - this.#windowStart >= WINDOW_MS;
+    if (full || timed) this.#closeWindow();
+  }
+
+  /** Document frame `frame` of the transport reached the canvas, its request
+   *  timed at `atMs` before it was drawn (bridgeClient.ts, the telemetry's
+   *  match of the runtime's echo): the deadline half of a window. No gap
+   *  starts at a cut's frame or a transition window's, nor ends at one (the
+   *  header's "A WINDOW IS ONE SHOT'S"). */
+  presented(atMs: number, frame: number): void {
+    if (!this.#playing || !Number.isFinite(atMs) || !Number.isFinite(frame)) return;
+    const last = this.#shown;
+    this.#shown = this.#blending || this.#cut ? null : { atMs, frame };
+    this.#cut = false;
+    if (last === null || this.#blending || atMs < last.atMs) return;
+    if (this.#gaps.length >= GAPS_KEPT) this.#gaps.shift();
+    this.#gaps.push({ ms: atMs - last.atMs, frames: Math.abs(frame - last.frame) });
+  }
+
+  /** The window in progress is over: judged, unless it is the one after a
+   *  step. */
+  #closeWindow(): void {
+    const window = this.#samples;
+    const gaps = this.#gaps;
+    this.#samples = [];
+    this.#gaps = [];
+    if (this.#settle) {
+      this.#settle = false;
+      return;
+    }
+    if (this.#asked) this.#judge(window, this.#deadlines(gaps), this.#windowShot ?? null);
+  }
+
+  /** What a window's presented frames say of its deadlines, or null when
+   *  there were too few of them to say anything. */
+  #deadlines(gaps: readonly Gap[]): Deadlines | null {
+    if (gaps.length < MIN_WINDOW_SAMPLES) return null;
+    const allowed = deadlineMs(this.#periodMs);
+    const late = gaps.filter((gap) => gap.ms > allowed || (gap.frames > 1 && gap.ms > MISSED_REFRESH_MS)).length;
+    return { late, presented: gaps.length, typicalMs: typicalGap(gaps.map((gap) => gap.ms)) };
+  }
+
+  /** The child's question, once per played frame (`PresentationScaleSource`).
+   *  Only a transition window's first frame asks, and the window keeps that
+   *  answer; its frames are no samples until the next ask, its closing cut. A
+   *  stopped controller answers 1: a preparing pass draws at full density
+   *  whoever asks. */
+  scale(frame: PresentationFrame): number {
+    if (!this.#playing) return 1;
+    this.#asked = true;
+    this.#blending = frame.blending;
+    // The header's "A WINDOW IS ONE SHOT'S": no gap ends at a cut's frame,
+    // and none starts there once it is presented.
+    this.#cut = frame.cut;
+    if (frame.cut) this.#shown = null;
+    if (frame.shot !== this.#windowShot) {
+      if (this.#windowShot !== undefined) {
+        if (this.#samples.length >= MIN_WINDOW_SAMPLES) this.#closeWindow();
+        else {
+          this.#samples = [];
+          this.#gaps = [];
+        }
+        this.#skip = SAMPLE_LAG_FRAMES;
+      }
+      this.#windowShot = frame.shot;
+      this.#shown = null;
+    }
+    if (this.#pending !== null && (frame.cut || this.#now)) this.#apply(this.#pending, this.#reason);
+    return this.#scale;
+  }
+
+  /** What a played frame renders at now: 1 while stopped, and before a frame
+   *  asked this run. */
+  inForce(): number {
+    return this.#playing && this.#asked ? this.#scale : 1;
+  }
+
+  reading(): RenderScaleReading {
+    const deadlines = this.#lastDeadlines;
+    return {
+      mode: this.#mode,
+      scale: this.inForce(),
+      next: this.#pending,
+      periodMs: this.#periodMs,
+      gpuP75Ms: this.#lastP75,
+      late: deadlines === null ? null : { frames: deadlines.late, of: deadlines.presented },
+      timer: this.#timer,
+      reason: this.#reason,
+    };
+  }
+
+  /** The steps this mode may take, highest first. Without a timer nothing is
+   *  measured, so nothing goes below where the mode starts. */
+  #steps(): readonly number[] {
+    if (this.#mode === "full") return [1];
+    const steps = this.#mode === "fast" ? RENDER_SCALE_STEPS.filter((step) => step <= FAST_RENDER_SCALE) : RENDER_SCALE_STEPS;
+    return this.#timer ? steps : steps.slice(0, 1);
+  }
+
+  /** The mode or the timer moved the steps: the highest one at or below the
+   *  scale, else the lowest, at once. A setting the author changed shows. */
+  #retarget(reason: string): void {
+    const steps = this.#steps();
+    this.#pending = null;
+    this.#now = false;
+    this.#undoing = false;
+    this.#clean = 0;
+    // Other steps: what the old ones learned says nothing about them.
+    this.#decided = null;
+    this.#trials.clear();
+    this.#floors.clear();
+    const target = steps.find((step) => step <= this.#scale) ?? steps.at(-1)!;
+    if (target !== this.#scale) this.#apply(target, reason);
+  }
+
+  #apply(scale: number, reason: string | null): void {
+    const decided = this.#decided;
+    this.#pending = null;
+    this.#now = false;
+    this.#undoing = false;
+    this.#decided = null;
+    if (scale === this.#scale) return;
+    // A step down the windows of a Shot chose is on trial until a window of
+    // that Shot judges it, whatever steps follow it, and a scale above a
+    // step's ends its trial (the header's "A STEP DOWN MUST PAY").
+    for (const [shot, trial] of this.#trials) if (trial.to < scale) this.#trials.delete(shot);
+    if (decided !== null && decided.shot !== null && decided.from === this.#scale && decided.to === scale) this.#trials.set(decided.shot, decided);
+    this.#scale = scale;
+    this.#reason = reason;
+    this.#clean = 0;
+    this.#samples = [];
+    this.#gaps = [];
+    this.#settle = true;
+  }
+
+  #judge(window: readonly Sample[], deadlines: Deadlines | null, shot: string | null): void {
+    const p75 = percentile(window.map((sample) => sample.gpuMs), 0.75)!;
+    this.#lastP75 = p75;
+    this.#lastDeadlines = deadlines;
+    const steps = this.#steps();
+    const scale = this.#scale;
+    const down = DOWN_SHARE * this.#periodMs;
+    // The header's "A REAL PROBLEM, AND THE GPU'S": its frames late.
+    const late = deadlines !== null && deadlines.late >= LATE_SHARE * deadlines.presented;
+    // This Shot's step down in force, judged by the first window of the Shot
+    // at its scale or below that says anything of deadlines (the header's "A
+    // STEP DOWN MUST PAY"). Another Shot's window leaves it waiting.
+    const trial = shot === null ? undefined : this.#trials.get(shot);
+    if (shot !== null && trial !== undefined && deadlines !== null) {
+      this.#trials.delete(shot);
+      if (late && !(deadlines.typicalMs <= (1 - RELIEF_SHARE) * trial.typicalMs && p75 <= (1 - RELIEF_SHARE) * trial.p75)) {
+        this.#floors.set(shot, { scale: trial.from, load: trial.p75 });
+        this.#clean = 0;
+        this.#pending = trial.from;
+        this.#undoing = true;
+        this.#decided = null;
+        this.#now = false;
+        this.#reason = `no relief at ${scale}: ${lateText(deadlines)}, gpu p75 ${ms(p75)} against ${ms(trial.p75)} at ${trial.from}`;
+        return;
+      }
+    }
+    // The undo of a step that bought nothing waits for its cut, whatever the
+    // windows before it say: over the budget, the floor leaves them no step
+    // to take, and under it, no step up to keep.
+    if (this.#undoing) return;
+    // A load past the one a step did not pay at, in that Shot, is new
+    // conditions there.
+    let floor = shot === null ? undefined : this.#floors.get(shot);
+    if (shot !== null && floor !== undefined && scale === floor.scale && p75 > RETRY_LOAD * floor.load) {
+      this.#floors.delete(shot);
+      floor = undefined;
+    }
+    if (scale < 1) {
+      this.#lastCanvas = {
+        copyMs: percentile(window.map((sample) => sample.copyMs), 0.75)!,
+        presentMs: percentile(window.map((sample) => sample.presentMs), 0.75)!,
+      };
+      this.#canvas.set(shot, this.#lastCanvas);
+    }
+    // What the window's own passes would have cost at the display's density:
+    // a step's prediction is this times its area, the present on top of it,
+    // and the copy below 1 (the header's prediction). At 1 the present is in
+    // the frames' time untagged, three's own output pass.
+    const passes = this.#canvas.get(shot) ?? this.#lastCanvas;
+    const own = percentile(window.map((sample) => sample.gpuMs - sample.copyMs - sample.presentMs), 0.75)!;
+    const perPixel = Math.max(0, own - (scale === 1 ? passes.presentMs : 0)) / (scale * scale);
+    const cost = (step: number): number => perPixel * step * step + passes.presentMs + (step < 1 ? passes.copyMs : 0);
+    if (late && p75 > down) {
+      this.#clean = 0;
+      // Not below where a step did not pay in this Shot.
+      const lowest = floor?.scale ?? 0;
+      const below = steps.filter((step) => step < scale && step >= lowest);
+      const target = below.find((step) => cost(step) <= down) ?? below.at(-1);
+      if (target === undefined) {
+        this.#pending = null;
+        this.#decided = null;
+        return;
+      }
+      this.#pending = target;
+      this.#decided = { from: scale, to: target, p75, predicted: cost(target), shot, typicalMs: deadlines.typicalMs };
+      this.#now = p75 > SEVERE_SHARE * this.#periodMs;
+      this.#reason = `${lateText(deadlines)}, gpu p75 ${ms(p75)} over ${ms(down)}${this.#now ? ", severe" : ""}`;
+      return;
+    }
+    if (this.#pending !== null && this.#pending < scale) {
+      this.#pending = null;
+      this.#decided = null;
+    }
+    // The step just above: the last of those higher, highest first.
+    const up = steps.filter((step) => step > scale).at(-1);
+    const headroom = UP_SHARE * this.#periodMs;
+    if (up !== undefined && cost(up) <= headroom) {
+      this.#clean += 1;
+      if (this.#clean < UP_WINDOWS) return;
+      this.#pending = up;
+      this.#decided = null;
+      this.#now = false;
+      this.#reason = `${UP_WINDOWS} windows with ${ms(cost(up))} predicted under ${ms(headroom)}`;
+      return;
+    }
+    this.#clean = 0;
+    if (this.#pending !== null && this.#pending > scale) this.#pending = null;
+  }
+}