@vgai/sdk 0.4.0-canary.20260715.0

package/src/cinematic/preview-operations.ts

@@ -0,0 +1,279 @@
+/**
+ * `cinematic.preview` / `cinematic.pause` / `cinematic.seek` / `cinematic.stop`
+ * (B5, §8 B5 "preview, pause, seek, and stop"). See
+ * `./preview-transport.ts`'s module jsdoc for the "real headless clock-seek
+ * preview, not a named gap" decision and why it proves "preview and render
+ * use the same canonical clock implementation" (§8 B5 AC) by construction.
+ *
+ * Flat names (`cinematic.pause`/`.seek`/`.stop`, not `cinematic.preview.
+ * pause`), matching the spec's own §5.7 example listing (`vgai.cinematic.
+ * preview(...)`) and this SDK's `play.*` precedent (`play.pause`/`play.
+ * resume`, not `play.control.pause`).
+ */
+
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import {
+  createPreviewSession,
+  getCinematicOpenPreviewFn,
+  getPreviewSession,
+  pausePreviewSession,
+  seekPreviewSession,
+  stopPreviewSession,
+} from './preview-transport.js';
+
+const PREVIEW_SESSION_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'PREVIEW_SESSION_NOT_FOUND',
+  summary:
+    'No open preview session with the given previewId exists (this process’s in-memory registry).',
+  data: z.object({ previewId: z.string() }),
+};
+
+const PreviewStateResult = z.object({
+  previewId: z.string(),
+  currentFrame: z.number(),
+  fps: z.number(),
+  frameCount: z
+    .number()
+    .describe('Total frames in the resolved preview range; last valid frame is frameCount - 1.'),
+  playing: z.boolean(),
+  ended: z
+    .boolean()
+    .describe(
+      'True once autoplay has advanced to (and stopped at) the last frame — distinguishes "played to the end" from an explicit pause.',
+    ),
+});
+
+function stateOf(session: {
+  id: string;
+  currentFrame: number;
+  playing: boolean;
+  ended: boolean;
+  handle: { fps: number; frameCount: number };
+}): z.infer<typeof PreviewStateResult> {
+  return {
+    previewId: session.id,
+    currentFrame: session.currentFrame,
+    fps: session.handle.fps,
+    frameCount: session.handle.frameCount,
+    playing: session.playing,
+    ended: session.ended,
+  };
+}
+
+function requireSession(previewId: string) {
+  const session = getPreviewSession(previewId);
+  if (!session) {
+    throw new OperationError(
+      'PREVIEW_SESSION_NOT_FOUND',
+      `No open preview session "${previewId}".`,
+      { previewId },
+    );
+  }
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// cinematic.preview
+// ---------------------------------------------------------------------------
+
+const CinematicPreviewInput = 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.',
+    ),
+  start: z.number().min(0).optional().describe('Initial time, seconds. Default 0.'),
+  end: z
+    .number()
+    .optional()
+    .describe(
+      'Range end, seconds — bounds how far autoplay advances. Supply at most one of end/frameCount; default is a 1s range (render-cinematic.ts’s own default).',
+    ),
+  frameCount: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Explicit frame count for the preview range (alternative to end).'),
+  fps: z.number().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(),
+  port: z.number().int().positive().optional(),
+  autoplay: z
+    .boolean()
+    .optional()
+    .describe('Start the forward-advancing loop immediately. Default true.'),
+  playbackRate: z.number().positive().optional().describe('Autoplay speed multiplier. Default 1.'),
+});
+
+export const cinematicPreview = defineOperation({
+  name: 'cinematic.preview',
+  summary:
+    'Open a headless preview session against a render-control-mode page and (by default) start playing it.',
+  description:
+    'Launches a real headless Chromium render-control page (the SAME `window.__vgaiRender` harness ' +
+    'cinematic.render drives — see ./preview-transport.ts module jsdoc) and, unless autoplay:false, ' +
+    'starts a forward-advancing loop calling seekFrame/renderOnce once per output frame. Returns a ' +
+    'previewId — control it with cinematic.pause/.seek/.stop.',
+  input: CinematicPreviewInput,
+  result: PreviewStateResult,
+  errors: [],
+  requires: { render: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Launches a headless browser page for interactive preview.',
+  },
+  async impl(input, ctx) {
+    const openFn = getCinematicOpenPreviewFn(ctx);
+    const handle = await openFn({
+      entry: input.entry,
+      // Unused by openRenderCinematicPage (which never encodes/writes an
+      // artifact) — a placeholder to satisfy RenderCinematicRequest's
+      // required `out` field.
+      out: join(tmpdir(), 'vgai-preview-unused.mp4'),
+      // NOTE: `input.start` is deliberately NOT forwarded to the render
+      // request. The harness frame index is absolute (frame n == time
+      // n/fps from 0), and resolveRenderCinematicRequest computes
+      // frameCount as (end - start) * fps — forwarding `start` would SHRINK
+      // the resolved frameCount and misalign it from the absolute index the
+      // preview loop seeks. `start` is applied purely as the local initial
+      // frame index below (round(start * fps)), within the 0..frameCount-1
+      // range that `end`/`frameCount` (absolute, from time 0) define.
+      ...(input.end !== undefined ? { end: input.end } : {}),
+      ...(input.frameCount !== undefined ? { frameCount: input.frameCount } : {}),
+      ...(input.fps !== undefined ? { fps: input.fps } : {}),
+      ...(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.port !== undefined ? { port: input.port } : {}),
+    });
+    const startFrame = input.start !== undefined ? Math.round(input.start * handle.fps) : 0;
+    // Establish a defined initial pose BEFORE autoplay's own loop (if any)
+    // fires its first tick — mirrors the render fixtures' own `clock.seek(0)`
+    // "defined initial pose before any external seek arrives" convention.
+    await handle.seekFrame(startFrame);
+    const session = createPreviewSession(
+      handle,
+      startFrame,
+      input.autoplay ?? true,
+      input.playbackRate ?? 1,
+    );
+    return stateOf(session);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.pause
+// ---------------------------------------------------------------------------
+
+const PreviewIdInput = z.object({ previewId: z.string() });
+
+export const cinematicPause = defineOperation({
+  name: 'cinematic.pause',
+  summary: 'Stop a preview session’s autoplay loop without closing it.',
+  description:
+    'The session stays open at its current frame — seek/resume-by-autoplay-restart remain available.',
+  input: PreviewIdInput,
+  result: PreviewStateResult,
+  errors: [PREVIEW_SESSION_NOT_FOUND_ERROR],
+  requires: { render: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Pauses a headless preview session only.' },
+  async impl(input) {
+    const session = requireSession(input.previewId);
+    pausePreviewSession(session);
+    return stateOf(session);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.seek
+// ---------------------------------------------------------------------------
+
+const CinematicSeekInput = z.object({
+  previewId: z.string(),
+  time: z
+    .number()
+    .min(0)
+    .optional()
+    .describe('Seek to this time, seconds. Supply exactly one of time/frame.'),
+  frame: z.number().int().min(0).optional().describe('Seek to this exact frame index.'),
+});
+
+export const cinematicSeek = defineOperation({
+  name: 'cinematic.seek',
+  summary: 'Seek a preview session to an exact time or frame.',
+  description:
+    'Works regardless of play state — a playing session continues autoplaying forward from the ' +
+    'new position on its next tick.',
+  input: CinematicSeekInput,
+  result: PreviewStateResult,
+  errors: [
+    PREVIEW_SESSION_NOT_FOUND_ERROR,
+    {
+      code: 'BAD_INPUT',
+      summary: 'Neither time nor frame was given, or both were.',
+      data: z.object({}),
+    },
+  ],
+  requires: { render: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Seeks a headless preview session only.' },
+  async impl(input) {
+    const session = requireSession(input.previewId);
+    if ((input.time === undefined) === (input.frame === undefined)) {
+      throw new OperationError('BAD_INPUT', 'Supply exactly one of time or frame.', {});
+    }
+    const frame = input.frame ?? Math.round(input.time! * session.handle.fps);
+    await seekPreviewSession(session, frame);
+    return stateOf(session);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.stop
+// ---------------------------------------------------------------------------
+
+export const cinematicStop = defineOperation({
+  name: 'cinematic.stop',
+  summary: 'Close a preview session (its page/browser) and forget it.',
+  description:
+    'Stops any running autoplay loop, closes the underlying headless browser page, and removes the session from the registry.',
+  input: PreviewIdInput,
+  result: z.object({ previewId: z.string() }),
+  errors: [PREVIEW_SESSION_NOT_FOUND_ERROR],
+  requires: { render: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: { risk: 'write', summary: 'Closes a headless preview session’s browser page.' },
+  async impl(input) {
+    const session = requireSession(input.previewId);
+    await stopPreviewSession(session);
+    return { previewId: input.previewId };
+  },
+});
+
+/** Register cinematic.preview / .pause / .seek / .stop onto `registry`. */
+export function registerPreviewOperations(registry: OperationRegistry): void {
+  registry.register(cinematicPreview);
+  registry.register(cinematicPause);
+  registry.register(cinematicSeek);
+  registry.register(cinematicStop);
+}

package/src/cinematic/preview-transport.ts

@@ -0,0 +1,244 @@
+/**
+ * Session registry + transport seam for `cinematic.preview` / `.pause` /
+ * `.seek` / `.stop` (B5, §8 B5 "preview, pause, seek, and stop").
+ *
+ * DECISION (per this unit's brief — "may target a runtime-page harness; if
+ * no live preview harness, a named error ... OR a headless clock-seek
+ * preview — decide + document"): a REAL headless clock-seek preview, not a
+ * named gap. There is no persistent, addressable "preview session" concept
+ * anywhere in this repo today (unlike `play.*`, which targets an EXISTING
+ * connected editor's browser tab over the `/__editor/command` relay) — the
+ * only thing that can drive `window.__vgaiRender` is a render-control-mode
+ * page (`?vgai-render=1`), and the only launcher for THAT page is
+ * `../render/render-cinematic.ts`'s own Playwright/Chromium launch,
+ * which is per-request-scoped, not a long-lived interactive session. Rather
+ * than declaring "no preview capability exists" (an honest but much less
+ * useful answer, and not actually true — the harness itself is real and
+ * launchable), this module launches its OWN headless page per preview
+ * session (via `openRenderCinematicPage`, the SAME additive I8 helper
+ * `renderCinematic` itself is built from) and drives it through
+ * `window.__vgaiRender.seekFrame`/`.renderOnce()` — THE EXACT SAME two
+ * calls `render-cinematic.ts`'s `captureFrames` makes for every captured
+ * frame. This is what makes "preview and render use the same canonical
+ * clock implementation" (§8 B5 AC) a literal, provable fact rather than an
+ * assertion: both paths bottom out in the identical harness call sequence.
+ *
+ * VCR SEMANTICS: `cinematic.preview` opens a session and (unless
+ * `autoplay: false`) starts a forward-advancing loop — one frame per tick,
+ * paced at the resolved fps (bounded below to avoid a runaway timer) —
+ * `cinematic.pause` stops that loop without closing the session,
+ * `cinematic.seek` jumps to an exact frame/time regardless of play state
+ * (continuing to play from the new position if it was playing),
+ * `cinematic.stop` closes the underlying page/browser and removes the
+ * session.
+ *
+ * DEPENDENCY INJECTION: `ctx['cinematicOpenPreviewFn']` overrides the real
+ * launcher (the same convention `./render-transport.ts`/`../play/
+ * transport.ts` use) with a narrow `CinematicPreviewHandle` — `seekFrame`/
+ * `fps`/`close()` only, never Playwright's full `Page` — so a unit test can
+ * prove the whole session state machine (autoplay pacing, pause/seek/stop,
+ * not-found handling) without a real browser anywhere in that test file.
+ */
+
+import type { RenderCinematicRequest } from '../render/render-cinematic.js';
+import { openRenderCinematicPage } from '../render/render-cinematic.js';
+import type { OperationContext } from '../types.js';
+
+/** The narrow surface preview sessions need — deliberately NOT Playwright's `Page` (see module jsdoc). */
+export interface CinematicPreviewHandle {
+  readonly fps: number;
+  /**
+   * Total frames in the resolved preview range (`resolveRenderCinematicRequest`'s
+   * `frameCount`) — the autoplay loop clamps at `frameCount - 1` (the last
+   * frame) so an abandoned autoplaying session can never tick a live headless
+   * Chromium forever. Valid frame indices are `0 .. frameCount - 1`.
+   */
+  readonly frameCount: number;
+  /** Seeks `window.__vgaiRender` to frame `n` (via `seekFrame(n, fps)`) and calls `renderOnce()` — the identical two-call sequence `render-cinematic.ts`'s `captureFrames` makes per frame. */
+  seekFrame(n: number): Promise<void>;
+  close(): Promise<void>;
+}
+
+export type CinematicOpenPreviewFn = (
+  request: RenderCinematicRequest,
+) => Promise<CinematicPreviewHandle>;
+
+interface HarnessGlobal {
+  __vgaiRender: {
+    seekFrame(n: number, fps: number): void;
+    renderOnce(): Promise<void>;
+  };
+}
+
+/** The real launcher — opens an actual headless Chromium render-control page. */
+async function openRealPreviewHandle(
+  request: RenderCinematicRequest,
+): Promise<CinematicPreviewHandle> {
+  const session = await openRenderCinematicPage(request);
+  const fps = session.resolved.fps;
+  return {
+    fps,
+    frameCount: session.resolved.frameCount,
+    async seekFrame(n: number) {
+      await session.page.evaluate(
+        async ({ n, fps }: { n: number; fps: number }) => {
+          const harness = (globalThis as unknown as HarnessGlobal).__vgaiRender;
+          harness.seekFrame(n, fps);
+          await harness.renderOnce();
+        },
+        { n, fps },
+      );
+    },
+    async close() {
+      await session.close();
+    },
+  };
+}
+
+/** Resolve the preview-page opener to use: `ctx['cinematicOpenPreviewFn']` when injected (tests), else the real launcher. */
+export function getCinematicOpenPreviewFn(ctx: OperationContext): CinematicOpenPreviewFn {
+  const injected = ctx['cinematicOpenPreviewFn'];
+  return (injected as CinematicOpenPreviewFn | undefined) ?? openRealPreviewHandle;
+}
+
+// ---------------------------------------------------------------------------
+// Session registry
+// ---------------------------------------------------------------------------
+
+/** A tick is never scheduled faster than this, regardless of a very high fps/playbackRate — a sanity floor against a runaway timer. */
+const MIN_TICK_MS = 10;
+
+export interface CinematicPreviewSession {
+  readonly id: string;
+  readonly handle: CinematicPreviewHandle;
+  currentFrame: number;
+  playing: boolean;
+  /** True once autoplay has reached the sequence's last frame and stopped on its own (as opposed to an explicit `cinematic.pause`). Surfaced so a caller can tell "played to the end" from "paused mid-way". */
+  ended: boolean;
+  playbackRate: number;
+  closed: boolean;
+  timer: ReturnType<typeof setTimeout> | undefined;
+}
+
+/** The last valid frame index of a session's range (`frameCount - 1`, never negative). */
+function lastFrameOf(session: CinematicPreviewSession): number {
+  return Math.max(0, session.handle.frameCount - 1);
+}
+
+const sessions = new Map<string, CinematicPreviewSession>();
+
+let sessionCounter = 0;
+function nextSessionId(): string {
+  sessionCounter += 1;
+  return `preview-${Date.now().toString(36)}-${sessionCounter}`;
+}
+
+export function getPreviewSession(id: string): CinematicPreviewSession | undefined {
+  const session = sessions.get(id);
+  return session && !session.closed ? session : undefined;
+}
+
+/** Test-only: clear the module-level session registry between test files/cases. */
+export function _clearPreviewSessionsForTests(): void {
+  for (const session of sessions.values()) {
+    if (session.timer !== undefined) clearTimeout(session.timer);
+  }
+  sessions.clear();
+  sessionCounter = 0;
+}
+
+function scheduleNextTick(session: CinematicPreviewSession): void {
+  if (!session.playing || session.closed) return;
+  const intervalMs = Math.max(MIN_TICK_MS, 1000 / (session.handle.fps * session.playbackRate));
+  session.timer = setTimeout(() => {
+    void tick(session);
+  }, intervalMs);
+}
+
+async function tick(session: CinematicPreviewSession): Promise<void> {
+  if (!session.playing || session.closed) return;
+  // BOUND (FOLD 1): never advance past the sequence's last frame. Without
+  // this an abandoned autoplaying preview would increment currentFrame
+  // unboundedly and keep seeking a live headless Chromium forever until an
+  // explicit cinematic.stop. At the end we stop ticking and mark `ended`.
+  if (session.currentFrame >= lastFrameOf(session)) {
+    session.playing = false;
+    session.ended = true;
+    return;
+  }
+  session.currentFrame += 1;
+  try {
+    await session.handle.seekFrame(session.currentFrame);
+  } catch {
+    // A tick failure stops autoplay rather than throwing into an
+    // unobserved timer callback — the session stays open (its LAST good
+    // frame stands) so a caller can still inspect/seek/stop it explicitly.
+    session.playing = false;
+    return;
+  }
+  if (session.currentFrame >= lastFrameOf(session)) {
+    // Reached the end ON this frame — stop now rather than scheduling one
+    // more no-op tick.
+    session.playing = false;
+    session.ended = true;
+    return;
+  }
+  scheduleNextTick(session);
+}
+
+export function createPreviewSession(
+  handle: CinematicPreviewHandle,
+  startFrame: number,
+  autoplay: boolean,
+  playbackRate: number,
+): CinematicPreviewSession {
+  const session: CinematicPreviewSession = {
+    id: nextSessionId(),
+    handle,
+    currentFrame: startFrame,
+    playing: false,
+    ended: false,
+    playbackRate,
+    closed: false,
+    timer: undefined,
+  };
+  sessions.set(session.id, session);
+  // Only arm autoplay if there is somewhere still to advance to — a preview
+  // opened AT (or past) the last frame is already `ended`, never a
+  // perpetually-"playing" session that never ticks.
+  if (autoplay && startFrame < lastFrameOf(session)) {
+    session.playing = true;
+    scheduleNextTick(session);
+  } else if (autoplay) {
+    session.ended = true;
+  }
+  return session;
+}
+
+export function pausePreviewSession(session: CinematicPreviewSession): void {
+  session.playing = false;
+  if (session.timer !== undefined) {
+    clearTimeout(session.timer);
+    session.timer = undefined;
+  }
+}
+
+export async function seekPreviewSession(
+  session: CinematicPreviewSession,
+  frame: number,
+): Promise<void> {
+  await session.handle.seekFrame(frame);
+  session.currentFrame = frame;
+  // A seek that lands before the end re-arms `ended` (the session is no
+  // longer stopped-at-the-end); a seek that lands AT the last frame leaves
+  // `ended` reflecting that. This keeps `ended` an honest "are we parked at
+  // the final frame" signal regardless of how we got there.
+  session.ended = frame >= lastFrameOf(session);
+}
+
+export async function stopPreviewSession(session: CinematicPreviewSession): Promise<void> {
+  pausePreviewSession(session);
+  session.closed = true;
+  sessions.delete(session.id);
+  await session.handle.close();
+}