@vgai/sdk 0.4.0-canary.20260715.0

package/src/render/render-cinematic.ts

@@ -0,0 +1,1847 @@
+/**
+ * `vgai render-cinematic` — the I0 crux deliverable
+ * (`docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §18 "I0 — recording
+ * spike", §15 Workstream I). Produces a REAL, deterministic, playable video
+ * file from an authored Theatre-driven cinematic: launches headless
+ * Chromium (SwiftShader) against a render-mode page (`?vgai-render=1`,
+ * `packages/engine/src/runtime/render-control.ts`'s `window.__vgaiRender`
+ * seam), seeks+captures every frame as a composited PNG, encodes with
+ * FFmpeg, and verifies the output with ffprobe before ever reporting
+ * success (I7 AC: "A failed render never reports success merely because an
+ * output file exists").
+ *
+ * Scope note (I0 is a spike, not the full I1-I8 slice): sequence-controlled
+ * capture only (no `--simulate`, I5); video-only output (no audio mux, I6's
+ * audio half); MP4/WebM/PNG-sequence in OPAQUE background only (I1's
+ * alpha/background policy is VALIDATED — an invalid transparent+MP4
+ * combination fails fast, before the browser ever launches — but alpha
+ * capture itself is not exercised here, since H.264 cannot carry it and
+ * this spike's fixture scene has an opaque background regardless).
+ *
+ * I1 (request/result schemas): {@link RenderCinematicRequest} /
+ * {@link ResolvedRenderCinematicRequest} / {@link RenderCinematicResult}
+ * below are this module's version of those shared shapes — defaults are
+ * resolved explicitly and returned on the result (`request` field), and
+ * {@link resolveRenderCinematicRequest} validates codec/container/alpha
+ * combinations before {@link renderCinematic} ever touches Playwright.
+ */
+
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Browser, Page } from 'playwright';
+import { chromium } from 'playwright';
+import { checkFfmpegCapability, type FfmpegCapabilityError } from './capabilities/ffmpeg';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Engine monorepo root, resolved from this file's own location (mirrors `packages/vgai-cli/src/index.ts`'s `ENGINE_ROOT`; one extra `..` vs. that file since this module lives one directory deeper, at `packages/vgai-sdk/src/render/`). Injectable for tests. */
+export const DEFAULT_ENGINE_ROOT = resolvePath(__dirname, '..', '..', '..', '..');
+
+/** The I0 fixture's own vite config — the render-mode Theatre cinematic page (`packages/engine/e2e/render-cinematic/`). */
+export function defaultFixtureViteConfig(engineRoot: string = DEFAULT_ENGINE_ROOT): string {
+  return join(engineRoot, 'packages/engine/e2e/render-cinematic/vite.config.ts');
+}
+
+/** The I8 reference cinematic's own vite config — the capstone render-mode
+ *  page that composes Theatre, a Director, cinematic cues, registered GSAP,
+ *  XState-driven character animation, camera ownership, and a React HUD/
+ *  letterbox (`packages/engine/e2e/reference-cinematic/`). Mirrors
+ *  {@link defaultFixtureViteConfig}'s shape exactly, one directory over. */
+export function defaultReferenceCinematicViteConfig(
+  engineRoot: string = DEFAULT_ENGINE_ROOT,
+): string {
+  return join(engineRoot, 'packages/engine/e2e/reference-cinematic/vite.config.ts');
+}
+
+/** The I6 audio-bearing cinematic fixture's own vite config — Theatre-driven
+ *  visuals identical to the I0 fixture, PLUS a declared Tone score (via
+ *  `installRenderAudioHarness`), which is what makes `renderCinematic`
+ *  automatically mux audio for it (`packages/engine/e2e/audio-cinematic/`). */
+export function defaultAudioCinematicViteConfig(engineRoot: string = DEFAULT_ENGINE_ROOT): string {
+  return join(engineRoot, 'packages/engine/e2e/audio-cinematic/vite.config.ts');
+}
+
+/** The I5 `--simulate` fixture's own vite config — a real Rapier physics
+ *  body falling under gravity, NO Theatre/GSAP/XState (see that fixture's
+ *  top doc comment), which is what proves the `--simulate` gameplay-advance
+ *  path rather than the I0/I4/I8 sequence-controlled one
+ *  (`packages/engine/e2e/simulate-cinematic/`). */
+export function defaultSimulateCinematicViteConfig(
+  engineRoot: string = DEFAULT_ENGINE_ROOT,
+): string {
+  return join(engineRoot, 'packages/engine/e2e/simulate-cinematic/vite.config.ts');
+}
+
+export type RenderCinematicFormat = 'mp4' | 'webm' | 'png';
+export type RenderCinematicBackground = 'opaque' | 'transparent';
+/**
+ * I6 audio mode (`docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I6 +
+ * the audio-capture half of §13 G4):
+ *  - `'auto'` (default) — mux audio iff the render page declares a Tone
+ *    score (`window.__vgaiRenderAudio.hasAudio === true`,
+ *    `@engine/runtime/render-audio-control`); a page with no score renders
+ *    video-only, exactly like before this mode existed. NOT a silent
+ *    best-effort: once a score IS declared, a failure to render/mux it is a
+ *    hard pipeline failure (see `maybeCaptureAudio`), never a silently
+ *    dropped track.
+ *  - `'on'` — require a declared score; fails fast (before any encode) if
+ *    the page has none.
+ *  - `'off'` — never mux audio, even if the page declares a score. The
+ *    explicit video-only escape hatch (I6 AC: "a video-only path must
+ *    remain").
+ */
+export type RenderCinematicAudioMode = 'auto' | 'on' | 'off';
+
+/** I1 — the render request. Every field but `entry`/`out` is optional; see {@link resolveRenderCinematicRequest} for defaults. */
+export interface RenderCinematicRequest {
+  /** Either an already-serving page URL (`http://…`) OR a filesystem path to a Vite config to spawn (e.g. {@link defaultFixtureViteConfig}'s return value). */
+  entry: string;
+  /** Output file path (mp4/webm) or output directory (png format). */
+  out: string;
+  format?: RenderCinematicFormat;
+  fps?: number;
+  /** Range start, seconds. Default 0. */
+  start?: number;
+  /** Range end, seconds. Mutually resolved with `frameCount` — supply exactly one. */
+  end?: number;
+  /** Frame count. Mutually resolved with `end` — supply exactly one. */
+  frameCount?: number;
+  width?: number;
+  height?: number;
+  /** Device pixel ratio. Default 1. */
+  dpr?: number;
+  /** `Math.random` seed (render-seed.ts's `?vgai-seed`). Default a fixed constant, for reproducibility across calls that don't pass one. */
+  seed?: number;
+  background?: RenderCinematicBackground;
+  /** I6 audio mode — see {@link RenderCinematicAudioMode}. Default `'auto'`. */
+  audio?: RenderCinematicAudioMode;
+  /** Fail instead of overwriting an existing `out`. Default false (overwrite). */
+  overwrite?: boolean;
+  /** Retain the temporary per-frame PNG directory after encoding. Default false (mp4/webm) — always effectively true for `format: 'png'` (the frames ARE the output). */
+  keepFrames?: boolean;
+  /**
+   * Dev-server port when `entry` is a Vite config path. Default (I7 fold-in
+   * #9b): a genuinely free port is discovered right before launch — two
+   * concurrent renders that both omit `--port` no longer collide on Vite's
+   * `--strictPort` (the prior fixed default, 5799, did exactly that). Pass
+   * an explicit port to pin one (e.g. to satisfy a firewall rule); every
+   * existing caller that already passes an explicit port is byte-for-byte
+   * unaffected.
+   */
+  port?: number;
+  /** Engine monorepo root, for resolving `npx vite`'s cwd when `entry` is a config path. Test-only override. */
+  engineRoot?: string;
+  /**
+   * I5 — `--simulate`: advance the FULL fixed-step gameplay loop (physics,
+   * gameplay phases, AI, particles, participating audio) between captured
+   * frames via `window.__vgaiRender.simulateSubsteps` (`@engine/runtime/
+   * render-control`), instead of the I4 default sequence-controlled path
+   * (Theatre/GSAP time-seek only, no gameplay advance at all). Default
+   * `false` — every existing caller (I0/I6/I8) is byte-unaffected.
+   */
+  simulate?: boolean;
+  /** I5 — fixed gameplay substeps (`game.runFrame(fixedDt)` calls) advanced
+   *  BETWEEN each captured output frame when `simulate` is true. Default 4.
+   *  Ignored (not validated) when `simulate` is false/absent. */
+  simulateSubsteps?: number;
+  /** I5 AC: "Simulation state can warm up before the capture range" — fixed
+   *  gameplay substeps advanced ONCE, before frame 0 is captured, when
+   *  `simulate` is true. Default 0 (no warmup). Ignored when `simulate` is
+   *  false/absent. */
+  simulateWarmupSubsteps?: number;
+  /**
+   * I7 fold-in (I5 nit fix) — an OPTIONAL override for the render-control
+   * harness's fixed gameplay substep `dt` (seconds), threaded through as a
+   * `?vgai-simulate-fixed-dt=` query param a fixture MAY read (the committed
+   * I5 fixture, `packages/engine/e2e/simulate-cinematic/main.ts`, does; a
+   * fixture that doesn't read it keeps its own hardcoded default). This is
+   * the CONFIGURATION half of the fix — the manifest's `simulate.fixedTimestep`
+   * does NOT simply echo this field back; it separately READS the harness's
+   * own `__vgaiRender.simulateFixedDt()` (see {@link readSimulateFixedDt}),
+   * which is the honesty half: a fixture that ignores this override, or was
+   * never told about it (an unmodified real game's own render-mode page,
+   * for instance), still reports whatever dt it is ACTUALLY using, never a
+   * value merely echoed from the request. Ignored when `simulate` is
+   * false/absent.
+   */
+  simulateFixedDt?: number;
+}
+
+/** I1 — the request with every default resolved, exactly as returned on {@link RenderCinematicResult.request}. */
+export interface ResolvedRenderCinematicRequest {
+  readonly entry: string;
+  readonly out: string;
+  readonly format: RenderCinematicFormat;
+  readonly fps: number;
+  readonly start: number;
+  readonly end: number;
+  readonly frameCount: number;
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+  readonly seed: number;
+  readonly background: RenderCinematicBackground;
+  readonly audio: RenderCinematicAudioMode;
+  readonly overwrite: boolean;
+  readonly keepFrames: boolean;
+  readonly port: number;
+  readonly engineRoot: string;
+  readonly simulate: boolean;
+  readonly simulateSubsteps: number;
+  readonly simulateWarmupSubsteps: number;
+  /** I7 fold-in — see {@link RenderCinematicRequest.simulateFixedDt}. `undefined` when the caller didn't override it (the fixture keeps its own default). */
+  readonly simulateFixedDt: number | undefined;
+}
+
+/** Thrown by {@link resolveRenderCinematicRequest} for an invalid request — I1 AC: "fail before launching the browser". */
+export class RenderCinematicRequestError extends Error {}
+
+/** Thrown when ffmpeg/ffprobe preflight fails (I1 AC, `capabilities/ffmpeg.ts`). */
+export class RenderCinematicFfmpegError extends Error {
+  constructor(readonly errors: readonly FfmpegCapabilityError[]) {
+    super(errors.map((e) => e.message).join(' '));
+  }
+}
+
+/** Thrown when the encoded output fails ffprobe verification — I7 AC: never report success on a mismatch. */
+export class RenderCinematicVerificationError extends Error {}
+
+/**
+ * Thrown when {@link RenderCinematicOptions.signal} is aborted mid-render
+ * (B5, `packages/vgai-sdk`'s `cinematic.render.cancel` — the SDK operation
+ * layer wraps this pipeline as a job and needs a real cancellation seam to
+ * fulfil "cancellation removes incomplete temporary frames unless retention
+ * is requested", §8 B5 AC). ADDITIVE: `signal` is optional and every
+ * existing caller (the CLI, the I0/I6/I8 e2e specs) passes none, so this
+ * class is never constructed and the check below is never true for them —
+ * their behavior is byte-for-byte unchanged.
+ *
+ * `keepFrames` carries a CANCEL-TIME retention override, read off
+ * `signal.reason` (an `AbortController.abort(reason)` payload) rather than
+ * the original request's own `keepFrames` — a caller may render with
+ * `keepFrames: false` but still want to inspect whatever was captured
+ * before the cancellation, or vice versa. `undefined` means "no override
+ * given" and the ORIGINAL request's `resolved.keepFrames` decides, exactly
+ * as it already does for every other failure path.
+ */
+export class RenderCinematicCancelledError extends Error {
+  constructor(
+    message: string,
+    readonly keepFrames: boolean | undefined,
+  ) {
+    super(message);
+    this.name = 'RenderCinematicCancelledError';
+  }
+}
+
+/** Read an optional cancel-time retention override off `signal.reason` — split out purely so both call sites below share one interpretation of the reason shape. */
+function keepFramesOverride(signal: AbortSignal | undefined): boolean | undefined {
+  const reason = signal?.reason as { keepFrames?: boolean } | undefined;
+  return reason?.keepFrames;
+}
+
+const DEFAULT_SEED = 0x5eed_c0de;
+/** Only actually used when `entry` is an http(s) URL (no dev server spawn — see {@link resolveEffectivePort}) or as this pure function's own documented default before that override applies. */
+const DEFAULT_PORT = 5799;
+
+/**
+ * I7 fold-in (#9b — port collision): bind an ephemeral TCP port (`:0`, OS-
+ * assigned) on loopback, read back the port the kernel picked, then release
+ * it immediately — the same "guaranteed free right now" idiom
+ * `packages/vgai-cli/src/oclif-projection.test.ts`'s `getClosedPort` and
+ * `editor-sessions.ts`'s `findFreePort` already use elsewhere in this repo.
+ * There is an inherent (and, in practice, vanishingly small) TOCTOU race
+ * between this socket closing and Vite's own `--strictPort` bind a moment
+ * later — the same race every "ask the OS for a free port" helper has — but
+ * it is categorically better than a FIXED default two concurrent renders are
+ * GUARANTEED to collide on.
+ */
+function findFreeRenderPort(): Promise<number> {
+  return new Promise((resolveP, reject) => {
+    const srv = createServer();
+    srv.once('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const address = srv.address();
+      const port = typeof address === 'object' && address !== null ? address.port : undefined;
+      srv.close((closeErr) => {
+        if (closeErr) {
+          reject(closeErr);
+        } else if (port === undefined) {
+          reject(new Error('findFreeRenderPort: could not determine the bound port.'));
+        } else {
+          resolveP(port);
+        }
+      });
+    });
+  });
+}
+
+/**
+ * I7 fold-in (#9b): when the caller didn't pin an explicit `port`, resolve a
+ * genuinely free one right before spawning the dev server, overriding the
+ * resolved request's `DEFAULT_PORT` placeholder. Checked against the
+ * ORIGINAL (unresolved) `request.port`, not `resolved.port` — the latter
+ * already has `DEFAULT_PORT` filled in by {@link resolveRenderCinematicRequest}
+ * and so can never tell "the caller explicitly asked for 5799" apart from
+ * "the caller asked for nothing at all". An `entry` that's already an
+ * http(s) URL never spawns a server (see {@link launchEntryServer}), so its
+ * port is moot — left untouched.
+ */
+async function resolveEffectivePort(
+  request: RenderCinematicRequest,
+  resolved: ResolvedRenderCinematicRequest,
+): Promise<ResolvedRenderCinematicRequest> {
+  if (request.port !== undefined) return resolved;
+  if (/^https?:\/\//.test(resolved.entry)) return resolved;
+  const port = await findFreeRenderPort();
+  return { ...resolved, port };
+}
+
+function requirePositive(value: number, flag: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RenderCinematicRequestError(`${flag} must be a positive number, got ${value}`);
+  }
+  return value;
+}
+
+/** Resolve `start`/`end`/`frameCount`/`fps` into a consistent `{ end, frameCount }` pair — split out of {@link resolveRenderCinematicRequest} purely to keep that function's branch count low. */
+function resolveFrameRange(
+  req: Pick<RenderCinematicRequest, 'end' | 'frameCount'>,
+  start: number,
+  fps: number,
+): { end: number; frameCount: number } {
+  if (req.end !== undefined && req.frameCount !== undefined) {
+    throw new RenderCinematicRequestError(
+      'Supply exactly one of --end or --frame-count, not both.',
+    );
+  }
+  if (req.frameCount !== undefined) {
+    if (!Number.isInteger(req.frameCount) || req.frameCount <= 0) {
+      throw new RenderCinematicRequestError(
+        `--frame-count must be a positive integer, got ${req.frameCount}`,
+      );
+    }
+    return { frameCount: req.frameCount, end: start + req.frameCount / fps };
+  }
+  const end = req.end ?? start + 1;
+  if (!Number.isFinite(end) || end <= start) {
+    throw new RenderCinematicRequestError(`--end (${end}) must be greater than --start (${start})`);
+  }
+  const frameCount = Math.round((end - start) * fps);
+  if (frameCount <= 0) {
+    throw new RenderCinematicRequestError(
+      `Resolved frame count is ${frameCount} (from --start/--end/--fps) — must be positive.`,
+    );
+  }
+  return { end, frameCount };
+}
+
+/** Validate `width`/`height` are positive integers — split out of {@link resolveRenderCinematicRequest} purely to keep that function's branch count low. */
+function requireResolution(width: number, height: number): void {
+  if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) {
+    throw new RenderCinematicRequestError(
+      `--width/--height must be positive integers, got ${width}x${height}`,
+    );
+  }
+}
+
+/** I1 AC: "Invalid codec/container/alpha combinations fail before launching the browser" — H.264/MP4 has no alpha channel. Split out of {@link resolveRenderCinematicRequest} purely to keep that function's branch count low. */
+function requireValidBackgroundFormat(
+  background: RenderCinematicBackground,
+  format: RenderCinematicFormat,
+): void {
+  if (background === 'transparent' && format === 'mp4') {
+    throw new RenderCinematicRequestError(
+      '--background transparent is incompatible with --format mp4 (H.264 has no alpha channel). ' +
+        'Use --format webm or --format png for alpha output.',
+    );
+  }
+}
+
+/** I6 AC: "PNG sequence output requires no video encoding" — a PNG sequence
+ *  has no container to mux audio into, so an EXPLICIT `--audio on` against
+ *  `--format png` is a contradictory request and must fail before the
+ *  browser ever launches, same as {@link requireValidBackgroundFormat}.
+ *  `'auto'`/`'off'` against `png` are NOT errors — `'auto'` just silently
+ *  resolves to no audio for png (there is nowhere to put it), which is not
+ *  the same as a caller explicitly demanding audio and not getting it. */
+function requireValidAudioFormat(
+  audio: RenderCinematicAudioMode,
+  format: RenderCinematicFormat,
+): void {
+  if (audio === 'on' && format === 'png') {
+    throw new RenderCinematicRequestError(
+      '--audio on is incompatible with --format png (a PNG sequence has no container to mux audio ' +
+        'into). Use --format mp4 or --format webm for an audio-bearing render.',
+    );
+  }
+}
+
+/** I5 AC: substep counts must be non-negative integers — split out of
+ *  {@link resolveRenderCinematicRequest} purely to keep that function's
+ *  branch count down (same convention as this file's other `require*`
+ *  helpers). Zero is valid for `simulateWarmupSubsteps` (no warmup) but NOT
+ *  for `simulateSubsteps` when `simulate` is true — a `--simulate` render
+ *  that never advances gameplay would silently degrade to the I4 default
+ *  with no error, which is exactly the "warning instead of a failure"
+ *  anti-pattern this codebase avoids (I7's own "never report success
+ *  merely because..." convention, applied here at the request-validation
+ *  boundary instead). */
+function requireSimulateSubsteps(value: number, flag: string, allowZero: boolean): number {
+  if (!Number.isInteger(value) || value < 0 || (!allowZero && value === 0)) {
+    throw new RenderCinematicRequestError(
+      `${flag} must be a ${allowZero ? 'non-negative' : 'positive'} integer, got ${value}`,
+    );
+  }
+  return value;
+}
+
+/** Resolve `simulate`/`simulateSubsteps`/`simulateWarmupSubsteps`/`simulateFixedDt` —
+ *  split out of {@link resolveRenderCinematicRequest} purely to keep that
+ *  function's own branch count down (same convention as
+ *  {@link resolveFrameRange}). */
+function resolveSimulateFields(req: RenderCinematicRequest): {
+  simulate: boolean;
+  simulateSubsteps: number;
+  simulateWarmupSubsteps: number;
+  simulateFixedDt: number | undefined;
+} {
+  const simulate = req.simulate ?? false;
+  const simulateSubsteps = requireSimulateSubsteps(
+    req.simulateSubsteps ?? 4,
+    '--simulate-substeps',
+    /* allowZero */ !simulate,
+  );
+  const simulateWarmupSubsteps = requireSimulateSubsteps(
+    req.simulateWarmupSubsteps ?? 0,
+    '--simulate-warmup-substeps',
+    /* allowZero */ true,
+  );
+  const simulateFixedDt =
+    req.simulateFixedDt !== undefined
+      ? requirePositive(req.simulateFixedDt, '--simulate-fixed-dt')
+      : undefined;
+  return { simulate, simulateSubsteps, simulateWarmupSubsteps, simulateFixedDt };
+}
+
+export function resolveRenderCinematicRequest(
+  req: RenderCinematicRequest,
+): ResolvedRenderCinematicRequest {
+  const format = req.format ?? 'mp4';
+  const fps = requirePositive(req.fps ?? 30, '--fps');
+  const start = req.start ?? 0;
+  if (!Number.isFinite(start) || start < 0) {
+    throw new RenderCinematicRequestError(`--start must be a non-negative number, got ${start}`);
+  }
+  const { end, frameCount } = resolveFrameRange(req, start, fps);
+
+  const width = req.width ?? 640;
+  const height = req.height ?? 360;
+  requireResolution(width, height);
+  const dpr = requirePositive(req.dpr ?? 1, '--dpr');
+
+  const background = req.background ?? 'opaque';
+  requireValidBackgroundFormat(background, format);
+
+  const audio = req.audio ?? 'auto';
+  requireValidAudioFormat(audio, format);
+
+  const { simulate, simulateSubsteps, simulateWarmupSubsteps, simulateFixedDt } =
+    resolveSimulateFields(req);
+
+  return {
+    entry: req.entry,
+    out: req.out,
+    format,
+    fps,
+    start,
+    end,
+    frameCount,
+    width,
+    height,
+    dpr,
+    seed: req.seed ?? DEFAULT_SEED,
+    background,
+    audio,
+    overwrite: req.overwrite ?? false,
+    keepFrames: req.keepFrames ?? false,
+    // I7 fold-in #9b: this DEFAULT_PORT fallback is only actually used when
+    // `resolveEffectivePort` (below) doesn't override it — i.e. `entry` is
+    // an already-serving http(s) URL (no dev server is ever spawned, so no
+    // port collision is possible). Every Vite-config `entry` gets a REAL
+    // free port at launch time instead — see `resolveEffectivePort`.
+    port: req.port ?? DEFAULT_PORT,
+    engineRoot: req.engineRoot ?? DEFAULT_ENGINE_ROOT,
+    simulate,
+    simulateSubsteps,
+    simulateWarmupSubsteps,
+    simulateFixedDt,
+  };
+}
+
+/** I7 — progress events the pipeline reports (launch/readiness/frame/encode/completion). */
+export type RenderCinematicProgress =
+  | { readonly phase: 'preflight' }
+  | { readonly phase: 'server-launch'; readonly url: string }
+  | { readonly phase: 'server-ready'; readonly url: string }
+  | { readonly phase: 'browser-launch' }
+  | { readonly phase: 'page-ready'; readonly readiness: unknown }
+  /** I5 — emitted once, before frame 0, only for a `simulate: true` request
+   *  with `simulateWarmupSubsteps > 0`. */
+  | { readonly phase: 'warmup'; readonly steps: number }
+  | { readonly phase: 'frame'; readonly n: number; readonly of: number }
+  | { readonly phase: 'audio-detect' }
+  | { readonly phase: 'audio-render' }
+  | { readonly phase: 'audio-render-done'; readonly durationSeconds: number }
+  | { readonly phase: 'encode-start'; readonly format: RenderCinematicFormat }
+  | { readonly phase: 'encode-done'; readonly outputPath: string }
+  | { readonly phase: 'audio-mux-start' }
+  | { readonly phase: 'audio-mux-done'; readonly outputPath: string }
+  | { readonly phase: 'verify'; readonly outputPath: string }
+  | { readonly phase: 'complete'; readonly outputPath: string };
+
+export interface RenderCinematicOptions {
+  onProgress?(event: RenderCinematicProgress): void;
+  /**
+   * Optional cooperative-cancellation signal (ADDITIVE — B5). Checked once
+   * per captured frame and once before the audio render; when aborted,
+   * {@link renderCinematic} throws {@link RenderCinematicCancelledError}
+   * instead of continuing, and — unless `signal.reason`'s `keepFrames` (or,
+   * absent that, the request's own `keepFrames`) says otherwise — removes
+   * the incomplete temporary frames directory before rethrowing. `undefined`
+   * (every pre-existing caller) preserves prior behavior exactly: the
+   * `signal?.aborted` checks below are simply never reached.
+   */
+  signal?: AbortSignal;
+}
+
+/** One FFmpeg encode invocation, recorded verbatim in the manifest (I6 AC). */
+export interface RenderManifestEncode {
+  readonly format: RenderCinematicFormat;
+  readonly outputPath: string;
+  readonly command: readonly string[];
+  readonly codec: { readonly video: string; readonly container: string };
+}
+
+/** I6 AC: "Codec settings and FFmpeg command are recorded in a render
+ *  manifest" — the audio half. Present iff a Tone score was declared,
+ *  rendered, muxed, AND ffprobe-verified present on the final output; a
+ *  render with no declared score (or an explicit `--audio off`) has no
+ *  `audio` field at all, rather than a `present: false` placeholder — the
+ *  same "absent, not falsely-populated" convention `RenderCinematicResult`
+ *  already uses for `encode`/`ffprobe` on a `png` render.
+ *
+ *  G4 AC3 ("audio start offset, duration, sample rate, channel count, and
+ *  tail policy are explicit"): `sampleRate`/`channels`/`durationSeconds`
+ *  live here; start offset is `RenderCinematicResult.request.start` (the
+ *  same requested-range start passed to `renderAudio(start, end)` — see
+ *  `maybeCaptureAudio` in this file); tail policy is "exact, hard-fail on
+ *  mismatch" (no pad/truncate step exists or is needed — see the duration
+ *  check in `maybeCaptureAudio`). */
+export interface RenderManifestAudio {
+  readonly codec: string;
+  readonly container: RenderCinematicFormat;
+  readonly sampleRate: number;
+  readonly channels: number;
+  readonly durationSeconds: number;
+  /** sha256 over the raw WAV file bytes rendered in-page, BEFORE muxing —
+   *  the audio-side equivalent of {@link RenderCinematicResult.framesDigest}:
+   *  identical across two renders of the same request iff the offline Tone
+   *  render (G12) was genuinely bit-identical both times. */
+  readonly wavDigest: string;
+  readonly muxCommand: readonly string[];
+}
+
+/** I5 — the `--simulate` manifest fields (present iff `request.simulate` is
+ *  true). Echoes what already lives on `request` (`seed`/`simulateSubsteps`/
+ *  `simulateWarmupSubsteps`) as one grouped, self-describing object, plus
+ *  the fixed substep `dt` actually used — so a manifest reader doesn't have
+ *  to reconstruct "was this a --simulate render, and with what settings"
+ *  from the flat request fields. */
+export interface RenderManifestSimulate {
+  readonly seed: number;
+  readonly substeps: number;
+  readonly warmupSubsteps: number;
+  readonly fixedTimestep: number;
+}
+
+/** I7 — the final result. Never returned on a failed/unverified render (the promise rejects instead). */
+export interface RenderCinematicResult {
+  readonly request: ResolvedRenderCinematicRequest;
+  readonly outputPath: string;
+  readonly manifestPath: string;
+  readonly frameCount: number;
+  readonly durationSeconds: number;
+  readonly frameHashes: readonly string[];
+  /** sha256 over the newline-joined, in-order per-frame sha256 hashes — a single value that changes iff ANY frame's bytes change. */
+  readonly framesDigest: string;
+  readonly encode?: RenderManifestEncode;
+  readonly ffprobe?: { readonly nbFrames: number; readonly durationSeconds: number };
+  /** I6 audio manifest fields — see {@link RenderManifestAudio}. */
+  readonly audio?: RenderManifestAudio;
+  /** I5 — present iff `request.simulate` is true. See {@link RenderManifestSimulate}. */
+  readonly simulate?: RenderManifestSimulate;
+  /** I5 AC 5 — every subsystem the render page declares (or this seam
+   *  itself detects) as excluded from deterministic participation. Always
+   *  present (an empty array is a real, checked answer — "nothing
+   *  excluded" — not an absent field), unlike `encode`/`audio`/`simulate`
+   *  which are genuinely optional per-request. See
+   *  `render-control.ts`'s `VgaiRenderHarness.excludedFromDeterminism`. */
+  readonly excludedFromDeterminism: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+function sha256(buf: Buffer): string {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+function padFrameName(n: number, digits: number): string {
+  return `frame-${String(n).padStart(digits, '0')}.png`;
+}
+
+async function waitForHttpOk(url: string, timeoutMs: number, signal?: AbortSignal): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr: unknown;
+  while (Date.now() < deadline) {
+    // I7 fold-in (#9a): don't keep polling a dev server that's booting for a
+    // render that was already cancelled — return promptly so the caller's
+    // own catch path (`launchEntryServer`) can group-kill the half-started
+    // vite process right away instead of waiting out the full 30s timeout.
+    if (signal?.aborted) {
+      throw new Error('Render cancelled while waiting for the dev server to become ready.');
+    }
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status === 404) return; // dev server answering is enough; 404 still proves it's up
+    } catch (err) {
+      lastErr = err;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error(
+    `Dev server at ${url} did not become ready within ${timeoutMs}ms` +
+      (lastErr instanceof Error ? ` (last error: ${lastErr.message})` : ''),
+  );
+}
+
+interface LaunchedServer {
+  readonly baseUrl: string;
+  stop(): Promise<void>;
+}
+
+/** Resolve `entry` into a running dev server: reuse a URL as-is, or spawn `npx vite --config <entry>` (mirrors `run-doctor.ts`/`runConformance`'s `npx tsx <runner>` spawn idiom, `packages/vgai-cli/src/index.ts`). */
+async function launchEntryServer(
+  entry: string,
+  port: number,
+  engineRoot: string,
+  onProgress: ((e: RenderCinematicProgress) => void) | undefined,
+  signal?: AbortSignal,
+): Promise<LaunchedServer> {
+  if (/^https?:\/\//.test(entry)) {
+    return { baseUrl: entry.replace(/\/$/, ''), stop: async () => {} };
+  }
+
+  const configPath = resolvePath(entry);
+  if (!existsSync(configPath)) {
+    throw new RenderCinematicRequestError(
+      `--entry "${entry}" is neither an http(s) URL nor an existing Vite config file.`,
+    );
+  }
+  const baseUrl = `http://127.0.0.1:${port}`;
+  onProgress?.({ phase: 'server-launch', url: baseUrl });
+
+  // `detached: true` makes this child the leader of its OWN process group —
+  // required for `stopServerProcess`'s `process.kill(-pid, sig)` group-kill
+  // below to reach the REAL `vite` node process underneath the `npx`
+  // wrapper, not just the wrapper itself. Without this, a plain
+  // `child.kill('SIGTERM')` only signals `npx`, which does NOT propagate to
+  // the node process it execs (the exact hazard documented at
+  // `packages/editor/e2e/helpers/server.ts`'s `stopProcess`) — the real vite
+  // server leaks, its stdout/stderr pipes stay open, and THIS process (still
+  // reading those pipes) never exits even after the render is fully done.
+  const child: ChildProcess = spawn(
+    'npx',
+    ['vite', '--config', configPath, '--port', String(port), '--strictPort'],
+    { cwd: engineRoot, stdio: ['ignore', 'pipe', 'pipe'], detached: true },
+  );
+  let serverOutput = '';
+  child.stdout?.on('data', (d) => {
+    serverOutput += String(d);
+  });
+  child.stderr?.on('data', (d) => {
+    serverOutput += String(d);
+  });
+
+  let exited = false;
+  child.on('exit', () => {
+    exited = true;
+  });
+
+  try {
+    await waitForHttpOk(`${baseUrl}/`, 30_000, signal);
+  } catch (err) {
+    await stopServerProcess(child);
+    throw new Error(`${(err as Error).message}\nVite dev server output:\n${serverOutput}`);
+  }
+  if (exited) {
+    throw new Error(`Vite dev server exited before becoming ready.\nOutput:\n${serverOutput}`);
+  }
+
+  onProgress?.({ phase: 'server-ready', url: baseUrl });
+
+  return {
+    baseUrl,
+    async stop() {
+      if (exited) return;
+      await stopServerProcess(child);
+    },
+  };
+}
+
+/**
+ * Terminate `proc` AND its whole process group (see the `detached: true`
+ * comment at its call site above) — a plain `proc.kill()` leaves the real
+ * `vite` node process (an `npx` grandchild) running, which both leaks a
+ * port-bound dev server across renders and keeps THIS process's event loop
+ * alive via the still-open stdout/stderr pipes, hanging `renderCinematic`'s
+ * caller indefinitely after the render itself has already finished. Mirrors
+ * `packages/editor/e2e/helpers/server.ts`'s `stopProcess` (POSIX process-
+ * group signal via the negative pid, falling back to signalling just the
+ * child if the group is already gone), trimmed to the Linux/macOS path this
+ * pipeline actually runs on.
+ */
+function stopServerProcess(proc: ChildProcess): Promise<void> {
+  const signalGroup = (sig: NodeJS.Signals): void => {
+    if (proc.pid === undefined) return;
+    try {
+      process.kill(-proc.pid, sig); // negative pid = the whole process group
+    } catch {
+      try {
+        proc.kill(sig); // group already gone — fall back to the child itself
+      } catch {
+        /* already dead */
+      }
+    }
+  };
+  return new Promise((resolvePromise) => {
+    if (proc.exitCode !== null || proc.signalCode !== null) {
+      signalGroup('SIGKILL');
+      resolvePromise();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signalGroup('SIGKILL'); // belt and braces — don't hang the render on a stuck dev server
+      resolvePromise();
+    }, 5_000);
+    proc.on('exit', () => {
+      clearTimeout(timer);
+      signalGroup('SIGKILL'); // the wrapper is dead; sweep the rest of the group too
+      resolvePromise();
+    });
+    signalGroup('SIGTERM');
+  });
+}
+
+interface ReadinessSubsystem {
+  readonly status: string;
+  readonly detail?: string;
+}
+interface ReadinessReport {
+  readonly assets: ReadinessSubsystem;
+  readonly shaders: ReadinessSubsystem;
+  readonly fonts: ReadinessSubsystem;
+  readonly theatre: ReadinessSubsystem;
+  readonly tone: ReadinessSubsystem;
+  readonly scene: ReadinessSubsystem;
+}
+
+/** Capture every frame `0..frameCount-1` as a composited PNG under `framesDir`, returning per-frame sha256 hashes in order. */
+async function captureFrames(
+  page: Page,
+  framesDir: string,
+  resolved: ResolvedRenderCinematicRequest,
+  onProgress: ((e: RenderCinematicProgress) => void) | undefined,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  // I5 AC: "Simulation state can warm up before the capture range" — advance
+  // the fixed-step gameplay loop ONCE, before frame 0 is ever seeked/
+  // captured. A no-warmup request (`simulateWarmupSubsteps === 0`, the
+  // default) skips this entirely — no behavior change for any pre-I5 caller.
+  if (resolved.simulate && resolved.simulateWarmupSubsteps > 0) {
+    onProgress?.({ phase: 'warmup', steps: resolved.simulateWarmupSubsteps });
+    await page.evaluate((steps) => {
+      (
+        globalThis as unknown as { __vgaiRender: { simulateSubsteps(steps: number): void } }
+      ).__vgaiRender.simulateSubsteps(steps);
+    }, resolved.simulateWarmupSubsteps);
+  }
+
+  const digits = Math.max(6, String(resolved.frameCount).length);
+  const hashes: string[] = [];
+  for (let n = 0; n < resolved.frameCount; n++) {
+    if (signal?.aborted) {
+      throw new RenderCinematicCancelledError(
+        `Render cancelled after ${n}/${resolved.frameCount} frames captured.`,
+        keepFramesOverride(signal),
+      );
+    }
+    await page.evaluate(
+      async ({ n, fps, simulate, simulateSubsteps }) => {
+        const harness = (
+          globalThis as unknown as {
+            __vgaiRender: {
+              advanceFrame(dt: number): void;
+              seekFrame(n: number, fps: number): void;
+              renderOnce(): Promise<void>;
+              simulateSubsteps(steps: number): void;
+            };
+          }
+        ).__vgaiRender;
+        if (simulate) {
+          // I5 — the `--simulate` seam: advance the FULL fixed-step
+          // gameplay loop (physics/gameLogic/animation/... — every phase)
+          // between this and the previous captured frame. Deliberately NOT
+          // `advanceFrame` here — that ticks only I8's FrameAdvancer
+          // registry (bypassing gameplay phases entirely), which would
+          // double-drive any system that also rides a real gameplay phase
+          // via `simulateSubsteps`'s own `game.runFrame` calls.
+          harness.simulateSubsteps(simulateSubsteps);
+        } else {
+          // I4 default (sequence-controlled, unchanged since I8): advance
+          // any registered frame-advancers (e.g. an XState/AnimationMixer
+          // binding's `tick`, which the 'animation'-phase gameplay loop
+          // would otherwise drive but renderOnce() deliberately bypasses —
+          // see render-control.ts's `VgaiRenderHarness.advanceFrame` doc
+          // comment) by exactly one output frame's worth of time, BEFORE
+          // seeking/rendering. A fixture that registered no advancers (e.g.
+          // the I0 fixture) sees a harmless no-op here.
+          harness.advanceFrame(1 / fps);
+        }
+        harness.seekFrame(n, fps);
+        await harness.renderOnce();
+      },
+      {
+        n,
+        fps: resolved.fps,
+        simulate: resolved.simulate,
+        simulateSubsteps: resolved.simulateSubsteps,
+      },
+    );
+    // Composite capture (I3 AC): the #app HOST container, not the bare
+    // canvas — this is what makes a future DOM/React overlay composite
+    // correctly. Exact WxH*DPR resolution comes from the browser context's
+    // own viewport + deviceScaleFactor (set at context-creation time).
+    const buffer = await page.locator('#app').screenshot({
+      omitBackground: resolved.background === 'transparent',
+    });
+    const name = padFrameName(n, digits);
+    await writeFile(join(framesDir, name), buffer);
+    hashes.push(sha256(buffer));
+    onProgress?.({ phase: 'frame', n, of: resolved.frameCount });
+  }
+  return hashes;
+}
+
+/** Read `window.__vgaiRender.excludedFromDeterminism()` (I5 AC 5) — split
+ *  out purely to keep {@link renderCinematic}'s own body readable. Present
+ *  on every render-mode page (not just `--simulate` ones): the harness
+ *  always exposes this method (`render-control.ts`), so a caller can always
+ *  see what the fixture declares, whether or not gameplay is advancing. */
+async function readExcludedFromDeterminism(page: Page): Promise<string[]> {
+  return page.evaluate(() =>
+    (
+      globalThis as unknown as { __vgaiRender: { excludedFromDeterminism(): string[] } }
+    ).__vgaiRender.excludedFromDeterminism(),
+  );
+}
+
+/**
+ * I7 fold-in (I5 nit fix) — read `window.__vgaiRender.simulateFixedDt()`
+ * (`@engine/runtime/render-control`'s `VgaiRenderHarness.simulateFixedDt`),
+ * the ACTUAL fixed gameplay substep `dt` the harness is using, instead of
+ * this pipeline assuming every fixture matches its own `1/60` default. Only
+ * called for a `resolved.simulate: true` request (see the call site in
+ * {@link renderCinematic}). Returns `undefined` — rather than throwing — for
+ * a render-mode page that predates this harness method (back-compat: an
+ * older/unmodified real game's own render-mode page might not have it yet);
+ * {@link buildSimulateManifest} falls back to the documented `1/60` engine
+ * default in that case, with an honest comment, never a silent guess dressed
+ * up as a measured value.
+ */
+async function readSimulateFixedDt(page: Page): Promise<number | undefined> {
+  return page.evaluate(() => {
+    const harness = (globalThis as unknown as { __vgaiRender: { simulateFixedDt?: () => number } })
+      .__vgaiRender;
+    return typeof harness.simulateFixedDt === 'function' ? harness.simulateFixedDt() : undefined;
+  });
+}
+
+/**
+ * I7 fold-in (#9a — cancellation): run ffmpeg via the ASYNC `spawn`, not
+ * `spawnSync`. `spawnSync` blocks Node's entire event loop for the whole
+ * invocation, so a cooperative `signal.aborted` check can never even run
+ * while an encode is in flight — cancelling a render mid-encode used to be
+ * unable to kill ffmpeg at all until the encode finished on its own. This
+ * version listens for `signal`'s abort event and SIGKILLs the ffmpeg child
+ * immediately, same "terminate right away" guarantee `renderCinematic`'s own
+ * `onAbort` gives the browser/vite-group.
+ */
+function runFfmpeg(args: string[], signal?: AbortSignal): Promise<void> {
+  return new Promise((resolveP, reject) => {
+    if (signal?.aborted) {
+      reject(
+        new RenderCinematicCancelledError(
+          'Render cancelled before ffmpeg started.',
+          keepFramesOverride(signal),
+        ),
+      );
+      return;
+    }
+    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr?.on('data', (d) => {
+      stderr += String(d);
+    });
+    let killedByAbort = false;
+    const onAbort = (): void => {
+      killedByAbort = true;
+      child.kill('SIGKILL');
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.on('error', (err) => {
+      signal?.removeEventListener('abort', onAbort);
+      reject(err);
+    });
+    child.on('exit', (code) => {
+      signal?.removeEventListener('abort', onAbort);
+      if (killedByAbort) {
+        reject(
+          new RenderCinematicCancelledError(
+            'ffmpeg terminated by render cancellation.',
+            keepFramesOverride(signal),
+          ),
+        );
+        return;
+      }
+      if (code !== 0) {
+        reject(
+          new Error(`ffmpeg exited ${code ?? '(signal)'}: ffmpeg ${args.join(' ')}\n${stderr}`),
+        );
+        return;
+      }
+      resolveP();
+    });
+  });
+}
+
+function runFfprobeFrameCountAndDuration(path: string): {
+  nbFrames: number;
+  durationSeconds: number;
+} {
+  const result = spawnSync(
+    'ffprobe',
+    [
+      '-v',
+      'error',
+      '-select_streams',
+      'v:0',
+      '-count_frames',
+      '-show_entries',
+      'stream=nb_read_frames',
+      '-show_entries',
+      'format=duration',
+      '-of',
+      'json',
+      path,
+    ],
+    { encoding: 'utf-8' },
+  );
+  if (result.status !== 0) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe failed on ${path} (exit ${result.status ?? '(signal)'}): ${result.stderr ?? ''}`,
+    );
+  }
+  const parsed = JSON.parse(result.stdout) as {
+    streams?: Array<{ nb_read_frames?: string }>;
+    format?: { duration?: string };
+  };
+  const nbFramesRaw = parsed.streams?.[0]?.nb_read_frames;
+  const durationRaw = parsed.format?.duration;
+  const nbFrames = nbFramesRaw !== undefined ? Number(nbFramesRaw) : Number.NaN;
+  const durationSeconds = durationRaw !== undefined ? Number(durationRaw) : Number.NaN;
+  if (!Number.isFinite(nbFrames) || !Number.isFinite(durationSeconds)) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe returned an unparseable result for ${path}: ${result.stdout}`,
+    );
+  }
+  return { nbFrames, durationSeconds };
+}
+
+/** ffprobe the first audio stream of `path` (codec name + duration), or
+ *  `undefined` if the container has none — split out purely to keep {@link
+ *  encodeAndVerify} readable. Some containers/codec combinations don't
+ *  report a per-stream `duration` (it's absent/`"N/A"`); this falls back to
+ *  the container-level `format.duration` in that case rather than treating
+ *  a missing per-stream field as "no duration information exists at all". */
+function runFfprobeAudioStream(
+  path: string,
+): { codec: string; durationSeconds: number } | undefined {
+  const result = spawnSync(
+    'ffprobe',
+    [
+      '-v',
+      'error',
+      '-select_streams',
+      'a:0',
+      '-show_entries',
+      'stream=codec_name,duration',
+      '-show_entries',
+      'format=duration',
+      '-of',
+      'json',
+      path,
+    ],
+    { encoding: 'utf-8' },
+  );
+  if (result.status !== 0) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe (audio stream) failed on ${path} (exit ${result.status ?? '(signal)'}): ${result.stderr ?? ''}`,
+    );
+  }
+  const parsed = JSON.parse(result.stdout) as {
+    streams?: Array<{ codec_name?: string; duration?: string }>;
+    format?: { duration?: string };
+  };
+  const stream = parsed.streams?.[0];
+  if (!stream) return undefined;
+
+  const codec = stream.codec_name ?? 'unknown';
+  const perStreamDuration = stream.duration !== undefined ? Number(stream.duration) : Number.NaN;
+  const durationSeconds = Number.isFinite(perStreamDuration)
+    ? perStreamDuration
+    : Number(parsed.format?.duration ?? Number.NaN);
+  if (!Number.isFinite(durationSeconds)) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe returned an unparseable audio duration for ${path}: ${result.stdout}`,
+    );
+  }
+  return { codec, durationSeconds };
+}
+
+/** Verify the muxed output actually carries an audio stream whose duration
+ *  matches the video (I6 AC: "exact range alignment") — split out of {@link
+ *  encodeAndVerify} to keep its own branch count down. Mirrors {@link
+ *  verifyEncodedOutput}'s "throw, never a warning" convention: a render that
+ *  declared a Tone score must never report success with audio silently
+ *  missing or misaligned. */
+function verifyAudioOutput(
+  audioStream: { codec: string; durationSeconds: number } | undefined,
+  outAbs: string,
+  resolved: ResolvedRenderCinematicRequest,
+): void {
+  if (!audioStream) {
+    throw new RenderCinematicVerificationError(
+      `Expected an audio stream in ${outAbs} (the render page declared a Tone score) but ffprobe ` +
+        'found none. The mux step did NOT verify — this is a failure, not a success with a warning.',
+    );
+  }
+  const expectedDuration = resolved.frameCount / resolved.fps;
+  const durationDelta = Math.abs(audioStream.durationSeconds - expectedDuration);
+  const tolerance = 0.5 / resolved.fps;
+  if (durationDelta > tolerance) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe audio duration (${audioStream.durationSeconds}s) does not match the expected video ` +
+        `duration (${expectedDuration}s, tolerance ${tolerance}s) for ${outAbs}.`,
+    );
+  }
+}
+
+/** Build one FFmpeg image-sequence-to-video invocation's args for `format` — split out of {@link renderCinematic} to keep its own branch count down. Returns `undefined` for `format: 'png'` (no encode step). */
+function buildEncodeArgs(
+  format: RenderCinematicFormat,
+  pattern: string,
+  outAbs: string,
+  resolved: ResolvedRenderCinematicRequest,
+): { args: string[]; codec: { video: string; container: string } } | undefined {
+  const common = ['-y', '-loglevel', 'error', '-framerate', String(resolved.fps), '-i', pattern];
+  if (format === 'mp4') {
+    return {
+      args: [
+        ...common,
+        '-c:v',
+        'libx264',
+        '-pix_fmt',
+        'yuv420p',
+        '-r',
+        String(resolved.fps),
+        '-movflags',
+        '+faststart',
+        outAbs,
+      ],
+      codec: { video: 'libx264', container: 'mp4' },
+    };
+  }
+  if (format === 'webm') {
+    return {
+      args: [
+        ...common,
+        '-c:v',
+        'libvpx-vp9',
+        '-pix_fmt',
+        resolved.background === 'transparent' ? 'yuva420p' : 'yuv420p',
+        '-b:v',
+        '0',
+        '-crf',
+        '32',
+        '-r',
+        String(resolved.fps),
+        outAbs,
+      ],
+      codec: { video: 'libvpx-vp9', container: 'webm' },
+    };
+  }
+  return undefined;
+}
+
+/** Build one FFmpeg mux invocation's args for `format` — combines a
+ *  video-only encode ({@link buildEncodeArgs}'s output, stream-COPIED, never
+ *  re-encoded) with the WAV `renderToneOffline` produced, per the I6 AC's
+ *  literal "MP4 with `-c:v copy -c:a aac`" / "WebM with an opus/vorbis audio
+ *  stream". Split into its own function (rather than folded into {@link
+ *  buildEncodeArgs}) because it takes TWO inputs and runs as a SEPARATE
+ *  ffmpeg invocation after the video-only encode, not a single-pass
+ *  image-sequence encode. */
+function buildMuxArgs(
+  format: RenderCinematicFormat,
+  videoOnlyPath: string,
+  wavPath: string,
+  outAbs: string,
+): { args: string[]; codec: string } {
+  const common = ['-y', '-loglevel', 'error', '-i', videoOnlyPath, '-i', wavPath, '-c:v', 'copy'];
+  if (format === 'mp4') {
+    return {
+      args: [...common, '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', outAbs],
+      codec: 'aac',
+    };
+  }
+  // format === 'webm'
+  return {
+    args: [...common, '-c:a', 'libopus', outAbs],
+    codec: 'libopus',
+  };
+}
+
+/** Verify an encoded output's frame count/duration against the request via ffprobe (I7 AC: never report success on a mismatch) — split out of {@link renderCinematic} to keep its own branch count down. */
+function verifyEncodedOutput(
+  ffprobeResult: { nbFrames: number; durationSeconds: number },
+  outAbs: string,
+  resolved: ResolvedRenderCinematicRequest,
+): void {
+  if (ffprobeResult.nbFrames !== resolved.frameCount) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe frame count (${ffprobeResult.nbFrames}) does not match the requested frame count ` +
+        `(${resolved.frameCount}) for ${outAbs}. The render pipeline did NOT verify — this is a failure, ` +
+        'not a success with a warning.',
+    );
+  }
+  const expectedDuration = resolved.frameCount / resolved.fps;
+  const durationDelta = Math.abs(ffprobeResult.durationSeconds - expectedDuration);
+  // Container rounding tolerance: half a frame's worth of time.
+  const tolerance = 0.5 / resolved.fps;
+  if (durationDelta > tolerance) {
+    throw new RenderCinematicVerificationError(
+      `ffprobe duration (${ffprobeResult.durationSeconds}s) does not match the expected duration ` +
+        `(${expectedDuration}s, tolerance ${tolerance}s) for ${outAbs}.`,
+    );
+  }
+}
+
+/** A rendered-and-WAV-encoded audio track, ready to mux — the return of
+ *  {@link maybeCaptureAudio}, consumed by {@link encodeAndVerify}. */
+interface AudioCapturePlan {
+  readonly wavPath: string;
+  readonly sampleRate: number;
+  readonly channels: number;
+  readonly durationSeconds: number;
+  readonly wavDigest: string;
+}
+
+/**
+ * I6/G4 — detect whether the render page declares a Tone score
+ * (`window.__vgaiRenderAudio.hasAudio`, `@engine/runtime/render-audio-
+ * control`) and, if so, render it offline for the EXACT requested
+ * `[start, end)` range and write it to a WAV file inside `framesDir`. Must
+ * run BEFORE the page/browser is closed (it drives `page.evaluate`) — see
+ * its call site in {@link renderCinematic}, between `captureFrames` and the
+ * browser teardown.
+ *
+ * `resolved.audio === 'off'` skips this entirely (the explicit video-only
+ * escape hatch). `'on'` demands a declared score and throws before ANY
+ * encode work if the page has none. `'auto'` (default) is silent ONLY when
+ * no score is declared at all — once `hasAudio` is true, every failure past
+ * that point (a mismatched duration, a `renderAudio()` rejection) throws
+ * and aborts the whole render (propagating up through `renderCinematic`'s
+ * own try/catch, which then removes any partial output) — I6's "partial
+ * failures preserve diagnostics" AC read together with I7's "never report
+ * success merely because an output file exists": once a score is declared,
+ * shipping a video without its audio would be exactly that.
+ */
+async function maybeCaptureAudio(
+  page: Page,
+  resolved: ResolvedRenderCinematicRequest,
+  framesDir: string,
+  onProgress: ((e: RenderCinematicProgress) => void) | undefined,
+  signal?: AbortSignal,
+): Promise<AudioCapturePlan | undefined> {
+  if (resolved.audio === 'off') return undefined;
+
+  if (signal?.aborted) {
+    throw new RenderCinematicCancelledError(
+      'Render cancelled before audio capture.',
+      keepFramesOverride(signal),
+    );
+  }
+
+  onProgress?.({ phase: 'audio-detect' });
+  const hasAudio = await page.evaluate(
+    () =>
+      (globalThis as unknown as { __vgaiRenderAudio?: { hasAudio?: boolean } }).__vgaiRenderAudio
+        ?.hasAudio === true,
+  );
+  if (!hasAudio) {
+    if (resolved.audio === 'on') {
+      throw new RenderCinematicRequestError(
+        '--audio on was requested, but the render page never published window.__vgaiRenderAudio ' +
+          '(it does not declare a Tone score via installRenderAudioHarness — ' +
+          '@engine/runtime/render-audio-control).',
+      );
+    }
+    return undefined; // 'auto' + no declared score: video-only, exactly as before I6.
+  }
+
+  onProgress?.({ phase: 'audio-render' });
+  const rendered = await page.evaluate(
+    ({ start, end }) =>
+      (
+        globalThis as unknown as {
+          __vgaiRenderAudio: {
+            renderAudio(
+              start: number,
+              end: number,
+            ): Promise<{
+              wavBase64: string;
+              sampleRate: number;
+              channels: number;
+              durationSeconds: number;
+              rms: number;
+              peak: number;
+            }>;
+          };
+        }
+      ).__vgaiRenderAudio.renderAudio(start, end),
+    { start: resolved.start, end: resolved.end },
+  );
+
+  // Exact range alignment (I6 AC) — checked against the WAV's OWN reported
+  // duration before it is ever muxed, not just against the final container
+  // after the fact.
+  //
+  // G4 AC3 explicitness — start offset, duration, and tail policy:
+  //   - Start offset is `resolved.start`, the requested range's own start
+  //     (0 for a from-the-top render, non-zero for a mid-cinematic slice) —
+  //     passed straight to `renderAudio(start, end)` above, never hardcoded
+  //     to 0. Verified live by the i6 spec's "range/offset correctness" case
+  //     (renders `[1.0, 1.5)` and asserts non-silent, correctly-shifted audio).
+  //   - Duration is `resolved.end - resolved.start`, i.e. exactly
+  //     `frameCount / fps` — the same range the video side captures.
+  //   - Tail policy is NEITHER pad NOR truncate: `Tone.Offline`
+  //     (`audio/tone-offline-render.ts`) always renders exactly
+  //     `durationSeconds * sampleRate` samples by construction, so there is
+  //     no short/long tail to reconcile. This check exists purely as a
+  //     hard-fail guard (never silently pad/truncate a mismatch) — any
+  //     deviation beyond half a frame throws and aborts the render rather
+  //     than muxing misaligned audio.
+  const expectedDuration = resolved.frameCount / resolved.fps;
+  const durationDelta = Math.abs(rendered.durationSeconds - expectedDuration);
+  const tolerance = 0.5 / resolved.fps;
+  if (durationDelta > tolerance) {
+    throw new RenderCinematicVerificationError(
+      `Rendered audio duration (${rendered.durationSeconds}s) does not match the expected video ` +
+        `duration (${expectedDuration}s, tolerance ${tolerance}s) — refusing to mux mismatched audio.`,
+    );
+  }
+
+  const wavBytes = Buffer.from(rendered.wavBase64, 'base64');
+  const wavPath = join(framesDir, 'audio.wav');
+  await writeFile(wavPath, wavBytes);
+  onProgress?.({ phase: 'audio-render-done', durationSeconds: rendered.durationSeconds });
+
+  return {
+    wavPath,
+    sampleRate: rendered.sampleRate,
+    channels: rendered.channels,
+    durationSeconds: rendered.durationSeconds,
+    wavDigest: sha256(wavBytes),
+  };
+}
+
+/** Encode `framesDir`'s PNG sequence (when `format` isn't `'png'`), mux in `audioPlan` (when present), and verify the result with ffprobe — split out of {@link renderCinematic} to keep its own branch count down. ASYNC (I7 fold-in #9a) so a `signal` abort mid-encode can actually SIGKILL the in-flight ffmpeg child — see {@link runFfmpeg}. */
+async function encodeAndVerify(
+  framesDir: string,
+  outAbs: string,
+  resolved: ResolvedRenderCinematicRequest,
+  onProgress: ((e: RenderCinematicProgress) => void) | undefined,
+  audioPlan: AudioCapturePlan | undefined,
+  signal?: AbortSignal,
+): Promise<{
+  encode?: RenderManifestEncode;
+  ffprobeResult?: { nbFrames: number; durationSeconds: number };
+  audio?: RenderManifestAudio;
+}> {
+  if (resolved.format === 'png') return {};
+
+  const digits = Math.max(6, String(resolved.frameCount).length);
+  const pattern = join(framesDir, `frame-%0${digits}d.png`);
+  // With audio to mux, the frame-sequence encode targets a SCRATCH path
+  // inside framesDir (cleaned up with the rest of that temp dir), and the
+  // requested `outAbs` is produced by the separate mux step below instead —
+  // with no audio, this is `outAbs` directly, IDENTICAL to pre-I6 behavior.
+  const videoEncodeTarget = audioPlan ? join(framesDir, `video-only.${resolved.format}`) : outAbs;
+  const built = buildEncodeArgs(resolved.format, pattern, videoEncodeTarget, resolved);
+  if (!built) return {};
+
+  onProgress?.({ phase: 'encode-start', format: resolved.format });
+  await runFfmpeg(built.args, signal);
+  const encode: RenderManifestEncode = {
+    format: resolved.format,
+    outputPath: audioPlan ? outAbs : videoEncodeTarget,
+    command: ['ffmpeg', ...built.args],
+    codec: built.codec,
+  };
+  onProgress?.({ phase: 'encode-done', outputPath: videoEncodeTarget });
+
+  let audio: RenderManifestAudio | undefined;
+  if (audioPlan) {
+    if (signal?.aborted) {
+      throw new RenderCinematicCancelledError(
+        'Render cancelled before audio mux.',
+        keepFramesOverride(signal),
+      );
+    }
+    onProgress?.({ phase: 'audio-mux-start' });
+    const muxBuilt = buildMuxArgs(resolved.format, videoEncodeTarget, audioPlan.wavPath, outAbs);
+    await runFfmpeg(muxBuilt.args, signal);
+    onProgress?.({ phase: 'audio-mux-done', outputPath: outAbs });
+    audio = {
+      codec: muxBuilt.codec,
+      container: resolved.format,
+      sampleRate: audioPlan.sampleRate,
+      channels: audioPlan.channels,
+      durationSeconds: audioPlan.durationSeconds,
+      wavDigest: audioPlan.wavDigest,
+      muxCommand: ['ffmpeg', ...muxBuilt.args],
+    };
+  }
+
+  onProgress?.({ phase: 'verify', outputPath: outAbs });
+  // `-c:v copy` in the mux step never re-encodes the video stream, so the
+  // frame count/duration ffprobe already proved on a video-only encode
+  // remains a valid check against the FINAL (possibly muxed) `outAbs`.
+  const ffprobeResult = runFfprobeFrameCountAndDuration(outAbs);
+  verifyEncodedOutput(ffprobeResult, outAbs, resolved);
+
+  if (audioPlan) {
+    const audioStream = runFfprobeAudioStream(outAbs);
+    verifyAudioOutput(audioStream, outAbs, resolved);
+  }
+
+  return { encode, ffprobeResult, ...(audio !== undefined ? { audio } : {}) };
+}
+
+interface OpenedRenderPage {
+  readonly page: Page;
+  readonly readiness: ReadinessReport;
+}
+
+/** Launch Chromium, open the render-mode page at an exact viewport/DPR with DOM/CSS animation frozen, and wait for `__vgaiRender.ready()` — split out of {@link renderCinematic} to keep its own branch count down. Caller owns closing the returned page's browser/context. */
+async function openRenderPage(
+  browser: Browser,
+  server: LaunchedServer,
+  resolved: ResolvedRenderCinematicRequest,
+  onProgress: ((e: RenderCinematicProgress) => void) | undefined,
+): Promise<OpenedRenderPage> {
+  const context = await browser.newContext({
+    viewport: { width: resolved.width, height: resolved.height },
+    deviceScaleFactor: resolved.dpr,
+  });
+  const page = await context.newPage();
+
+  // DOM/CSS animation freeze (I2 AC: "DOM/CSS animation clocks are frozen
+  // during capture") — this is the CAPTURE HOST's job, per the spec's own
+  // split (the runtime side is `render-control.ts`'s composition fence).
+  const cdp = await context.newCDPSession(page);
+  await cdp.send('Animation.enable');
+  await cdp.send('Animation.setPlaybackRate', { playbackRate: 0 });
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+
+  const pageUrl =
+    `${server.baseUrl}/?vgai-render=1&vgai-seed=${resolved.seed}` +
+    `&vgai-width=${resolved.width}&vgai-height=${resolved.height}` +
+    // I7 fold-in (I5 nit fix) — see RenderCinematicRequest.simulateFixedDt's
+    // doc comment: a fixture MAY read this to override its harness's
+    // simulateFixedDt; omitted entirely when the caller didn't ask for one,
+    // so a fixture with no reader for this param sees no behavior change.
+    (resolved.simulateFixedDt !== undefined
+      ? `&vgai-simulate-fixed-dt=${resolved.simulateFixedDt}`
+      : '');
+  await page.goto(pageUrl, { waitUntil: 'load' });
+  await page.waitForFunction(() =>
+    Boolean((globalThis as unknown as { __vgaiRender?: unknown }).__vgaiRender),
+  );
+
+  const readiness = (await page.evaluate(() =>
+    (
+      globalThis as unknown as { __vgaiRender: { ready(): Promise<ReadinessReport> } }
+    ).__vgaiRender.ready(),
+  )) as ReadinessReport;
+  onProgress?.({ phase: 'page-ready', readiness });
+  for (const [name, entry] of Object.entries(readiness)) {
+    if (entry.status === 'error') {
+      throw new Error(
+        `Render page readiness failed for "${name}": ${entry.detail ?? '(no detail)'}`,
+      );
+    }
+  }
+
+  return { page, readiness };
+}
+
+/** A live render-mode page session, opened WITHOUT driving a frame-capture
+ *  loop — see {@link openRenderCinematicPage}. */
+export interface RenderCinematicPageSession {
+  readonly page: Page;
+  readonly resolved: ResolvedRenderCinematicRequest;
+  /** Closes the page/context, the browser, and stops the spawned dev server (if any). */
+  close(): Promise<void>;
+}
+
+/**
+ * Open a live render-mode page — preflight, dev-server launch, headless
+ * Chromium launch, DOM/CSS-animation freeze, navigate, and wait for
+ * `__vgaiRender.ready()` — WITHOUT running {@link renderCinematic}'s own
+ * frame-capture/encode loop. This exposes the raw Playwright `Page` for a
+ * caller that needs a CUSTOM `window.__vgaiRender` call sequence beyond the
+ * standard "advanceFrame, seekFrame, renderOnce, screenshot" loop
+ * {@link renderCinematic} drives internally — the motivating case is a test
+ * that proves the I8 `advanceFrame` render-integration seam by choosing
+ * exactly when (and how many times) to call it relative to `seekFrame`
+ * (`packages/engine/e2e/tests/render-cinematic-i8.spec.ts`).
+ *
+ * Reuses the exact same {@link launchEntryServer}/{@link openRenderPage}
+ * building blocks {@link renderCinematic} itself calls — this is an
+ * ADDITIVE export, not a refactor of the main pipeline's control flow, so it
+ * carries no risk to the existing `renderCinematic` behavior/tests.
+ */
+export async function openRenderCinematicPage(
+  request: RenderCinematicRequest,
+): Promise<RenderCinematicPageSession> {
+  const resolved = await resolveEffectivePort(request, resolveRenderCinematicRequest(request));
+  const server = await launchEntryServer(
+    resolved.entry,
+    resolved.port,
+    resolved.engineRoot,
+    undefined,
+  );
+  let browser: Browser | undefined;
+  try {
+    browser = await chromium.launch({
+      headless: true,
+      args: ['--use-gl=angle', '--use-angle=swiftshader'],
+      // B7 review fold-in (SIGINT race): Playwright's DEFAULT is to install
+      // its own SIGINT/SIGTERM/SIGHUP handlers on the launched browser that
+      // close it and then call `process.exit(130)` directly — racing (and,
+      // on the Ink-mounted TTY path, BEATING) the CLI's own
+      // `EXIT_CODES.CANCELLED` (4) exit. Cancellation here is exclusively
+      // owned by the caller's `AbortSignal`/process-signal wiring (see
+      // `onAbort` below in `renderCinematic`, and `runRenderCinematic`'s
+      // `process.on('SIGINT'/'SIGTERM', ...)` in the CLI) — Playwright
+      // must never race that single owner with its own `process.exit()`.
+      handleSIGINT: false,
+      handleSIGTERM: false,
+      handleSIGHUP: false,
+    });
+    const { page } = await openRenderPage(browser, server, resolved, undefined);
+    const openedBrowser = browser;
+    return {
+      page,
+      resolved,
+      async close() {
+        await page
+          .context()
+          .close()
+          .catch(() => {});
+        await openedBrowser.close().catch(() => {});
+        await server.stop().catch(() => {});
+      },
+    };
+  } catch (err) {
+    if (browser) await browser.close().catch(() => {});
+    await server.stop().catch(() => {});
+    throw err;
+  }
+}
+
+interface PreparedOutputs {
+  readonly outAbs: string;
+  readonly framesDir: string;
+}
+
+/** Preflight ffmpeg, validate `out` doesn't collide, and create the frames dir — split out of {@link renderCinematic} to keep its own branch count down. Everything here runs BEFORE any browser is launched (I1 AC). */
+async function preparePipelineOutputs(
+  resolved: ResolvedRenderCinematicRequest,
+): Promise<PreparedOutputs> {
+  if (resolved.format !== 'png') {
+    const ffmpegCheck = checkFfmpegCapability();
+    if (!ffmpegCheck.ok) throw new RenderCinematicFfmpegError(ffmpegCheck.errors);
+  }
+
+  const outAbs = resolvePath(resolved.out);
+  if (!resolved.overwrite && existsSync(outAbs) && resolved.format !== 'png') {
+    throw new RenderCinematicRequestError(
+      `${outAbs} already exists. Pass --overwrite to replace it.`,
+    );
+  }
+  await mkdir(dirname(outAbs), { recursive: true });
+
+  const framesDir =
+    resolved.format === 'png' ? outAbs : await mkdtemp(join(tmpdir(), 'vgai-render-cinematic-'));
+  if (resolved.format === 'png') await mkdir(framesDir, { recursive: true });
+
+  return { outAbs, framesDir };
+}
+
+/**
+ * Build the I5 `RenderManifestSimulate` object iff `resolved.simulate` —
+ * split out purely to keep {@link renderCinematic}'s own body short.
+ *
+ * I7 fold-in (I5 nit fix): `fixedTimestep` used to be hardcoded to `1/60`
+ * regardless of what the fixture actually configured
+ * (`RenderControlHarnessOptions.simulateFixedDt`) — silently wrong for any
+ * fixture that set a different substep dt. `actualFixedDt` is
+ * {@link readSimulateFixedDt}'s result — the REAL value read off the live
+ * harness right before the page closed. The `?? 1 / 60` fallback below is
+ * ONLY reached for a render-mode page that predates the
+ * `simulateFixedDt()` harness method (an older/unmodified page) — an
+ * honestly-commented "best known default", not a value ever claimed to be
+ * measured.
+ */
+function buildSimulateManifest(
+  resolved: ResolvedRenderCinematicRequest,
+  actualFixedDt: number | undefined,
+): RenderManifestSimulate | undefined {
+  if (!resolved.simulate) return undefined;
+  return {
+    seed: resolved.seed,
+    substeps: resolved.simulateSubsteps,
+    warmupSubsteps: resolved.simulateWarmupSubsteps,
+    // Honest fallback only: the harness didn't expose `simulateFixedDt()`
+    // (predates I7), so this is the engine-wide documented default
+    // (`render-control.ts`'s own `1/60`), NOT a measured value.
+    fixedTimestep: actualFixedDt ?? 1 / 60,
+  };
+}
+
+/** Write the render manifest and clean up the temp frames dir per retention policy — split out of {@link renderCinematic} to keep its own branch count down. */
+async function finalizeResult(
+  prepared: PreparedOutputs,
+  resolved: ResolvedRenderCinematicRequest,
+  frameHashes: readonly string[],
+  encode: RenderManifestEncode | undefined,
+  ffprobeResult: { nbFrames: number; durationSeconds: number } | undefined,
+  audio: RenderManifestAudio | undefined,
+  excludedFromDeterminism: readonly string[],
+  warnings: readonly string[],
+  actualSimulateFixedDt: number | undefined,
+): Promise<RenderCinematicResult> {
+  const { outAbs, framesDir } = prepared;
+  const framesDigest = sha256(Buffer.from(frameHashes.join('\n'), 'utf-8'));
+  const outputPath = resolved.format === 'png' ? framesDir : outAbs;
+  const durationSeconds = resolved.frameCount / resolved.fps;
+  const simulate = buildSimulateManifest(resolved, actualSimulateFixedDt);
+
+  const manifestPath = `${outAbs}.manifest.json`;
+  const manifest = {
+    request: resolved,
+    outputPath,
+    frameCount: resolved.frameCount,
+    durationSeconds,
+    frameHashes,
+    framesDigest,
+    encode,
+    ffprobe: ffprobeResult,
+    audio,
+    simulate,
+    excludedFromDeterminism,
+    warnings,
+    generatedAt: new Date().toISOString(),
+  };
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+
+  if (!resolved.keepFrames && resolved.format !== 'png') {
+    await rm(framesDir, { recursive: true, force: true });
+  }
+
+  return {
+    request: resolved,
+    outputPath,
+    manifestPath,
+    frameCount: resolved.frameCount,
+    durationSeconds,
+    frameHashes,
+    framesDigest,
+    ...(encode !== undefined ? { encode } : {}),
+    ...(ffprobeResult !== undefined ? { ffprobe: ffprobeResult } : {}),
+    ...(audio !== undefined ? { audio } : {}),
+    ...(simulate !== undefined ? { simulate } : {}),
+    excludedFromDeterminism,
+    warnings,
+  };
+}
+
+/**
+ * Failure-path cleanup for {@link renderCinematic}'s `catch` block — split
+ * out purely to keep that function's own cognitive-complexity score down
+ * (same helper-splitting convention this file already uses throughout,
+ * e.g. {@link resolveFrameRange}).
+ *
+ * Never leaves a partially-encoded output looking like a real one on
+ * failure (I7 AC) — the temp frames dir is left in place (minus the
+ * `format: 'png'` case, which never had one) so a human can inspect what
+ * was captured before the failure.
+ *
+ * ADDITIVE (B5): a genuine CANCELLATION (as opposed to an ordinary failure,
+ * which deliberately preserves the temp frames dir for inspection — see
+ * above) ALSO removes the incomplete temp frames dir, unless retention was
+ * requested — either at cancel-time (`signal.reason.keepFrames`, carried on
+ * the thrown error) or, absent that override, by the original request's own
+ * `keepFrames`. Never reached when `options.signal` was never given (every
+ * pre-existing caller): `signal` is `undefined` and never `.aborted` in that
+ * case.
+ *
+ * Detecting "was this a cancellation" via `signal?.aborted` — NOT merely
+ * `err instanceof RenderCinematicCancelledError` — matters because of a real
+ * race documented at `renderCinematic`'s own `onAbort` listener: that
+ * listener closes the browser/vite-group the INSTANT `signal` fires, which
+ * can race ahead of the cooperative `signal?.aborted` checks inside
+ * `captureFrames`/`maybeCaptureAudio`/`encodeAndVerify`. When it wins that
+ * race, the in-flight `page.evaluate`/`page.locator().screenshot()` call
+ * itself rejects with Playwright's own "Target page, context or browser has
+ * been closed" error instead — a real `Error`, not a
+ * `RenderCinematicCancelledError` — even though the render was genuinely
+ * cancelled. Gating cleanup on `err instanceof RenderCinematicCancelledError`
+ * alone left the temp frames dir leaked on exactly that race (reproduced via
+ * a real `vgai render-cinematic` + SIGINT on this box, not merely a unit
+ * test — the committed I7 Playwright proof's synchronous `controller.abort()`
+ * call, right after an `onProgress` callback returns, never lands mid-flight
+ * and so never exercised this path).
+ */
+async function cleanupAfterFailure(
+  err: unknown,
+  resolved: ResolvedRenderCinematicRequest,
+  outAbs: string,
+  framesDir: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (resolved.format !== 'png' && existsSync(outAbs) && !resolved.keepFrames) {
+    await rm(outAbs, { force: true }).catch(() => {});
+  }
+  const wasCancelled = err instanceof RenderCinematicCancelledError || signal?.aborted === true;
+  if (wasCancelled && resolved.format !== 'png') {
+    const keep =
+      (err instanceof RenderCinematicCancelledError ? err.keepFrames : undefined) ??
+      keepFramesOverride(signal) ??
+      resolved.keepFrames;
+    if (!keep) {
+      await rm(framesDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/**
+ * `vgai render-cinematic` — the full pipeline (I0/I2-I4/I6/I7). Preflights
+ * ffmpeg/ffprobe and validates the request BEFORE launching any browser
+ * (I1 AC), then: serves/launches the render-mode page, waits on
+ * `__vgaiRender.ready()`, sets an exact viewport + deviceScaleFactor,
+ * freezes DOM/CSS animation via CDP, captures every composited frame,
+ * encodes with FFmpeg, and verifies the output with ffprobe — throwing
+ * (never resolving) if verification fails, so a caller can never mistake a
+ * partially-broken output for a successful render.
+ */
+export async function renderCinematic(
+  request: RenderCinematicRequest,
+  options: RenderCinematicOptions = {},
+): Promise<RenderCinematicResult> {
+  const onProgress = options.onProgress;
+  const signal = options.signal;
+  const resolved = await resolveEffectivePort(request, resolveRenderCinematicRequest(request));
+
+  onProgress?.({ phase: 'preflight' });
+  const prepared = await preparePipelineOutputs(resolved);
+  const { outAbs, framesDir } = prepared;
+
+  if (signal?.aborted) {
+    // I7 fold-in (#9a — cancellation race): this is the EARLIEST possible
+    // cancellation point — `preparePipelineOutputs` (immediately above)
+    // already created `framesDir` on disk, so throwing here without cleanup
+    // leaked it (reproduced by a real abort landing before the dev server
+    // even starts, not merely a hypothetical). `cleanupAfterFailure` is a
+    // no-op on everything else at this point (no `outAbs` output could
+    // possibly exist yet), so this is just the framesDir removal, done
+    // explicitly rather than pulled into a broader try/catch this early.
+    const err = new RenderCinematicCancelledError(
+      'Render cancelled before the dev server launched.',
+      keepFramesOverride(signal),
+    );
+    await cleanupAfterFailure(err, resolved, outAbs, framesDir, signal);
+    throw err;
+  }
+
+  // I7 fold-in (#9a — cancellation race): `launchEntryServer` runs BEFORE
+  // the main try/catch below (there is no `server`/`browser` to tear down
+  // in that `finally` yet), but it can still throw a genuine
+  // cancellation-driven failure — `waitForHttpOk`'s own `signal?.aborted`
+  // check inside `launchEntryServer` throws a plain `Error` (wrapped again
+  // by `launchEntryServer`'s own catch, losing any `RenderCinematicCancelledError`-
+  // ness entirely) if `signal` aborts while still waiting for the dev server
+  // to come up. Without this try/catch, THAT throw skipped
+  // `cleanupAfterFailure` completely (it's outside the main try block) and
+  // leaked the temp frames dir `preparePipelineOutputs` already created
+  // above — reproduced by a real abort landing this early, not merely a
+  // hypothetical.
+  let server: LaunchedServer;
+  try {
+    server = await launchEntryServer(
+      resolved.entry,
+      resolved.port,
+      resolved.engineRoot,
+      onProgress,
+      signal,
+    );
+  } catch (err) {
+    await cleanupAfterFailure(err, resolved, outAbs, framesDir, signal);
+    throw err;
+  }
+
+  let browser: Browser | undefined;
+  const warnings: string[] = [];
+  // I7 fold-in (#9a — cancellation/orphan): tear down the browser AND the
+  // vite dev server's WHOLE PROCESS GROUP the INSTANT `signal` aborts,
+  // rather than waiting for the next cooperative per-frame check
+  // (`captureFrames`'s `signal?.aborted` guard) to be reached. This is what
+  // makes a slow/hung in-flight `page.evaluate`/`page.screenshot` call, or a
+  // long single ffmpeg encode, never keep the browser/vite group alive a
+  // moment longer than necessary — `server.stop()` already group-kills vite
+  // (`stopServerProcess`, above), and both calls are idempotent/`.catch`-
+  // guarded so racing against the normal `finally` cleanup below is safe.
+  const onAbort = (): void => {
+    browser?.close().catch(() => {});
+    server.stop().catch(() => {});
+  };
+  signal?.addEventListener('abort', onAbort, { once: true });
+  try {
+    onProgress?.({ phase: 'browser-launch' });
+    browser = await chromium.launch({
+      headless: true,
+      args: ['--use-gl=angle', '--use-angle=swiftshader'],
+      // B7 review fold-in (SIGINT race, #10): without this, Playwright
+      // installs its OWN SIGINT/SIGTERM/SIGHUP handlers that close the
+      // browser and call `process.exit(130)` directly — racing the CLI's
+      // `EXIT_CODES.CANCELLED` (4) exit this function's own `onAbort`
+      // (above) and the CLI's `process.on('SIGINT'/'SIGTERM', ...)`
+      // (`runRenderCinematic` in `packages/vgai-cli/src/index.ts`) already
+      // drive via `signal`. On the piped/non-TTY CLI path the CLI's own
+      // `process.exit(EXIT_CODES.CANCELLED)` happened to win that race most
+      // of the time; on the Ink-mounted TTY path the extra
+      // settle-then-unmount delay before the CLI's own exit reliably LOST
+      // it, surfacing a raw Playwright "Target page ... has been closed"
+      // error and exit code 130 instead of the I7 contract. The
+      // `AbortController`/signal wiring is the single owner of cancellation
+      // end-to-end — Playwright must never race it with its own
+      // `process.exit()`.
+      handleSIGINT: false,
+      handleSIGTERM: false,
+      handleSIGHUP: false,
+    });
+    const { page } = await openRenderPage(browser, server, resolved, onProgress);
+
+    const frameHashes = await captureFrames(page, framesDir, resolved, onProgress, signal);
+
+    // I6/G4 — must run BEFORE the page/browser closes (drives page.evaluate
+    // against window.__vgaiRenderAudio). A declared-but-failing score throws
+    // here and aborts the whole render (see maybeCaptureAudio's doc comment).
+    const audioPlan = await maybeCaptureAudio(page, resolved, framesDir, onProgress, signal);
+
+    // I5 AC 5 — read BEFORE the page/browser closes, same constraint as the
+    // audio capture above (drives page.evaluate against window.__vgaiRender).
+    const excludedFromDeterminism = await readExcludedFromDeterminism(page);
+    // I7 fold-in (I5 nit) — the ACTUAL harness dt, read before the page/
+    // browser closes, same constraint as the two calls above. `undefined`
+    // for a non-`--simulate` request (never called) or a render-mode page
+    // that predates this harness method (back-compat fallback in
+    // `buildSimulateManifest`).
+    const actualSimulateFixedDt = resolved.simulate ? await readSimulateFixedDt(page) : undefined;
+
+    await page.context().close();
+    await browser.close();
+    browser = undefined;
+
+    if (signal?.aborted) {
+      throw new RenderCinematicCancelledError(
+        'Render cancelled before encode.',
+        keepFramesOverride(signal),
+      );
+    }
+
+    // format === 'png': no encode step, framesDir IS outAbs already.
+    const { encode, ffprobeResult, audio } = await encodeAndVerify(
+      framesDir,
+      outAbs,
+      resolved,
+      onProgress,
+      audioPlan,
+      signal,
+    );
+
+    const result = await finalizeResult(
+      prepared,
+      resolved,
+      frameHashes,
+      encode,
+      ffprobeResult,
+      audio,
+      excludedFromDeterminism,
+      warnings,
+      actualSimulateFixedDt,
+    );
+    onProgress?.({ phase: 'complete', outputPath: result.outputPath });
+    return result;
+  } catch (err) {
+    await cleanupAfterFailure(err, resolved, outAbs, framesDir, signal);
+    throw err;
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+    if (browser) await browser.close().catch(() => {});
+    await server.stop().catch(() => {});
+  }
+}
+
+/** Re-read a manifest written by {@link renderCinematic} — used by the CLI's human-readable printer and by tests. */
+export async function readRenderManifest(manifestPath: string): Promise<unknown> {
+  return JSON.parse(await readFile(manifestPath, 'utf-8'));
+}