chore: import upstream snapshot with attribution

packages/player/tests/perf/scenarios/02-fps.ts

@@ -0,0 +1,236 @@
+/**
+ * Scenario 02: sustained playback against the composition clock.
+ *
+ * Loads the 10-video-grid fixture, calls `player.play()`, then samples
+ * `__player.getTime()` at fixed wall-clock intervals for ~5 seconds. The
+ * emitted metric is the ratio of composition-time advanced to wall-clock
+ * elapsed:
+ *
+ *   composition_time_advancement_ratio = (getTime(end) - getTime(start)) / wallSeconds
+ *
+ * This reads ~1.0 when the runtime is keeping up with its intended playback
+ * speed and falls below 1.0 when the player stalls — a slow video decoder, a
+ * blocked main thread, a GC pause, anything that prevents the composition
+ * clock from advancing at real-time. The metric is independent of the host
+ * display refresh rate by construction: both numerator and denominator are
+ * wall-clock timestamps, neither is a frame count, so a 60Hz, 120Hz, or 240Hz
+ * runner sees the same value for a healthy player.
+ *
+ * Why we replaced the previous rAF-based FPS metric:
+ *   The original implementation counted `requestAnimationFrame` ticks per
+ *   wall-clock second and asserted `fps >= 55`. On a 120Hz CI runner that
+ *   reads ~120 fps regardless of whether the composition is actually
+ *   advancing, so the gate passed even when the player was silently stalling.
+ *   See PR #400 review (jrusso1020 + miguel-heygen) for the full discussion;
+ *   this implementation follows jrusso1020's "first choice" recommendation.
+ *
+ * Per the proposal:
+ *   Test 1: Playback frame rate (player-perf-fps)
+ *     Load 10-video composition → play 5s → measure how well the player kept
+ *     up with the composition clock.
+ *
+ * Methodology details:
+ *   - We install the wall-clock sampler before calling `play()` so the very
+ *     first post-play tick is captured. We then wait for `__player.isPlaying()`
+ *     to flip true (the parent→iframe `play` message is async via postMessage)
+ *     and *reset* the sample buffer, so the measurement window only contains
+ *     samples taken while the runtime was actively playing the timeline.
+ *   - Sampling cadence is 100ms (10 samples/sec). That's fine-grained enough
+ *     to spot a half-second stall but coarse enough that the sampler itself
+ *     has negligible overhead. With a 5s window we collect ~50 samples; the
+ *     ratio is computed from the first and last sample's `getTime()` values.
+ *   - We use `setInterval` (not rAF) on purpose: rAF cadence is the metric we
+ *     are trying to *avoid* depending on. `setInterval` is wall-clock-driven.
+ *
+ * Outputs one metric:
+ *   - composition_time_advancement_ratio_min
+ *     (higher-is-better, baseline key compositionTimeAdvancementRatioMin)
+ *
+ * Aggregation: `min(ratio)` across runs because the proposal asserts a floor
+ * — the worst run is the one that gates against regressions.
+ */
+
+import type { Browser, Frame, Page } from "puppeteer-core";
+import { loadHostPage } from "../runner.ts";
+import type { Metric } from "../perf-gate.ts";
+
+export type FpsScenarioOpts = {
+  browser: Browser;
+  origin: string;
+  /** Number of measurement runs. */
+  runs: number;
+  /** If null, runs the default fixture (10-video-grid). */
+  fixture: string | null;
+};
+
+const DEFAULT_FIXTURE = "10-video-grid";
+const PLAYBACK_DURATION_MS = 5_000;
+const SAMPLE_INTERVAL_MS = 100;
+const PLAY_CONFIRM_TIMEOUT_MS = 5_000;
+const FRAME_LOOKUP_TIMEOUT_MS = 5_000;
+
+declare global {
+  interface Window {
+    /** (wallClockMs, compositionTimeSec) pairs collected by the sampler. */
+    __perfPlaySamples?: Array<{ wall: number; comp: number }>;
+    /** setInterval handle used by the sampler; cleared at the end of the window. */
+    __perfPlaySamplerHandle?: number;
+    /** Hyperframes runtime player API exposed inside the composition iframe. */
+    __player?: {
+      play: () => void;
+      pause: () => void;
+      seek: (timeSeconds: number) => void;
+      getTime: () => number;
+      getDuration: () => number;
+      isPlaying: () => boolean;
+    };
+  }
+}
+
+type RunResult = {
+  ratio: number;
+  compElapsedSec: number;
+  wallElapsedSec: number;
+  samples: number;
+};
+
+/**
+ * Find the iframe Puppeteer Frame that hosts the fixture composition. The
+ * `<hyperframes-player>` shell wraps an iframe whose URL is derived from the
+ * player's `src` attribute, so we match by path substring rather than full URL.
+ */
+async function getFixtureFrame(page: Page, fixture: string): Promise<Frame> {
+  const expected = `/fixtures/${fixture}/`;
+  const deadline = Date.now() + FRAME_LOOKUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const frame = page.frames().find((f) => f.url().includes(expected));
+    if (frame) return frame;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`[scenario:fps] fixture frame not found for "${fixture}" within timeout`);
+}
+
+async function runOnce(
+  opts: FpsScenarioOpts,
+  fixture: string,
+  idx: number,
+  total: number,
+): Promise<RunResult> {
+  const ctx = await opts.browser.createBrowserContext();
+  try {
+    const page = await ctx.newPage();
+    const { duration } = await loadHostPage(page, opts.origin, { fixture });
+    const frame = await getFixtureFrame(page, fixture);
+
+    // Install the wall-clock sampler in the iframe context. We use setInterval
+    // because rAF cadence is exactly the host-display-dependent signal we are
+    // trying NOT to depend on; setInterval is driven by the event loop and
+    // gives us samples at fixed wall-clock cadence regardless of refresh rate.
+    await frame.evaluate((sampleIntervalMs: number) => {
+      window.__perfPlaySamples = [];
+      window.__perfPlaySamplerHandle = window.setInterval(() => {
+        const comp = window.__player?.getTime?.();
+        if (typeof comp !== "number" || !Number.isFinite(comp)) return;
+        window.__perfPlaySamples!.push({
+          wall: performance.timeOrigin + performance.now(),
+          comp,
+        });
+      }, sampleIntervalMs);
+    }, SAMPLE_INTERVAL_MS);
+
+    // Issue play from the host page (parent of the iframe). The player's
+    // public `play()` posts a control message into the iframe.
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { play: () => void }) | null;
+      if (!el) throw new Error("[scenario:fps] player element missing on host page");
+      el.play();
+    });
+
+    // Wait for the runtime to actually transition to playing — this is the
+    // signal that the postMessage round trip + timeline.play() finished.
+    await frame.waitForFunction(() => window.__player?.isPlaying?.() === true, {
+      timeout: PLAY_CONFIRM_TIMEOUT_MS,
+    });
+
+    // Reset samples now that playback is confirmed running. Anything captured
+    // before this point belongs to the ramp-up window (composition clock at
+    // 0, wall clock advancing) and would skew the ratio toward 0.
+    await frame.evaluate(() => {
+      window.__perfPlaySamples = [];
+    });
+
+    // Sustain playback for the measurement window.
+    await new Promise((r) => setTimeout(r, PLAYBACK_DURATION_MS));
+
+    // Stop the sampler and harvest the samples before pausing the runtime,
+    // so the pause command can't perturb the tail of the sample window.
+    const samples = (await frame.evaluate(() => {
+      if (window.__perfPlaySamplerHandle !== undefined) {
+        clearInterval(window.__perfPlaySamplerHandle);
+        window.__perfPlaySamplerHandle = undefined;
+      }
+      return window.__perfPlaySamples ?? [];
+    })) as Array<{ wall: number; comp: number }>;
+
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { pause: () => void }) | null;
+      el?.pause();
+    });
+
+    if (samples.length < 2) {
+      throw new Error(
+        `[scenario:fps] run ${idx + 1}/${total}: only ${samples.length} composition-clock samples captured (composition duration ${duration}s)`,
+      );
+    }
+
+    const first = samples[0]!;
+    const last = samples[samples.length - 1]!;
+    const wallElapsedSec = (last.wall - first.wall) / 1000;
+    const compElapsedSec = last.comp - first.comp;
+    const ratio = wallElapsedSec > 0 ? compElapsedSec / wallElapsedSec : 0;
+
+    console.log(
+      `[scenario:fps] run[${idx + 1}/${total}] ratio=${ratio.toFixed(4)} compElapsed=${compElapsedSec.toFixed(3)}s wallElapsed=${wallElapsedSec.toFixed(3)}s samples=${samples.length}`,
+    );
+
+    await page.close();
+    return {
+      ratio,
+      compElapsedSec,
+      wallElapsedSec,
+      samples: samples.length,
+    };
+  } finally {
+    await ctx.close();
+  }
+}
+
+export async function runFps(opts: FpsScenarioOpts): Promise<Metric[]> {
+  const fixture = opts.fixture ?? DEFAULT_FIXTURE;
+  const runs = Math.max(1, opts.runs);
+  console.log(
+    `[scenario:fps] fixture=${fixture} runs=${runs} window=${PLAYBACK_DURATION_MS}ms sampleInterval=${SAMPLE_INTERVAL_MS}ms`,
+  );
+
+  const ratios: number[] = [];
+  for (let i = 0; i < runs; i++) {
+    const result = await runOnce(opts, fixture, i, runs);
+    ratios.push(result.ratio);
+  }
+
+  // Worst run wins: the proposal asserts a floor on this ratio, so a single
+  // bad run (slow decoder, GC pause, host contention) is the one that gates.
+  const ratioMin = Math.min(...ratios);
+  console.log(`[scenario:fps] aggregate min ratio=${ratioMin.toFixed(4)} runs=${runs}`);
+
+  return [
+    {
+      name: "composition_time_advancement_ratio_min",
+      baselineKey: "compositionTimeAdvancementRatioMin",
+      value: ratioMin,
+      unit: "ratio",
+      direction: "higher-is-better",
+      samples: ratios,
+    },
+  ];
+}

packages/player/tests/perf/scenarios/03-load.ts

@@ -0,0 +1,98 @@
+/**
+ * Scenario 03: composition load (cold + warm).
+ *
+ * Cold: a fresh BrowserContext per run so the network cache is empty. Measures
+ * the wall-clock time from `page.goto` until the player fires its `ready`
+ * event (host shell sets `window.__playerReady`). This stresses html parse +
+ * runtime IIFE eval + GSAP eval + the player's first composition init.
+ *
+ * Warm: same BrowserContext is reused across runs so the static assets
+ * (player bundle, runtime, GSAP, fixture HTML) are served from disk cache.
+ * This isolates the player's per-composition init cost from network I/O.
+ *
+ * Both metrics report p95 over `runs` samples and feed into perf-gate.ts:
+ *   - compLoadColdP95Ms (lower is better)
+ *   - compLoadWarmP95Ms (lower is better)
+ */
+
+import type { Browser } from "puppeteer-core";
+import { loadHostPage, percentile } from "../runner.ts";
+import type { Metric } from "../perf-gate.ts";
+
+export type LoadScenarioOpts = {
+  browser: Browser;
+  origin: string;
+  /** Number of cold and warm runs each. */
+  runs: number;
+  /** If null, runs the default fixture (gsap-heavy). */
+  fixture: string | null;
+};
+
+const DEFAULT_FIXTURE = "gsap-heavy";
+
+export async function runLoad(opts: LoadScenarioOpts): Promise<Metric[]> {
+  const fixture = opts.fixture ?? DEFAULT_FIXTURE;
+  const runs = Math.max(1, opts.runs);
+  console.log(`[scenario:load] fixture=${fixture} runs=${runs}`);
+
+  const cold: number[] = [];
+  for (let i = 0; i < runs; i++) {
+    const ctx = await opts.browser.createBrowserContext();
+    try {
+      const page = await ctx.newPage();
+      const { loadMs, duration } = await loadHostPage(page, opts.origin, { fixture });
+      cold.push(loadMs);
+      console.log(
+        `[scenario:load] cold[${i + 1}/${runs}] loadMs=${loadMs.toFixed(1)} duration=${duration}s`,
+      );
+      await page.close();
+    } finally {
+      await ctx.close();
+    }
+  }
+
+  const warm: number[] = [];
+  const warmCtx = await opts.browser.createBrowserContext();
+  try {
+    const warmupPage = await warmCtx.newPage();
+    await loadHostPage(warmupPage, opts.origin, { fixture });
+    await warmupPage.close();
+
+    for (let i = 0; i < runs; i++) {
+      const page = await warmCtx.newPage();
+      const { loadMs, duration } = await loadHostPage(page, opts.origin, { fixture });
+      warm.push(loadMs);
+      console.log(
+        `[scenario:load] warm[${i + 1}/${runs}] loadMs=${loadMs.toFixed(1)} duration=${duration}s`,
+      );
+      await page.close();
+    }
+  } finally {
+    await warmCtx.close();
+  }
+
+  const coldP95 = percentile(cold, 95);
+  const warmP95 = percentile(warm, 95);
+  console.log(
+    `[scenario:load] cold p95=${coldP95.toFixed(1)}ms (samples=${cold.length}) warm p95=${warmP95.toFixed(1)}ms (samples=${warm.length})`,
+  );
+
+  return [
+    {
+      name: "comp_load_cold_p95_ms",
+      baselineKey: "compLoadColdP95Ms",
+      value: coldP95,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: cold,
+    },
+    {
+      name: "comp_load_warm_p95_ms",
+      baselineKey: "compLoadWarmP95Ms",
+      value: warmP95,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: warm,
+    },
+  ];
+}

packages/player/tests/perf/scenarios/04-scrub.ts

@@ -0,0 +1,307 @@
+/**
+ * Scenario 04: scrub latency.
+ *
+ * Loads the 10-video-grid fixture, pauses the player, then issues 10 seek
+ * calls in sequence — first through the synchronous "inline" path, then
+ * through the postMessage-driven "isolated" path — and measures the wall-clock
+ * latency from each `seek()` call to the first paint where the iframe's
+ * timeline reports the new time.
+ *
+ * Per the proposal:
+ *   Test 2: Scrub latency (player-perf-scrub)
+ *     Load composition → seek to 10 positions in sequence → measure time
+ *     from seek() call to state update callback
+ *     Assert: p95 < 80ms (isolated), p95 < 33ms (inline, Phase 4+)
+ *
+ * Methodology details:
+ *   - Both modes are measured in the same page load. Inline runs first so
+ *     the isolated mode's monkey-patch (forcing `_trySyncSeek` to return
+ *     false) doesn't bleed into the inline samples.
+ *   - "Inline" mode is the default behavior of `<hyperframes-player>` when the
+ *     iframe is same-origin and exposes `__player.seek()` synchronously.
+ *     `seek()` lands the new frame in the same task as the input event.
+ *   - "Isolated" mode is forced by replacing the player element's
+ *     `_trySyncSeek` method with `() => false`, which sends the player
+ *     element through the postMessage bridge — exactly what cross-origin
+ *     embeds and Phase 1 (pre-sync) builds did.
+ *   - Detection is via a `requestAnimationFrame` watcher inside the iframe
+ *     that polls `__player.getTime()` until it is within `MATCH_TOLERANCE_S`
+ *     of the requested target. We use a tolerance because the postMessage
+ *     bridge converts seconds → frame number → seconds, which can introduce
+ *     sub-frame quantization drift even for targets on the canonical fps grid.
+ *   - Timing uses `performance.timeOrigin + performance.now()` in both the
+ *     host and iframe contexts. `timeOrigin` is consistent across same-process
+ *     frames, so the difference is a true wall-clock measurement of latency.
+ *   - Seek targets alternate forward/backward across the 10s composition so
+ *     no two consecutive seeks land near each other; this avoids the rAF
+ *     watcher matching against a stale `getTime()` value before the seek
+ *     command is processed.
+ *
+ * Outputs two metrics:
+ *   - scrub_latency_p95_inline_ms     (lower-is-better, baseline scrubLatencyP95InlineMs)
+ *   - scrub_latency_p95_isolated_ms   (lower-is-better, baseline scrubLatencyP95IsolatedMs)
+ *
+ * Aggregation: percentile(95) is computed across the pooled per-seek
+ * latencies from every run. With 10 seeks per mode per run × 3 runs we get
+ * 30 samples per mode per CI shard, which is enough for a stable p95.
+ */
+
+import type { Browser, Frame, Page } from "puppeteer-core";
+import { loadHostPage, percentile } from "../runner.ts";
+import type { Metric } from "../perf-gate.ts";
+
+export type ScrubScenarioOpts = {
+  browser: Browser;
+  origin: string;
+  /** Number of measurement runs. */
+  runs: number;
+  /** If null, runs the default fixture (10-video-grid). */
+  fixture: string | null;
+};
+
+const DEFAULT_FIXTURE = "10-video-grid";
+/** Targets are seconds within the composition (10s duration). */
+const SEEK_TARGETS: readonly number[] = [1.0, 7.0, 2.0, 8.0, 3.0, 9.0, 4.0, 6.0, 5.0, 0.5];
+/**
+ * Tolerance window the rAF watcher uses to decide that the iframe's reported
+ * `__player.getTime()` matches the requested seek target. 50ms = 1.5 frames at
+ * 30fps, which absorbs three sources of expected slippage:
+ *
+ *   1. **Frame quantization on the postMessage path.** `_sendControl("seek")`
+ *      converts seconds → integer frame number → seconds inside the runtime,
+ *      so e.g. a target of 1.0s on a 30fps composition lands at frame 30 →
+ *      1.000s exactly, but a target of 1.005s lands at frame 30 → still
+ *      1.000s, a 5ms quantization error baked into the API itself.
+ *   2. **Sub-frame intra-clip clock advance.** Even with the iframe paused,
+ *      between the `seek()` call landing and the next rAF tick, the runtime
+ *      may have already nudged time by a fraction of a frame as part of
+ *      finalizing the seek; `getTime()` reports the post-finalize value.
+ *   3. **Variable host load + browser jitter on CI.** GitHub runners share
+ *      cores, so a noisy neighbor can delay the rAF tick that would otherwise
+ *      register the match by tens of ms. Picking a tolerance much tighter
+ *      than this would gate against runner contention rather than player
+ *      regressions.
+ *
+ * The metric this scenario asserts is *latency to user-visible match*, not
+ * *exact equality of the reported time*, so a 50ms acceptance window is the
+ * intended behavior — but if we ever want to tighten this (e.g. to assert
+ * sub-frame precision on the inline path now that PR #397 documented it),
+ * this is the knob to turn. Configurability is deliberately deferred until
+ * we have a concrete second use case; YAGNI.
+ *
+ * TODO(player-perf): revisit this constant after P0-1b lands and we have ~2
+ * weeks of CI baseline data — if the inline-mode samples consistently cluster
+ * well below 50ms, drop this to e.g. 16ms (1 frame @ 60fps) and split the
+ * tolerance per mode (tighter for inline, current for isolated).
+ */
+const MATCH_TOLERANCE_S = 0.05;
+/** Per-seek timeout; isolated p95 in the proposal is 80ms, so 1s is huge headroom. */
+const SEEK_TIMEOUT_MS = 1_000;
+const PAUSE_CONFIRM_TIMEOUT_MS = 5_000;
+const FRAME_LOOKUP_TIMEOUT_MS = 5_000;
+
+declare global {
+  interface Window {
+    /** Promise resolved by the iframe rAF watcher with the wall-clock t1 of the matching paint. */
+    __perfScrubAwait?: Promise<number>;
+    __player?: {
+      play: () => void;
+      pause: () => void;
+      seek: (timeSeconds: number) => void;
+      getTime: () => number;
+      getDuration: () => number;
+      isPlaying: () => boolean;
+    };
+  }
+}
+
+type Mode = "inline" | "isolated";
+
+type RunResult = {
+  inlineLatencies: number[];
+  isolatedLatencies: number[];
+};
+
+/**
+ * Find the iframe Puppeteer Frame that hosts the fixture composition. Same
+ * helper as 02-fps.ts; duplicated locally so each scenario file is
+ * self-contained.
+ */
+async function getFixtureFrame(page: Page, fixture: string): Promise<Frame> {
+  const expected = `/fixtures/${fixture}/`;
+  const deadline = Date.now() + FRAME_LOOKUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const frame = page.frames().find((f) => f.url().includes(expected));
+    if (frame) return frame;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`[scenario:scrub] fixture frame not found for "${fixture}" within timeout`);
+}
+
+/**
+ * Measure a single seek's latency.
+ *
+ * Sequence:
+ *   1. Install a rAF watcher in the iframe that resolves with the wall-clock
+ *      timestamp of the first paint where `__player.getTime()` is within
+ *      tolerance of `target`. Promise is stashed on `window.__perfScrubAwait`.
+ *   2. Capture host wall-clock t0 and call `el.seek(target)` in the same task.
+ *   3. Await the iframe's resolved Promise (returns t1).
+ *   4. Latency = t1 - t0 (ms).
+ */
+async function measureSingleSeek(page: Page, frame: Frame, target: number): Promise<number> {
+  await frame.evaluate(
+    (target: number, tolerance: number, timeoutMs: number) => {
+      window.__perfScrubAwait = new Promise<number>((resolve, reject) => {
+        const deadlineWall = performance.timeOrigin + performance.now() + timeoutMs;
+        const tick = () => {
+          const wall = performance.timeOrigin + performance.now();
+          const time = window.__player?.getTime?.() ?? Number.NaN;
+          if (Number.isFinite(time) && Math.abs(time - target) < tolerance) {
+            resolve(wall);
+            return;
+          }
+          if (wall > deadlineWall) {
+            reject(new Error(`[scrub] timeout target=${target} last=${time}`));
+            return;
+          }
+          requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+      });
+    },
+    target,
+    MATCH_TOLERANCE_S,
+    SEEK_TIMEOUT_MS,
+  );
+
+  const t0Wall = await page.evaluate((targetSeconds: number) => {
+    const el = document.getElementById("player") as
+      | (HTMLElement & { seek: (t: number) => void })
+      | null;
+    if (!el) throw new Error("[scenario:scrub] player element missing on host page");
+    const wall = performance.timeOrigin + performance.now();
+    el.seek(targetSeconds);
+    return wall;
+  }, target);
+
+  // Puppeteer awaits the Promise we stashed on window and returns its resolved value.
+  const t1Wall = (await frame.evaluate(() => window.__perfScrubAwait as Promise<number>)) as number;
+
+  return t1Wall - t0Wall;
+}
+
+async function runScrubBatch(
+  page: Page,
+  frame: Frame,
+  mode: Mode,
+  idx: number,
+  total: number,
+): Promise<number[]> {
+  const latencies: number[] = [];
+  for (const target of SEEK_TARGETS) {
+    const latency = await measureSingleSeek(page, frame, target);
+    latencies.push(latency);
+  }
+  const p95 = percentile(latencies, 95);
+  console.log(
+    `[scenario:scrub] run[${idx + 1}/${total}] mode=${mode} p95=${p95.toFixed(2)}ms n=${latencies.length}`,
+  );
+  return latencies;
+}
+
+async function runOnce(
+  opts: ScrubScenarioOpts,
+  fixture: string,
+  idx: number,
+  total: number,
+): Promise<RunResult> {
+  const ctx = await opts.browser.createBrowserContext();
+  try {
+    const page = await ctx.newPage();
+    const { duration } = await loadHostPage(page, opts.origin, { fixture });
+    const requiredDuration = Math.max(...SEEK_TARGETS);
+    if (duration < requiredDuration) {
+      throw new Error(
+        `[scenario:scrub] fixture composition is ${duration.toFixed(2)}s but scrub targets require >= ${requiredDuration}s`,
+      );
+    }
+    const frame = await getFixtureFrame(page, fixture);
+
+    // Defensively pause: the host shell doesn't autoplay, but `pause()` also
+    // cancels any pending autoplay-on-ready behavior and guarantees the
+    // timeline isn't ticking under our seek measurements.
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { pause?: () => void }) | null;
+      el?.pause?.();
+    });
+    await frame.waitForFunction(() => window.__player?.isPlaying?.() === false, {
+      timeout: PAUSE_CONFIRM_TIMEOUT_MS,
+    });
+
+    // Inline mode first — the player's default `_trySyncSeek` path lands the
+    // seek synchronously when the iframe is same-origin (which it is here).
+    const inlineLatencies = await runScrubBatch(page, frame, "inline", idx, total);
+
+    // Force isolated mode by shadowing `_trySyncSeek` on the instance with
+    // a function that always reports failure. The fallback in `seek()` then
+    // sends the seek through `_sendControl("seek", { frame })`, which is the
+    // same path a cross-origin embed (or a Phase 1 build without sync seek)
+    // would take.
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as
+        | (HTMLElement & { _trySyncSeek?: (t: number) => boolean })
+        | null;
+      if (!el) throw new Error("[scenario:scrub] player element missing on host page");
+      el._trySyncSeek = () => false;
+    });
+
+    const isolatedLatencies = await runScrubBatch(page, frame, "isolated", idx, total);
+
+    await page.close();
+    return { inlineLatencies, isolatedLatencies };
+  } finally {
+    await ctx.close();
+  }
+}
+
+export async function runScrub(opts: ScrubScenarioOpts): Promise<Metric[]> {
+  const fixture = opts.fixture ?? DEFAULT_FIXTURE;
+  const runs = Math.max(1, opts.runs);
+  console.log(
+    `[scenario:scrub] fixture=${fixture} runs=${runs} seeks_per_mode=${SEEK_TARGETS.length} tolerance=${(MATCH_TOLERANCE_S * 1000).toFixed(0)}ms`,
+  );
+
+  const allInline: number[] = [];
+  const allIsolated: number[] = [];
+  for (let i = 0; i < runs; i++) {
+    const result = await runOnce(opts, fixture, i, runs);
+    allInline.push(...result.inlineLatencies);
+    allIsolated.push(...result.isolatedLatencies);
+  }
+
+  const inlineP95 = percentile(allInline, 95);
+  const isolatedP95 = percentile(allIsolated, 95);
+  console.log(
+    `[scenario:scrub] aggregate inline_p95=${inlineP95.toFixed(2)}ms isolated_p95=${isolatedP95.toFixed(2)}ms (runs=${runs} samples_per_mode=${allInline.length})`,
+  );
+
+  return [
+    {
+      name: "scrub_latency_p95_inline_ms",
+      baselineKey: "scrubLatencyP95InlineMs",
+      value: inlineP95,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: allInline,
+    },
+    {
+      name: "scrub_latency_p95_isolated_ms",
+      baselineKey: "scrubLatencyP95IsolatedMs",
+      value: isolatedP95,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: allIsolated,
+    },
+  ];
+}

packages/player/tests/perf/scenarios/05-drift.ts

@@ -0,0 +1,307 @@
+/**
+ * Scenario 05: media sync drift.
+ *
+ * Loads the 10-video-grid fixture, starts playback, and uses
+ * `requestVideoFrameCallback` on every video element to record
+ * (compositionTime, actualMediaTime) pairs for each decoded frame. Drift is
+ * the absolute difference between the *expected* media time (derived from the
+ * composition time using the runtime's clip transform) and the actual media
+ * time the decoder presented to the compositor.
+ *
+ * Per the proposal:
+ *   Test 4: Media sync drift (player-perf-drift)
+ *     Load 5-video composition → play for 10 seconds → on each RVFC callback,
+ *     record drift between expected and actual media time
+ *     Assert: max drift < 500ms, p95 drift < 100ms
+ *
+ * Methodology details:
+ *   - We instrument *every* `video[data-start]` element in the fixture. The
+ *     proposal called for 5 videos; the 10-video-grid gives us 10 streams in
+ *     the same composition, which is a more conservative regression signal.
+ *   - The expected media time uses the same transform the runtime applies in
+ *     packages/core/src/runtime/media.ts:
+ *
+ *         expectedMediaTime = (compositionTime - clip.start) * clip.playbackRate
+ *                              + clip.mediaStart
+ *
+ *     We snapshot `clip.start` / `clip.mediaStart` / `clip.playbackRate` from
+ *     each element's dataset + `defaultPlaybackRate` once when the sampler is
+ *     installed, so the per-frame work is just a subtract + multiply + abs.
+ *   - The runtime's media sync runs on a 50ms `setInterval`. Between syncs the
+ *     video element's clock free-runs. The drift we measure here is the
+ *     residual after that 50ms loop catches up — i.e. the user-visible glitch
+ *     budget. The runtime hard-resyncs when |currentTime - relTime| > 0.5s
+ *     (see media.ts), which is exactly the proposal's max-drift ceiling: a
+ *     regression past 500ms means the corrective resync kicked in and the
+ *     viewer saw a jump.
+ *   - We install RVFC *before* calling play(), then reset the sample buffer
+ *     once `__player.isPlaying()` flips true. Frames captured during the
+ *     postMessage round-trip would compare a non-zero mediaTime against
+ *     `getTime() === 0` and inflate drift to several hundred ms — same gotcha
+ *     as 02-fps.ts.
+ *   - Sustain window is 6s instead of the proposal's 10s because the fixture
+ *     composition is exactly 10s long, and we want headroom before the
+ *     end-of-timeline pause/clamp behavior. With 10 videos × ~25fps × 6s we
+ *     still pool ~1500 samples per run, more than enough for a stable p95.
+ *
+ * Outputs two metrics:
+ *   - media_drift_max_ms   (lower-is-better, baseline driftMaxMs)
+ *   - media_drift_p95_ms   (lower-is-better, baseline driftP95Ms)
+ *
+ * Aggregation: max() and percentile(95) across the pooled per-frame drifts
+ * from every video in every run.
+ */
+
+import type { Browser, Frame, Page } from "puppeteer-core";
+import { loadHostPage, percentile } from "../runner.ts";
+import type { Metric } from "../perf-gate.ts";
+
+export type DriftScenarioOpts = {
+  browser: Browser;
+  origin: string;
+  /** Number of measurement runs. */
+  runs: number;
+  /** If null, runs the default fixture (10-video-grid). */
+  fixture: string | null;
+};
+
+const DEFAULT_FIXTURE = "10-video-grid";
+const PLAYBACK_DURATION_MS = 6_000;
+const PLAY_CONFIRM_TIMEOUT_MS = 5_000;
+const FRAME_LOOKUP_TIMEOUT_MS = 5_000;
+
+type DriftSample = {
+  compTime: number;
+  actualMediaTime: number;
+  clipStart: number;
+  clipMediaStart: number;
+  clipPlaybackRate: number;
+};
+
+declare global {
+  interface Window {
+    /** RVFC samples collected by the iframe-side observer. */
+    __perfDriftSamples?: DriftSample[];
+    /** Set to false to stop sampling at the end of the measurement window. */
+    __perfDriftActive?: boolean;
+    __player?: {
+      play: () => void;
+      pause: () => void;
+      seek: (timeSeconds: number) => void;
+      getTime: () => number;
+      getDuration: () => number;
+      isPlaying: () => boolean;
+    };
+  }
+}
+
+type RunResult = {
+  drifts: number[];
+  videoCount: number;
+};
+
+/**
+ * Find the iframe Puppeteer Frame that hosts the fixture composition. Same
+ * helper as the other scenarios; duplicated locally so each scenario file is
+ * self-contained.
+ */
+async function getFixtureFrame(page: Page, fixture: string): Promise<Frame> {
+  const expected = `/fixtures/${fixture}/`;
+  const deadline = Date.now() + FRAME_LOOKUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const frame = page.frames().find((f) => f.url().includes(expected));
+    if (frame) return frame;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`[scenario:drift] fixture frame not found for "${fixture}" within timeout`);
+}
+
+async function runOnce(
+  opts: DriftScenarioOpts,
+  fixture: string,
+  idx: number,
+  total: number,
+): Promise<RunResult> {
+  const ctx = await opts.browser.createBrowserContext();
+  try {
+    const page = await ctx.newPage();
+    const { duration } = await loadHostPage(page, opts.origin, { fixture });
+    const requiredDurationSec = PLAYBACK_DURATION_MS / 1000;
+    if (duration < requiredDurationSec) {
+      throw new Error(
+        `[scenario:drift] fixture composition is ${duration.toFixed(2)}s but drift sample window needs >= ${requiredDurationSec.toFixed(0)}s`,
+      );
+    }
+    const frame = await getFixtureFrame(page, fixture);
+
+    // Install RVFC on every `video[data-start]` element in the iframe. Each
+    // callback records the wall-clock-aligned (compositionTime, mediaTime)
+    // pair plus a snapshot of the clip transform so we can compute drift in
+    // node without re-querying the dataset on every frame.
+    const videoCount = (await frame.evaluate(() => {
+      window.__perfDriftSamples = [];
+      window.__perfDriftActive = true;
+      const videos = Array.from(document.querySelectorAll<HTMLVideoElement>("video[data-start]"));
+      type RvfcMetadata = { mediaTime: number; presentationTime: number };
+      type RvfcVideo = HTMLVideoElement & {
+        requestVideoFrameCallback?: (
+          cb: (now: DOMHighResTimeStamp, metadata: RvfcMetadata) => void,
+        ) => number;
+      };
+      let installed = 0;
+      for (const video of videos) {
+        const rvfcVideo = video as RvfcVideo;
+        const rvfc = rvfcVideo.requestVideoFrameCallback;
+        // Headless Chrome supports RVFC; bail quietly on browsers that don't.
+        if (!rvfc) continue;
+        const clipStart = Number.parseFloat(video.dataset.start ?? "0") || 0;
+        const clipMediaStart =
+          Number.parseFloat(video.dataset.playbackStart ?? video.dataset.mediaStart ?? "0") || 0;
+        const rawRate = video.defaultPlaybackRate;
+        const clipPlaybackRate =
+          Number.isFinite(rawRate) && rawRate > 0 ? Math.max(0.1, Math.min(5, rawRate)) : 1;
+        const tick = (_now: DOMHighResTimeStamp, metadata: RvfcMetadata) => {
+          if (!window.__perfDriftActive) return;
+          const compTime = window.__player?.getTime?.() ?? Number.NaN;
+          if (Number.isFinite(compTime)) {
+            window.__perfDriftSamples!.push({
+              compTime,
+              actualMediaTime: metadata.mediaTime,
+              clipStart,
+              clipMediaStart,
+              clipPlaybackRate,
+            });
+          }
+          rvfc.call(video, tick);
+        };
+        rvfc.call(video, tick);
+        installed++;
+      }
+      return installed;
+    })) as number;
+
+    if (videoCount === 0) {
+      throw new Error(`[scenario:drift] fixture ${fixture} contains no video[data-start] elements`);
+    }
+
+    // Issue play from the host page; the player posts a control message into
+    // the iframe and the runtime starts the 50ms media sync poll.
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { play: () => void }) | null;
+      if (!el) throw new Error("[scenario:drift] player element missing on host page");
+      el.play();
+    });
+
+    // Wait for the runtime to confirm playing before we trust the samples.
+    await frame.waitForFunction(() => window.__player?.isPlaying?.() === true, {
+      timeout: PLAY_CONFIRM_TIMEOUT_MS,
+    });
+
+    // Reset the buffer now that playback is live. Anything captured during
+    // the postMessage round-trip would compare a non-zero mediaTime against
+    // `getTime() === 0` and bias drift up by hundreds of ms.
+    await frame.evaluate(() => {
+      window.__perfDriftSamples = [];
+    });
+
+    await new Promise((r) => setTimeout(r, PLAYBACK_DURATION_MS));
+
+    // Stop sampling first, then pause. Same ordering as 02-fps.ts so the
+    // pause command can't perturb the tail of the measurement window.
+    const samples = (await frame.evaluate(() => {
+      window.__perfDriftActive = false;
+      return window.__perfDriftSamples ?? [];
+    })) as DriftSample[];
+
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { pause: () => void }) | null;
+      el?.pause();
+    });
+
+    if (samples.length === 0) {
+      throw new Error(
+        `[scenario:drift] run ${idx + 1}/${total}: zero RVFC samples captured (videos=${videoCount}, duration=${duration.toFixed(2)}s)`,
+      );
+    }
+
+    // Apply the runtime's transform to derive the expected media time, then
+    // compare against the actual media time the decoder presented. Convert
+    // to ms here so the gate threshold (driftMaxMs / driftP95Ms) compares
+    // apples-to-apples.
+    const drifts: number[] = [];
+    for (const s of samples) {
+      const expectedMediaTime = (s.compTime - s.clipStart) * s.clipPlaybackRate + s.clipMediaStart;
+      const driftMs = Math.abs(s.actualMediaTime - expectedMediaTime) * 1000;
+      drifts.push(driftMs);
+    }
+
+    const max = Math.max(...drifts);
+    const p95 = percentile(drifts, 95);
+    console.log(
+      `[scenario:drift] run[${idx + 1}/${total}] max=${max.toFixed(2)}ms p95=${p95.toFixed(2)}ms videos=${videoCount} samples=${samples.length}`,
+    );
+
+    await page.close();
+    return { drifts, videoCount };
+  } finally {
+    await ctx.close();
+  }
+}
+
+export async function runDrift(opts: DriftScenarioOpts): Promise<Metric[]> {
+  const fixture = opts.fixture ?? DEFAULT_FIXTURE;
+  const runs = Math.max(1, opts.runs);
+  console.log(`[scenario:drift] fixture=${fixture} runs=${runs} window=${PLAYBACK_DURATION_MS}ms`);
+
+  const allDrifts: number[] = [];
+  let lastVideoCount = 0;
+  for (let i = 0; i < runs; i++) {
+    const result = await runOnce(opts, fixture, i, runs);
+    allDrifts.push(...result.drifts);
+    lastVideoCount = result.videoCount;
+  }
+
+  // Worst case wins for max; p95 is computed across the pooled per-frame
+  // drifts from every video in every run. The proposal asserts max < 500ms
+  // and p95 < 100ms, so a single bad sample legitimately gates the build.
+  const maxDrift = Math.max(...allDrifts);
+  const p95Drift = percentile(allDrifts, 95);
+  // Coefficient of variation (stddev / mean) is logged here as a soft signal
+  // we can eyeball in CI output. We deliberately do NOT gate on it — the
+  // baseline asserts absolute thresholds (max, p95), and the underlying
+  // distribution is heavy-tailed (most frames are sub-50ms, occasional ones
+  // spike during the 50ms media-sync interval). But CV is a useful early
+  // warning: if it climbs significantly across CI runs while max + p95 stay
+  // green, our jitter assumptions about the runtime's resync loop have
+  // shifted (e.g. if media.ts changes its 50ms `setInterval` cadence) and
+  // we should revisit the baselines before they start producing flakes.
+  // TODO(player-perf): once we have ~2 weeks of CI baseline data, decide
+  // whether to publish CV as a tracked-but-ungated metric in baseline.json
+  // alongside max + p95, or wire it into the Slack regression report.
+  const meanDrift = allDrifts.reduce((a, b) => a + b, 0) / allDrifts.length;
+  const variance = allDrifts.reduce((acc, d) => acc + (d - meanDrift) ** 2, 0) / allDrifts.length;
+  const stddev = Math.sqrt(variance);
+  const cv = meanDrift > 0 ? stddev / meanDrift : 0;
+  console.log(
+    `[scenario:drift] aggregate max=${maxDrift.toFixed(2)}ms p95=${p95Drift.toFixed(2)}ms mean=${meanDrift.toFixed(2)}ms cv=${cv.toFixed(3)} videos=${lastVideoCount} samples=${allDrifts.length} runs=${runs}`,
+  );
+
+  return [
+    {
+      name: "media_drift_max_ms",
+      baselineKey: "driftMaxMs",
+      value: maxDrift,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: allDrifts,
+    },
+    {
+      name: "media_drift_p95_ms",
+      baselineKey: "driftP95Ms",
+      value: p95Drift,
+      unit: "ms",
+      direction: "lower-is-better",
+      samples: allDrifts,
+    },
+  ];
+}

packages/player/tests/perf/scenarios/06-parity.ts

@@ -0,0 +1,418 @@
+/**
+ * Scenario 06: live-playback parity vs synchronous seek.
+ *
+ * Loads the gsap-heavy fixture, plays it from t=0, then captures the rendered
+ * frame at a known timestamp (t≈5.0s, mid-animation). Without releasing the
+ * page, we then synchronously seek the same player back to that exact captured
+ * timestamp and capture a *reference* frame. The two PNGs are diffed with
+ * `ffmpeg -lavfi ssim` and the resulting average SSIM is the parity metric.
+ *
+ * Per the proposal:
+ *   Test 5: Live-playback parity (player-perf-parity)
+ *     Play composition → freeze at known t → screenshot → seek to same t →
+ *     screenshot → compare via SSIM
+ *     Assert: SSIM > 0.95 (effectively perfect with deterministic rendering)
+ *
+ * Baseline note (paritySsimMin=0.93, set deliberately wider than the proposal's
+ * 0.95): the host runner is headless Chromium with all the determinism flags
+ * we can practically apply, but the gsap-heavy fixture still has a small
+ * sub-pixel rasterization wobble between "paint immediately after pause()"
+ * and "paint after sync seek." Empirically the worst run sits around 0.96–0.98,
+ * but a 2-point cushion keeps us from chasing flakes on slower CI hardware
+ * while still catching real parity drift (anything < 0.93 means the two
+ * paths produced visibly different pixels, not just sub-pixel jitter).
+ * If we tighten determinism further (e.g. fixed device pixel ratio + forced
+ * software raster) we should ratchet this baseline back up to 0.95.
+ *
+ * Why this matters:
+ *   `<hyperframes-player>`'s sync-seek path goes through `_trySyncSeek`, which
+ *   for same-origin embeds calls into the iframe runtime's `seek()` directly.
+ *   Live playback advances frames via the runtime's animation loop. If those
+ *   two paths drift out of agreement — different rounding, different sub-frame
+ *   sampling, different state ordering — scrubbing a paused composition will
+ *   show different pixels than a paused-during-playback frame at the same time.
+ *   This test pins them together visually.
+ *
+ * Methodology details:
+ *   - Capture point is t=5.0s. The gsap-heavy fixture is a 10s composition
+ *     with 60 tiles each running a staggered 4s out-and-back tween. At 5.0s
+ *     a large fraction of those tiles are mid-flight, so the rendered frame
+ *     has many distinct, position-sensitive pixels — the worst case for any
+ *     sub-frame disagreement between the two paths.
+ *   - Live capture uses an iframe-side rAF watcher that polls
+ *     `__player.getTime()` every animation frame. When `getTime() >= 5.0`,
+ *     the watcher calls `__player.pause()` *from inside the same rAF tick*.
+ *     `pause()` is synchronous (it calls `timeline.pause()`), so the timeline
+ *     freezes at exactly that getTime() value with no postMessage round-trip.
+ *     We then read `getTime()` one more time to capture the canonical frozen
+ *     timestamp `T_actual` — that's the ground truth both screenshots target.
+ *   - Both screenshots wait for two `requestAnimationFrame` ticks on the host
+ *     page before capture. The first rAF flushes any pending style/layout
+ *     work; the second rAF guarantees the compositor has painted. This is
+ *     the same paint-settlement pattern as packages/producer/src/parity-harness.ts.
+ *   - Reference capture issues `el.seek(T_actual)` from the host page. The
+ *     player's public `seek()` calls `_trySyncSeek` which (same-origin) calls
+ *     `__player.seek()` synchronously, so we don't need a postMessage await.
+ *   - SSIM is computed by `ffmpeg -lavfi ssim`, which emits per-channel and
+ *     overall scores to stderr. We parse the `All:` value (clamped at 1.0
+ *     because ffmpeg occasionally reports 1.000001 for identical inputs).
+ *   - Both PNGs and the captured T_actual value are written under
+ *     `tests/perf/results/parity/run-N/` for CI artifact upload and local
+ *     debugging. The directory is gitignored via the existing
+ *     `packages/player/tests/perf/results/` rule.
+ *
+ * Output metric:
+ *   - parity_ssim_min   (higher-is-better, baseline paritySsimMin = 0.93)
+ *
+ * Aggregation: min() across runs. We want the *worst* observed parity to
+ * pass the gate, so that one bad run can't get masked by averaging.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Browser, Frame, Page } from "puppeteer-core";
+import { loadHostPage } from "../runner.ts";
+import type { Metric } from "../perf-gate.ts";
+
+export type ParityScenarioOpts = {
+  browser: Browser;
+  origin: string;
+  /** Number of measurement runs. */
+  runs: number;
+  /** If null, runs the default fixture (gsap-heavy). */
+  fixture: string | null;
+};
+
+const DEFAULT_FIXTURE = "gsap-heavy";
+/** Mid-composition; gsap-heavy is 10s and has many tiles in motion at this point. */
+const TARGET_TIME_S = 5.0;
+/** rAF watcher will resolve as soon as getTime() crosses TARGET_TIME_S. */
+const TARGET_TIMEOUT_MS = 15_000;
+const PLAY_CONFIRM_TIMEOUT_MS = 5_000;
+const FRAME_LOOKUP_TIMEOUT_MS = 5_000;
+/** ffmpeg occasionally reports 1.000001 on identical inputs; clamp to keep
+ *  baseline math sane. */
+const SSIM_CLAMP_MAX = 1.0;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const RESULTS_DIR = resolve(HERE, "../results/parity");
+
+declare global {
+  interface Window {
+    /** Promise resolved by the iframe rAF watcher with the frozen player time (s). */
+    __perfParityPauseAwait?: Promise<number>;
+    __player?: {
+      play: () => void;
+      pause: () => void;
+      seek: (timeSeconds: number) => void;
+      getTime: () => number;
+      getDuration: () => number;
+      isPlaying: () => boolean;
+    };
+  }
+}
+
+type RunResult = {
+  ssim: number;
+  capturedTime: number;
+};
+
+/**
+ * Find the iframe Puppeteer Frame that hosts the fixture composition. Same
+ * helper as the other scenarios; duplicated locally so each scenario file is
+ * self-contained.
+ */
+async function getFixtureFrame(page: Page, fixture: string): Promise<Frame> {
+  const expected = `/fixtures/${fixture}/`;
+  const deadline = Date.now() + FRAME_LOOKUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const frame = page.frames().find((f) => f.url().includes(expected));
+    if (frame) return frame;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`[scenario:parity] fixture frame not found for "${fixture}" within timeout`);
+}
+
+/**
+ * Wait for two animation frames on the host page so the compositor has had a
+ * chance to paint the latest player state before we screenshot. First rAF
+ * flushes pending style/layout, second rAF guarantees a painted commit.
+ */
+async function waitForPaint(page: Page): Promise<void> {
+  await page.evaluate(
+    () =>
+      new Promise<void>((resolve) =>
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+      ),
+  );
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+}
+
+/**
+ * Run `ffmpeg -lavfi ssim` against two PNGs and return the overall SSIM
+ * score. ffmpeg writes the score to stderr in the form:
+ *
+ *   [Parsed_ssim_0 @ 0x...] SSIM Y:0.998... U:0.999... V:0.999... All:0.998... (28.3)
+ *
+ * We grab the `All:` value, parse it as a float, and clamp to SSIM_CLAMP_MAX.
+ *
+ * Three failure modes, kept distinct so CI is debuggable without re-running:
+ *   - `result.error` (e.g. ENOENT) — ffmpeg never started; the binary is
+ *     missing or unexecutable. We surface the OS error so the operator
+ *     immediately knows to install ffmpeg on the runner instead of chasing
+ *     an "exit=undefined" red herring.
+ *   - `result.status !== 0` — ffmpeg started but exited non-zero. Usually a
+ *     decode/argument error; stderr has the real message.
+ *   - parse failure — ffmpeg ran successfully but its output didn't contain
+ *     the expected `All:` token. Indicates a version skew or a no-op input.
+ *
+ * On the second and third failure modes we additionally re-run ffmpeg with
+ * `stats_file` pointed at `<runDir>/ssim-stats.log` so the next CI artifact
+ * upload contains a per-frame SSIM dump alongside the two PNGs. That log is
+ * the cheapest possible bridge between "the assert tripped" and "this pixel
+ * region drifted" — without it, debugging a parity regression means pulling
+ * the PNGs locally and eyeballing them.
+ */
+function computeSsim(referencePath: string, actualPath: string, runDir: string): number {
+  const result = spawnSync(
+    "ffmpeg",
+    ["-hide_banner", "-i", referencePath, "-i", actualPath, "-lavfi", "ssim", "-f", "null", "-"],
+    { stdio: "pipe" },
+  );
+  if (result.error) {
+    // spawnSync surfaces ENOENT / EACCES / etc. on `result.error`. status is
+    // null in this case — ffmpeg never actually ran. Calling toString() on
+    // result.status would print "null", which is exactly what produced the
+    // confusing "exit=undefined" line that masked the real ENOENT in CI.
+    throw new Error(
+      `[scenario:parity] ffmpeg could not be started (${(result.error as NodeJS.ErrnoException).code ?? "unknown"}): ${result.error.message}. ` +
+        "Install ffmpeg on the runner (apt-get install -y ffmpeg) — the parity scenario " +
+        "requires it for SSIM scoring.",
+    );
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr || Buffer.from("")).toString("utf-8");
+    writeSsimStatsOnFailure(referencePath, actualPath, runDir);
+    throw new Error(`[scenario:parity] ffmpeg ssim failed (exit=${result.status}): ${stderr}`);
+  }
+  const stderr = (result.stderr || Buffer.from("")).toString("utf-8");
+  const match = stderr.match(/All:\s*([0-9.]+)/);
+  if (!match) {
+    writeSsimStatsOnFailure(referencePath, actualPath, runDir);
+    throw new Error(`[scenario:parity] could not parse SSIM from ffmpeg stderr: ${stderr}`);
+  }
+  const raw = Number.parseFloat(match[1]);
+  if (!Number.isFinite(raw)) {
+    writeSsimStatsOnFailure(referencePath, actualPath, runDir);
+    throw new Error(`[scenario:parity] parsed SSIM is not finite: "${match[1]}"`);
+  }
+  return Math.min(SSIM_CLAMP_MAX, raw);
+}
+
+/**
+ * Best-effort: re-invoke ffmpeg with `stats_file=<runDir>/ssim-stats.log`
+ * so the per-frame SSIM dump lands in the artifact directory. This runs
+ * only on the failure paths in `computeSsim` — a successful parity check
+ * doesn't need the dump. We swallow any error from this helper because
+ * the caller is already on its way to throwing the original failure;
+ * losing the diagnostic dump shouldn't change the surfaced error.
+ */
+function writeSsimStatsOnFailure(referencePath: string, actualPath: string, runDir: string): void {
+  try {
+    const statsPath = resolve(runDir, "ssim-stats.log");
+    spawnSync(
+      "ffmpeg",
+      [
+        "-hide_banner",
+        "-i",
+        referencePath,
+        "-i",
+        actualPath,
+        "-lavfi",
+        // ffmpeg's lavfi parser uses '\:' to escape the path separator inside
+        // a filter argument. We don't expect ':' in `statsPath` but escape
+        // defensively to keep this robust on weird mounts.
+        `ssim=stats_file=${statsPath.replace(/:/g, "\\:")}`,
+        "-f",
+        "null",
+        "-",
+      ],
+      { stdio: "pipe" },
+    );
+  } catch {
+    // Best-effort: never let stats-dump failure mask the real error.
+  }
+}
+
+async function runOnce(
+  opts: ParityScenarioOpts,
+  fixture: string,
+  idx: number,
+  total: number,
+): Promise<RunResult> {
+  const ctx = await opts.browser.createBrowserContext();
+  try {
+    const page = await ctx.newPage();
+    const { duration } = await loadHostPage(page, opts.origin, { fixture });
+    if (duration < TARGET_TIME_S + 0.1) {
+      throw new Error(
+        `[scenario:parity] fixture composition is ${duration.toFixed(2)}s but parity target needs >= ${(TARGET_TIME_S + 0.1).toFixed(2)}s`,
+      );
+    }
+    const frame = await getFixtureFrame(page, fixture);
+
+    // Install the iframe-side rAF watcher *before* we issue play(). The
+    // watcher polls __player.getTime() every animation frame and, the first
+    // time getTime() >= TARGET_TIME_S, calls __player.pause() in the same
+    // tick. pause() is synchronous (it calls timeline.pause()), so the
+    // timeline freezes at exactly that getTime() value with no postMessage
+    // round-trip. The Promise resolves with that frozen value as the
+    // canonical T_actual we'll use for both screenshots.
+    await frame.evaluate(
+      (target: number, timeoutMs: number) => {
+        window.__perfParityPauseAwait = new Promise<number>((resolve, reject) => {
+          const deadlineWall = performance.timeOrigin + performance.now() + timeoutMs;
+          const tick = () => {
+            const player = window.__player;
+            if (!player) {
+              reject(new Error("[parity] __player missing during rAF watcher"));
+              return;
+            }
+            const wall = performance.timeOrigin + performance.now();
+            const time = player.getTime();
+            if (Number.isFinite(time) && time >= target) {
+              // Pause from inside the rAF tick — synchronous in the runtime,
+              // so the timeline can't advance any further before we read
+              // getTime() back out as the canonical frozen value.
+              player.pause();
+              resolve(player.getTime());
+              return;
+            }
+            if (wall > deadlineWall) {
+              reject(new Error(`[parity] timeout waiting for getTime >= ${target} (last=${time})`));
+              return;
+            }
+            requestAnimationFrame(tick);
+          };
+          requestAnimationFrame(tick);
+        });
+      },
+      TARGET_TIME_S,
+      TARGET_TIMEOUT_MS,
+    );
+
+    // Start playback from the host page.
+    await page.evaluate(() => {
+      const el = document.getElementById("player") as (HTMLElement & { play: () => void }) | null;
+      if (!el) throw new Error("[scenario:parity] player element missing on host page");
+      el.play();
+    });
+
+    // Confirm the runtime is actually playing before we wait on the rAF
+    // watcher. Without this we can hang waiting for getTime() to advance
+    // when play() hasn't kicked the timeline yet.
+    await frame.waitForFunction(() => window.__player?.isPlaying?.() === true, {
+      timeout: PLAY_CONFIRM_TIMEOUT_MS,
+    });
+
+    // Block until the iframe watcher pauses the timeline and resolves with
+    // the frozen player time. This is the canonical T_actual for the run.
+    const capturedTime = (await frame.evaluate(
+      () => window.__perfParityPauseAwait as Promise<number>,
+    )) as number;
+
+    if (!Number.isFinite(capturedTime) || capturedTime < TARGET_TIME_S) {
+      throw new Error(
+        `[scenario:parity] watcher resolved with invalid time: ${capturedTime} (target=${TARGET_TIME_S})`,
+      );
+    }
+
+    // Capture frame #1: the live-playback frame frozen by pause().
+    await waitForPaint(page);
+    const actualImage = (await page.screenshot({ type: "png" })) as Buffer | Uint8Array;
+
+    // Capture frame #2: the same time, reached via synchronous seek. The
+    // player is already paused, so seek() lands the timeline directly on
+    // capturedTime via _trySyncSeek -> __player.seek().
+    await page.evaluate((targetSeconds: number) => {
+      const el = document.getElementById("player") as
+        | (HTMLElement & { seek: (t: number) => void })
+        | null;
+      if (!el) throw new Error("[scenario:parity] player element missing on host page");
+      el.seek(targetSeconds);
+    }, capturedTime);
+
+    await waitForPaint(page);
+    const referenceImage = (await page.screenshot({ type: "png" })) as Buffer | Uint8Array;
+
+    // Persist artifacts under results/parity/run-N/ for CI upload and local
+    // inspection. Captured time is written alongside so we can reproduce
+    // a specific run's seek target later.
+    const runDir = resolve(RESULTS_DIR, `run-${idx + 1}`);
+    ensureDir(runDir);
+    const actualPath = resolve(runDir, "actual.png");
+    const referencePath = resolve(runDir, "reference.png");
+    writeFileSync(actualPath, actualImage);
+    writeFileSync(referencePath, referenceImage);
+    writeFileSync(
+      resolve(runDir, "captured-time.txt"),
+      `${capturedTime}\n${TARGET_TIME_S}\n`,
+      "utf-8",
+    );
+
+    const ssim = computeSsim(referencePath, actualPath, runDir);
+    console.log(
+      `[scenario:parity] run[${idx + 1}/${total}] ssim=${ssim.toFixed(6)} captured_time=${capturedTime.toFixed(6)}s artifacts=${runDir}`,
+    );
+
+    await page.close();
+    return { ssim, capturedTime };
+  } finally {
+    await ctx.close();
+  }
+}
+
+export async function runParity(opts: ParityScenarioOpts): Promise<Metric[]> {
+  const fixture = opts.fixture ?? DEFAULT_FIXTURE;
+  const runs = Math.max(1, opts.runs);
+  console.log(`[scenario:parity] fixture=${fixture} runs=${runs} target=${TARGET_TIME_S}s`);
+
+  // Wipe stale per-run dirs from previous invocations so artifact upload
+  // only contains this run's PNGs. We don't rm -rf the parent dir to avoid
+  // surprising anyone debugging a previous failure.
+  ensureDir(RESULTS_DIR);
+
+  const ssims: number[] = [];
+  for (let i = 0; i < runs; i++) {
+    const result = await runOnce(opts, fixture, i, runs);
+    ssims.push(result.ssim);
+  }
+
+  // Worst case wins. A min < 0.93 means at least one run produced visibly
+  // different pixels between live playback and sync seek at the same time —
+  // which is the regression we're guarding against (see file-level JSDoc
+  // for why the gate is 0.93 rather than the proposal's 0.95).
+  const minSsim = Math.min(...ssims);
+  const meanSsim = ssims.reduce((a, b) => a + b, 0) / ssims.length;
+  console.log(
+    `[scenario:parity] aggregate min=${minSsim.toFixed(6)} mean=${meanSsim.toFixed(6)} runs=${runs}`,
+  );
+
+  return [
+    {
+      name: "parity_ssim_min",
+      baselineKey: "paritySsimMin",
+      value: minSsim,
+      unit: "ssim",
+      direction: "higher-is-better",
+      samples: ssims,
+    },
+  ];
+}