@vgai/sdk 0.4.0-canary.20260715.0

package/src/cinematic/render-operations.ts

@@ -0,0 +1,409 @@
+/**
+ * `cinematic.render` / `cinematic.render.status` / `cinematic.render.cancel`
+ * (B5, §8 B5 "render and render-status", "cancel rendering"; ACs: "Render
+ * jobs expose progress, current frame, elapsed time, and output paths";
+ * "Cancellation removes incomplete temporary frames unless retention is
+ * requested"; "Render errors include the failing frame/time and originating
+ * subsystem"). See `./render-transport.ts`'s module jsdoc for the job-
+ * registry design this wraps.
+ *
+ * `cinematic.render` is pinned `host: 'node'` + `longRunning: true` + a real
+ * `render: true` requirement, per §8 B1's review-hardened addition
+ * ("`cinematic.render` is host `node` and a long-running job — it launches
+ * its own browser and MUST NOT ride the editor relay's ~5s timeout") — this
+ * is the REAL implementation that replaces B1's `operations.ts` stand-in
+ * (which always threw `NOT_IMPLEMENTED`; see that file's updated jsdoc).
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import {
+  RenderCinematicFfmpegError,
+  type RenderCinematicRequest,
+  RenderCinematicRequestError,
+} from '../render/render-cinematic.js';
+import {
+  type CinematicRenderJobStatus,
+  getCinematicRenderFn,
+  getRenderJob,
+  startRenderJob,
+} from './render-transport.js';
+
+// ---------------------------------------------------------------------------
+// Shared error definitions
+// ---------------------------------------------------------------------------
+
+const RENDER_REQUEST_INVALID_ERROR: ErrorDefinition = {
+  code: 'RENDER_REQUEST_INVALID',
+  summary:
+    'The render request failed validation (I1 AC: "fail before launching the browser") — no job ' +
+    'was created.',
+  data: z.object({ message: z.string() }),
+};
+
+const RENDER_CAPABILITY_UNAVAILABLE_ERROR: ErrorDefinition = {
+  code: 'RENDER_CAPABILITY_UNAVAILABLE',
+  summary: 'ffmpeg/ffprobe preflight failed (A1) — no job was created.',
+  data: z.object({ message: z.string() }),
+};
+
+const RENDER_JOB_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'RENDER_JOB_NOT_FOUND',
+  summary: 'No render job with the given jobId exists (this process’s in-memory job registry).',
+  data: z.object({ jobId: z.string() }),
+};
+
+const RENDER_JOB_NOT_RUNNING_ERROR: ErrorDefinition = {
+  code: 'RENDER_JOB_NOT_RUNNING',
+  summary: 'The job has already settled (completed/failed/cancelled) — nothing to cancel.',
+  data: z.object({ jobId: z.string(), status: z.string() }),
+};
+
+// ---------------------------------------------------------------------------
+// Shared input/result fragments — mirrors I1's RenderCinematicRequest shape.
+// ---------------------------------------------------------------------------
+
+const CinematicRenderInput = z.object({
+  entry: z
+    .string()
+    .describe(
+      'Either an http(s) URL to an already-serving render-mode page, or a filesystem path to a Vite config to spawn.',
+    ),
+  out: z.string().describe('Output file path (mp4/webm) or output directory (png format).'),
+  format: z.enum(['mp4', 'webm', 'png']).optional(),
+  fps: z.number().positive().optional(),
+  start: z.number().min(0).optional().describe('Range start, seconds. Default 0.'),
+  end: z.number().optional().describe('Range end, seconds. Supply exactly one of end/frameCount.'),
+  frameCount: z.number().int().positive().optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  dpr: z.number().positive().optional(),
+  seed: z.number().int().optional(),
+  background: z.enum(['opaque', 'transparent']).optional(),
+  audio: z.enum(['auto', 'on', 'off']).optional(),
+  overwrite: z.boolean().optional(),
+  keepFrames: z
+    .boolean()
+    .optional()
+    .describe(
+      'Retain the temporary per-frame PNG directory after the render finishes OR is cancelled.',
+    ),
+  port: z.number().int().positive().optional(),
+  simulate: z
+    .boolean()
+    .optional()
+    .describe(
+      'I5: advance the FULL fixed-step gameplay loop (physics/gameplay phases/AI/particles/' +
+        'participating audio) between captured frames via window.__vgaiRender.simulateSubsteps, ' +
+        'instead of the default sequence-controlled (Theatre/GSAP time-seek only) render.',
+    ),
+  simulateSubsteps: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Fixed gameplay substeps advanced per captured frame under --simulate. Default 4.'),
+  simulateWarmupSubsteps: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      'Fixed gameplay substeps advanced ONCE, before frame 0, under --simulate. Default 0 (no warmup).',
+    ),
+});
+
+const CinematicRenderResult = z.object({
+  jobId: z.string().describe('Opaque render job handle — poll with cinematic.render.status.'),
+  outPath: z.string().describe('Destination path the job will write to.'),
+  resolvedFrameCount: z
+    .number()
+    .int()
+    .describe('Frame count resolved from start/end/frameCount/fps.'),
+  resolvedFps: z.number(),
+});
+
+const CinematicRenderJobErrorSchema = z.object({
+  message: z.string(),
+  subsystem: z.string(),
+  frame: z.number().optional(),
+  time: z.number().optional(),
+});
+
+const CinematicRenderStatusResult = z.object({
+  jobId: z.string(),
+  status: z.enum(['running', 'completed', 'failed', 'cancelled']),
+  currentFrame: z.number(),
+  frameCount: z.number().optional(),
+  elapsedMs: z
+    .number()
+    .describe('Time since the job started (or, once settled, its total run time).'),
+  outputPath: z.string().optional(),
+  manifestPath: z.string().optional(),
+  durationSeconds: z.number().optional(),
+  warnings: z.array(z.string()),
+  error: CinematicRenderJobErrorSchema.optional(),
+});
+
+/** Bound on waiting for a cancelled job to actually settle (browser/ffmpeg teardown) before `cinematic.render.cancel` gives up and reports the best-known status anyway — never an unbounded hang. */
+const CANCEL_SETTLE_TIMEOUT_MS = 15_000;
+
+const CinematicRenderCancelInput = z.object({
+  jobId: z.string(),
+  keepFrames: z
+    .boolean()
+    .optional()
+    .describe(
+      'Cancel-time retention override — when given, wins over the original request’s own ' +
+        'keepFrames for the purpose of this cancellation’s temp-frame cleanup decision.',
+    ),
+});
+
+const CinematicRenderCancelResult = z.object({
+  jobId: z.string(),
+  status: z
+    .enum(['running', 'completed', 'failed', 'cancelled'])
+    .describe(
+      'The job’s status after cancellation was requested and awaited (bounded). Usually "cancelled", ' +
+        'but a job that finished/failed the instant before the abort signal was observed reports its ' +
+        'real terminal status rather than a fabricated "cancelled" — and a job whose browser/ffmpeg ' +
+        `teardown takes longer than the ${CANCEL_SETTLE_TIMEOUT_MS}ms bound still reports "running" ` +
+        '(abort WAS signalled; it just has not been confirmed yet — poll cinematic.render.status), ' +
+        'never a fabricated terminal state.',
+    ),
+});
+
+function elapsedMsFor(job: { startedAt: number; finishedAt?: number }): number {
+  return (job.finishedAt ?? Date.now()) - job.startedAt;
+}
+
+function statusResultFor(job: {
+  id: string;
+  status: CinematicRenderJobStatus;
+  startedAt: number;
+  finishedAt?: number;
+  currentFrame: number;
+  frameCount?: number;
+  outputPath?: string;
+  manifestPath?: string;
+  durationSeconds?: number;
+  warnings: string[];
+  error?: { message: string; subsystem: string; frame?: number; time?: number };
+}): z.infer<typeof CinematicRenderStatusResult> {
+  return {
+    jobId: job.id,
+    status: job.status,
+    currentFrame: job.currentFrame,
+    ...(job.frameCount !== undefined ? { frameCount: job.frameCount } : {}),
+    elapsedMs: elapsedMsFor(job),
+    ...(job.outputPath !== undefined ? { outputPath: job.outputPath } : {}),
+    ...(job.manifestPath !== undefined ? { manifestPath: job.manifestPath } : {}),
+    ...(job.durationSeconds !== undefined ? { durationSeconds: job.durationSeconds } : {}),
+    warnings: job.warnings,
+    ...(job.error !== undefined ? { error: job.error } : {}),
+  };
+}
+
+/** I5 fragment of {@link toRenderCinematicRequest} — split out purely to
+ *  keep that function's own branch count down (same "require*"/"resolve*"
+ *  helper-splitting convention `render-cinematic.ts` itself uses). */
+function toRenderCinematicSimulateFields(
+  input: z.infer<typeof CinematicRenderInput>,
+): Pick<RenderCinematicRequest, 'simulate' | 'simulateSubsteps' | 'simulateWarmupSubsteps'> {
+  return {
+    ...(input.simulate !== undefined ? { simulate: input.simulate } : {}),
+    ...(input.simulateSubsteps !== undefined ? { simulateSubsteps: input.simulateSubsteps } : {}),
+    ...(input.simulateWarmupSubsteps !== undefined
+      ? { simulateWarmupSubsteps: input.simulateWarmupSubsteps }
+      : {}),
+  };
+}
+
+/**
+ * Rebuild a `RenderCinematicRequest` from the Zod-validated input via
+ * conditional spreads — required under `exactOptionalPropertyTypes: true`
+ * (Zod's `.optional()` infers `field?: T | undefined`; `RenderCinematicRequest`
+ * declares plain `field?: T`, so passing the raw parsed object through
+ * directly does not structurally match).
+ */
+function toRenderCinematicRequest(
+  input: z.infer<typeof CinematicRenderInput>,
+): RenderCinematicRequest {
+  return {
+    entry: input.entry,
+    out: input.out,
+    ...(input.format !== undefined ? { format: input.format } : {}),
+    ...(input.fps !== undefined ? { fps: input.fps } : {}),
+    ...(input.start !== undefined ? { start: input.start } : {}),
+    ...(input.end !== undefined ? { end: input.end } : {}),
+    ...(input.frameCount !== undefined ? { frameCount: input.frameCount } : {}),
+    ...(input.width !== undefined ? { width: input.width } : {}),
+    ...(input.height !== undefined ? { height: input.height } : {}),
+    ...(input.dpr !== undefined ? { dpr: input.dpr } : {}),
+    ...(input.seed !== undefined ? { seed: input.seed } : {}),
+    ...(input.background !== undefined ? { background: input.background } : {}),
+    ...(input.audio !== undefined ? { audio: input.audio } : {}),
+    ...(input.overwrite !== undefined ? { overwrite: input.overwrite } : {}),
+    ...(input.keepFrames !== undefined ? { keepFrames: input.keepFrames } : {}),
+    ...(input.port !== undefined ? { port: input.port } : {}),
+    ...toRenderCinematicSimulateFields(input),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// cinematic.render
+// ---------------------------------------------------------------------------
+
+export const cinematicRender = defineOperation({
+  name: 'cinematic.render',
+  summary: 'Render a Theatre-driven cinematic sequence to a video or frame-sequence artifact.',
+  description:
+    'WRAPS packages/vgai-sdk/src/render/render-cinematic.ts’s renderCinematic (I0/I2-I8) as a background job: ' +
+    'validates + resolves the request synchronously (failing BEFORE any browser launches, I1 AC), ' +
+    'then fires the real pipeline WITHOUT awaiting it and returns a jobId immediately — poll ' +
+    'cinematic.render.status for progress/current-frame/elapsed-time/output-paths, or ' +
+    'cinematic.render.cancel to abort. Preview (cinematic.preview) and this op drive the exact same ' +
+    'window.__vgaiRender render-control harness / AnimationClock seam — the SAME canonical clock ' +
+    'implementation (§8 B5 AC).',
+  input: CinematicRenderInput,
+  result: CinematicRenderResult,
+  errors: [RENDER_REQUEST_INVALID_ERROR, RENDER_CAPABILITY_UNAVAILABLE_ERROR],
+  requires: { render: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: false,
+  longRunning: true,
+  permission: {
+    risk: 'write',
+    summary: 'Launches a headless browser + ffmpeg; writes rendered video/frame artifacts to disk.',
+  },
+  async impl(input, ctx) {
+    const renderFn = getCinematicRenderFn(ctx);
+    let job: ReturnType<typeof startRenderJob>;
+    try {
+      job = startRenderJob(toRenderCinematicRequest(input), renderFn);
+    } catch (err) {
+      if (err instanceof RenderCinematicRequestError) {
+        throw new OperationError('RENDER_REQUEST_INVALID', err.message, { message: err.message });
+      }
+      if (err instanceof RenderCinematicFfmpegError) {
+        throw new OperationError('RENDER_CAPABILITY_UNAVAILABLE', err.message, {
+          message: err.message,
+        });
+      }
+      throw err;
+    }
+    return {
+      jobId: job.id,
+      outPath: input.out,
+      resolvedFrameCount: job.frameCount ?? 0,
+      resolvedFps: job.fps ?? 30,
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.render.status
+// ---------------------------------------------------------------------------
+
+const CinematicRenderStatusInput = z.object({ jobId: z.string() });
+
+export const cinematicRenderStatus = defineOperation({
+  name: 'cinematic.render.status',
+  summary: 'Poll a cinematic.render job’s progress, current frame, elapsed time, and output paths.',
+  description:
+    'Reads the SAME in-memory job the dispatching cinematic.render call created — see ' +
+    './render-transport.ts. Errors (when status is "failed") include the failing frame/time and ' +
+    'originating subsystem (§8 B5 AC).',
+  input: CinematicRenderStatusInput,
+  result: CinematicRenderStatusResult,
+  errors: [RENDER_JOB_NOT_FOUND_ERROR],
+  requires: { render: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads this process’s in-memory render job registry only.' },
+  async impl(input) {
+    const job = getRenderJob(input.jobId);
+    if (!job) {
+      throw new OperationError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
+        jobId: input.jobId,
+      });
+    }
+    return statusResultFor(job);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.render.cancel
+// ---------------------------------------------------------------------------
+
+export const cinematicRenderCancel = defineOperation({
+  name: 'cinematic.render.cancel',
+  summary: 'Cancel a running cinematic.render job.',
+  description:
+    'Aborts the job’s render-cinematic.ts pipeline via its (B5-additive) AbortSignal seam, then ' +
+    `waits (bounded, ${CANCEL_SETTLE_TIMEOUT_MS}ms) for it to actually settle before returning the ` +
+    'real terminal status. Unless retention is requested (this call’s own keepFrames, or — absent ' +
+    'that override — the original request’s), incomplete temporary frames are removed (§8 B5 AC).',
+  input: CinematicRenderCancelInput,
+  result: CinematicRenderCancelResult,
+  errors: [RENDER_JOB_NOT_FOUND_ERROR, RENDER_JOB_NOT_RUNNING_ERROR],
+  requires: { render: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'destructive',
+    summary: 'Aborts a running render job and may delete its temporary frame files.',
+  },
+  async impl(input) {
+    const job = getRenderJob(input.jobId);
+    if (!job) {
+      throw new OperationError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
+        jobId: input.jobId,
+      });
+    }
+    if (job.status !== 'running') {
+      throw new OperationError(
+        'RENDER_JOB_NOT_RUNNING',
+        `Render job "${input.jobId}" has already settled (${job.status}) — nothing to cancel.`,
+        { jobId: input.jobId, status: job.status },
+      );
+    }
+    // Precedence for the pipeline's temp-frame cleanup decision:
+    //   cancel-time override (this call's keepFrames, if GIVEN)
+    //     > request-time keepFrames (resolved.keepFrames, the render request's own)
+    //       > default false.
+    // Critical: when this cancel supplies NO override, pass NO reason at all
+    // — so `signal.reason` carries no `keepFrames`, `keepFramesOverride`
+    // returns undefined, and the pipeline's `err.keepFrames ?? resolved.keepFrames`
+    // fallback genuinely consults the RESOLVED request's keepFrames. Passing
+    // `{ keepFrames: false }` here (the old `?? false`) would collapse
+    // "no override" into an EXPLICIT false, silently deleting the frames of a
+    // render that was started with request-time keepFrames:true — contradicting
+    // the AC ("unless retention is requested").
+    if (input.keepFrames !== undefined) {
+      job.abortController.abort({ keepFrames: input.keepFrames });
+    } else {
+      job.abortController.abort();
+    }
+    await Promise.race([
+      job.donePromise,
+      new Promise((resolve) => setTimeout(resolve, CANCEL_SETTLE_TIMEOUT_MS)),
+    ]);
+    // `job.status` is STILL 'running' iff the timeout won the race (an
+    // extremely slow browser/ffmpeg teardown) — reported as-is (see the
+    // result schema's own doc), never fabricated into a terminal state
+    // before it is actually true.
+    return { jobId: job.id, status: job.status };
+  },
+});
+
+/** Register cinematic.render / .status / .cancel onto `registry`. */
+export function registerRenderOperations(registry: OperationRegistry): void {
+  registry.register(cinematicRender);
+  registry.register(cinematicRenderStatus);
+  registry.register(cinematicRenderCancel);
+}

package/src/cinematic/render-transport.ts

@@ -0,0 +1,238 @@
+/**
+ * Job registry + transport seam for `cinematic.render` / `.status` / `.cancel`
+ * (B5, §8 B5 "render and render-status", "cancel rendering", plus the B5 AC:
+ * "Render jobs expose progress, current frame, elapsed time, and output
+ * paths" / "Cancellation removes incomplete temporary frames unless
+ * retention is requested" / "Render errors include the failing frame/time
+ * and originating subsystem").
+ *
+ * `cinematic.render` WRAPS the real, proven pipeline
+ * (`../render/render-cinematic.ts`'s `renderCinematic` — I0/I2-I8) as a
+ * background job: `startRenderJob` fires `renderCinematic(...)` WITHOUT
+ * awaiting it, records progress via `onProgress`, and returns a `jobId`
+ * synchronously — this is what makes `cinematic.render`'s own op resolve
+ * immediately (never riding the editor relay's short timeout, per §8 B1's
+ * review-hardened `host: 'node'` + `longRunning: true` requirement) while
+ * `cinematic.render.status` polls the SAME in-memory job for progress/
+ * current-frame/elapsed-time/output-paths, and `cinematic.render.cancel`
+ * aborts it via `RenderCinematicOptions.signal` (the B5-additive seam added
+ * to `render-cinematic.ts` — see that file's own jsdoc on
+ * `RenderCinematicCancelledError`).
+ *
+ * DEPENDENCY INJECTION: every op reads `ctx['cinematicRenderFn']` (falling
+ * back to the real `renderCinematic`) — the SAME "transport injected via
+ * ctx" convention `../play/transport.ts`/`../editor/transport.ts` establish,
+ * so unit tests can prove the whole job-registry state machine (progress
+ * tracking, status polling, cancellation, error classification) against a
+ * FAKE renderer that resolves/rejects/aborts on the test's own schedule —
+ * no real Playwright/ffmpeg process anywhere in that test file. The REAL
+ * proof (an actual Chromium + ffmpeg render dispatched through this exact
+ * registry) is a separate, deliberately NOT-vitest script — see this unit's
+ * commit message / build report for the invocation and its `ls -la`/
+ * `ffprobe` output.
+ *
+ * JOB REGISTRY LIFETIME: a plain in-process `Map`, matching this SDK's
+ * `node`-hosted, non-durable design elsewhere — jobs do not survive a
+ * process restart, and there is no persistence layer (a fresh CLI/HTTP/MCP
+ * process starts with an empty job map, same as e.g. `~/.vgai/editor-
+ * sessions.json` is NOT what this is — that registry is for discovering
+ * OTHER long-lived processes; a render job's lifetime is exactly this one
+ * process's).
+ */
+
+import {
+  RenderCinematicCancelledError,
+  RenderCinematicFfmpegError,
+  type RenderCinematicOptions,
+  type RenderCinematicProgress,
+  type RenderCinematicRequest,
+  RenderCinematicRequestError,
+  type RenderCinematicResult,
+  RenderCinematicVerificationError,
+  renderCinematic,
+  resolveRenderCinematicRequest,
+} from '../render/render-cinematic.js';
+import type { OperationContext } from '../types.js';
+
+export type CinematicRenderFn = (
+  request: RenderCinematicRequest,
+  options?: RenderCinematicOptions,
+) => Promise<RenderCinematicResult>;
+
+/** Resolve the render function to use: `ctx['cinematicRenderFn']` when injected (tests), else the real pipeline. */
+export function getCinematicRenderFn(ctx: OperationContext): CinematicRenderFn {
+  const injected = ctx['cinematicRenderFn'];
+  return (injected as CinematicRenderFn | undefined) ?? renderCinematic;
+}
+
+export type CinematicRenderJobStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+
+/** Maps a render-pipeline phase (`RenderCinematicProgress['phase']`) to the subsystem an error there should be attributed to (B5 AC: "originating subsystem"). */
+function subsystemForPhase(phase: string | undefined): string {
+  switch (phase) {
+    case undefined:
+    case 'preflight':
+      return 'preflight';
+    case 'server-launch':
+    case 'server-ready':
+      return 'dev-server';
+    case 'browser-launch':
+    case 'page-ready':
+      return 'browser';
+    case 'frame':
+      return 'capture';
+    case 'audio-detect':
+    case 'audio-render':
+    case 'audio-render-done':
+    case 'audio-mux-start':
+    case 'audio-mux-done':
+      return 'audio';
+    case 'encode-start':
+    case 'encode-done':
+      return 'ffmpeg';
+    case 'verify':
+      return 'ffprobe';
+    default:
+      return 'render-pipeline';
+  }
+}
+
+export interface CinematicRenderJobError {
+  readonly message: string;
+  readonly subsystem: string;
+  /** The frame index in progress (or last completed) when the failure occurred, when known. */
+  readonly frame?: number;
+  /** The corresponding time in seconds (frame / fps), when known. */
+  readonly time?: number;
+}
+
+export interface CinematicRenderJob {
+  readonly id: string;
+  status: CinematicRenderJobStatus;
+  readonly startedAt: number;
+  finishedAt?: number;
+  currentFrame: number;
+  frameCount?: number;
+  fps?: number;
+  lastPhase?: string;
+  outputPath?: string;
+  manifestPath?: string;
+  durationSeconds?: number;
+  warnings: string[];
+  error?: CinematicRenderJobError;
+  readonly abortController: AbortController;
+  /** Resolves once the job has fully settled (completed/failed/cancelled) — awaited (bounded) by `cinematic.render.cancel`. Assigned once, immediately after construction (see `startRenderJob`); not `readonly` purely because it is built from a promise chain that itself closes over this same job object. */
+  donePromise: Promise<void>;
+}
+
+const jobs = new Map<string, CinematicRenderJob>();
+
+let jobCounter = 0;
+function nextJobId(): string {
+  jobCounter += 1;
+  return `render-${Date.now().toString(36)}-${jobCounter}`;
+}
+
+export function getRenderJob(jobId: string): CinematicRenderJob | undefined {
+  return jobs.get(jobId);
+}
+
+/** Test-only: clear the module-level job registry between test files/cases so job ids never leak across tests. */
+export function _clearRenderJobsForTests(): void {
+  jobs.clear();
+  jobCounter = 0;
+}
+
+function classifyError(err: unknown, job: CinematicRenderJob): CinematicRenderJobError {
+  const time = job.fps ? job.currentFrame / job.fps : undefined;
+  const base = { frame: job.currentFrame, ...(time !== undefined ? { time } : {}) };
+  if (err instanceof RenderCinematicRequestError) {
+    return { message: err.message, subsystem: 'request', ...base };
+  }
+  if (err instanceof RenderCinematicFfmpegError) {
+    return { message: err.message, subsystem: 'ffmpeg', ...base };
+  }
+  if (err instanceof RenderCinematicVerificationError) {
+    return { message: err.message, subsystem: 'ffprobe', ...base };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return { message, subsystem: subsystemForPhase(job.lastPhase), ...base };
+}
+
+/**
+ * Start a render job: fires `renderFn(request, {...})` WITHOUT awaiting it,
+ * returns the new job immediately. `request` must already be validated
+ * (callers resolve/validate via `resolveRenderCinematicRequest` BEFORE
+ * calling this, per I1 AC "fail before launching the browser" — a request
+ * that fails validation never creates a job at all).
+ */
+export function startRenderJob(
+  request: RenderCinematicRequest,
+  renderFn: CinematicRenderFn,
+): CinematicRenderJob {
+  const id = nextJobId();
+  const abortController = new AbortController();
+  const resolved = resolveRenderCinematicRequest(request);
+
+  const job: CinematicRenderJob = {
+    id,
+    status: 'running',
+    startedAt: Date.now(),
+    currentFrame: 0,
+    // Known up-front from the RESOLVED request (I1: fps/frameCount are
+    // computed synchronously by resolveRenderCinematicRequest before any
+    // browser launches) — not left undefined until the first 'frame'
+    // progress event arrives, which would otherwise make
+    // cinematic.render's OWN immediate result (`resolvedFrameCount`) report
+    // a false "0" for the entire time before the first frame is captured.
+    frameCount: resolved.frameCount,
+    fps: resolved.fps,
+    warnings: [],
+    abortController,
+    donePromise: Promise.resolve(), // reassigned immediately below, once the real chain exists
+  };
+  jobs.set(id, job);
+
+  const onProgress = (event: RenderCinematicProgress): void => {
+    job.lastPhase = event.phase;
+    if (event.phase === 'frame') {
+      job.currentFrame = event.n;
+      job.frameCount = event.of;
+    }
+  };
+
+  job.donePromise = renderFn(request, { onProgress, signal: abortController.signal })
+    .then((result) => {
+      job.status = 'completed';
+      job.finishedAt = Date.now();
+      job.currentFrame = result.frameCount;
+      job.frameCount = result.frameCount;
+      job.outputPath = result.outputPath;
+      job.manifestPath = result.manifestPath;
+      job.durationSeconds = result.durationSeconds;
+      job.warnings = [...result.warnings];
+    })
+    .catch((err: unknown) => {
+      job.finishedAt = Date.now();
+      // Detect cancellation via `abortController.signal.aborted` — NOT
+      // merely `err instanceof RenderCinematicCancelledError` — for the
+      // same reason `render-cinematic.ts`'s own `cleanupAfterFailure` and
+      // the CLI's SIGINT handling do (see `cleanupAfterFailure`'s jsdoc in
+      // `render-cinematic.ts`): an abort landing mid-flight can race ahead of
+      // `renderCinematic`'s cooperative `signal?.aborted` checks, so the
+      // in-flight `page.evaluate`/screenshot call itself rejects with a raw
+      // Playwright error ("Target page, context or browser has been
+      // closed") instead of `RenderCinematicCancelledError` — even though
+      // the render was genuinely cancelled via THIS job's own
+      // `abortController`. Gating on the error type alone misreported that
+      // race as `status: 'failed'`.
+      if (err instanceof RenderCinematicCancelledError || abortController.signal.aborted) {
+        job.status = 'cancelled';
+      } else {
+        job.status = 'failed';
+        job.error = classifyError(err, job);
+      }
+    });
+
+  return job;
+}