@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/adaptivePresentation.ts

@@ -0,0 +1,145 @@
+// Editor-only presentation quality. Nothing here samples authored values or
+// changes export inputs: the policy decides the editor stage's canvas density
+// and the rung its layer rasters are cut at, and nothing else.
+//
+// ── THE LADDER IS GONE ─────────────────────────────────────────────────────
+//
+// This module used to step the pixel ratio down through 0.75 and 0.5 when a
+// one-second window of presentations looked slow, and back up after four good
+// ones. It never bought the cadence it was built for: every accepted capture of
+// the Cero reference film reached the bottom rung and still presented 21 to 25
+// of its 60 frames a second (gates/performance-verification-20260905). What it
+// did do was RESIZE THE CANVAS mid-playback. fiber sizes the renderer inside
+// its store write, `gl.setSize` clears the backing store synchronously, and the
+// redraw was a later scheduler task, so every rung step presented one cleared,
+// black canvas. Near the threshold the policy flapped, and each flap was another
+// black frame. That is the intermittent black the editor was reported to show
+// during playback.
+//
+// ── ONE DENSITY, PAUSED AND PLAYING ────────────────────────────────────────
+//
+// After the ladder the transport played at device scale 1 and Pause gave the
+// display's density back. That pin was never measured against GPU time, and it
+// cost two canvas resizes per Play and Pause and a soft picture on every
+// display above 1x. Gate G1 measured it (2026-10-24, an RTX 3060 Laptop on
+// WebGPU, six films at device scale 1.5 and 2): at full density the presented
+// cadence and the floor matched the pin on every film, GPU p95 was 0.5 to
+// 3.7 ms (0.7 to 2.9 pinned) against frame periods of 16.7 to 41.7 ms, and
+// peak texture memory rose 60 to 450 MB. So the canvas draws at
+// `stageDensity()` whether the transport runs or not. An integrated GPU is
+// unmeasured; the playback render scale (renderScaleController.ts), which
+// renders below this density into an offscreen target only when the GPU
+// cannot keep up, is the safety net there, and it never resizes the canvas.
+//
+// A change of density (the window moved to another monitor, a browser zoom) is
+// followed by `watchStageDensity` and applied by `useStageDensity` only while
+// the transport is stopped: one that lands during a run waits for its Pause
+// edge, so playback never resizes the canvas. The resize redraws in the task
+// that made it (`ClockDriver`'s store subscription in
+// packages/shot/src/ShotRuntime.tsx), so a density change presents no cleared
+// frame either.
+//
+// ── THE RASTERS FOLLOW IT ONLY UNDER THE GATE'S ARM, FOR NOW ───────────────
+//
+// The layer rasters are cut at the zoom rung (`editorRasterScale`), one rule
+// paused and playing, so Play never re-rasters. Cutting them at the zoom TIMES
+// the density, so a 2x display stops magnifying every text raster, is the
+// author's decision on one condition: that the playback gate shows it fits
+// (first-loop stalls and raster memory within budget). At 2x a raster holds 4x
+// the pixels against a budget tuned for the zoom rung, so a heavy document
+// reaches the raster pressure ceiling, which lowers the rung for everything. So
+// it is the gate's `?rasterDensity=on` arm alone until that A/B has run.
+//
+// The telemetry's one-second windows still close and still report, because the
+// HUD, the `onPerformance` chip and the playback gate read them. They just do
+// not decide anything here.
+import { useEffect, useState } from "react";
+import { quantizeRasterScale } from "@dailies-studio/shot";
+
+export type AdaptivePresentationLevel = 0;
+
+export const ADAPTIVE_WINDOW_MS = 1_000;
+
+export interface PresentationQuality {
+  level: AdaptivePresentationLevel;
+  /** The canvas device-pixel ratio: the stage's density, or 1 in export
+   *  framing. Always a number, so fiber configures nothing while it holds. */
+  dpr: number;
+  rasterScale: number;
+}
+
+/** `?rasterDensity=on` on the stage URL: the layer rasters at the zoom times
+ *  the stage's density, the playback gate's A/B arm
+ *  (`DAILIES_GATE_RASTER_DENSITY`, forwarded by the chrome's `stageSrc`), which
+ *  ships as the default only once that A/B passes (see the header). Absent,
+ *  the zoom rung alone. Read once, like `?warmup` (stageWarmup.ts): the stage
+ *  URL is set at iframe mount and never rewritten. */
+export const STAGE_RASTER_DENSITY: boolean =
+  typeof window !== "undefined" && new URLSearchParams(window.location.search).get("rasterDensity") === "on";
+
+/** The editor stage's canvas density: the display's device-pixel ratio, held
+ *  to 1 through 2 (fiber's default `[1, 2]`, which the paused stage always
+ *  drew at). */
+export function stageDensity(): number {
+  const ratio = typeof window === "undefined" ? 1 : window.devicePixelRatio;
+  return Math.min(Math.max(ratio || 1, 1), 2);
+}
+
+/** Calls `onChange` each time the display's density moves: a monitor move or
+ *  a browser zoom. A `resolution` query matches only the ratio it was made
+ *  for, so it fires once that ratio is gone and is made again for the new one.
+ *  Returns the stop. */
+export function watchStageDensity(onChange: () => void): () => void {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {};
+  let query: MediaQueryList | null = null;
+  const arm = (): void => {
+    query?.removeEventListener("change", changed);
+    query = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+    query.addEventListener("change", changed);
+  };
+  function changed(): void {
+    arm();
+    onChange();
+  }
+  arm();
+  return () => query?.removeEventListener("change", changed);
+}
+
+/** The density the stage draws at now: `stageDensity()`, followed while the
+ *  transport is stopped and HELD while `playing` (which a preparing pass sets
+ *  too). A change during a run lands at its Pause edge, read again there. */
+export function useStageDensity(playing: boolean): number {
+  const [density, setDensity] = useState(stageDensity);
+  useEffect(() => {
+    if (playing) return;
+    const follow = (): void => setDensity(stageDensity());
+    follow();
+    return watchStageDensity(follow);
+  }, [playing]);
+  return density;
+}
+
+/** The rung the editor's layer rasters are cut at: the author's zoom, snapped
+ *  UP the ladder (`quantizeRasterScale`, whose top rung caps it). Under
+ *  `rasterDensity` (`STAGE_RASTER_DENSITY`, the gate's `on` arm) the zoom times
+ *  the stage's density, so text is cut for the device pixels it is shown at. */
+export function editorRasterScale(zoom: number, density: number, rasterDensity: boolean): number {
+  return quantizeRasterScale(zoom * (rasterDensity ? density : 1));
+}
+
+export function presentationQuality({
+  exporting,
+  density,
+  authoredRasterScale,
+}: {
+  exporting: boolean;
+  /** The stage's density (`useStageDensity`). */
+  density: number;
+  /** The editor's raster rung (`editorRasterScale`). */
+  authoredRasterScale: number;
+}): PresentationQuality {
+  // Export framing: the backing store at exactly the design size, the scale
+  // factor Tier-2's Chromium pins, and rasters cut to match.
+  if (exporting) return { level: 0, dpr: 1, rasterScale: 1 };
+  return { level: 0, dpr: density, rasterScale: authoredRasterScale };
+}