@vgai/sdk 0.4.0-canary.20260715.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@vgai/sdk",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.4.0-canary.20260715.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/vgai-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./registry": "./src/registry.ts"
+  },
+  "dependencies": {
+    "@vgai/engine": "0.4.0-canary.20260715.0",
+    "playwright": "^1.58.2",
+    "zod": "^4.3.6"
+  }
+}

package/src/cinematic/capabilities-operations.ts

@@ -0,0 +1,128 @@
+/**
+ * `cinematic.capabilities` (B5, §8 B5 "report capture/codec capabilities").
+ *
+ * Wraps `checkFfmpegCapability` (`packages/vgai-sdk/src/render/capabilities/ffmpeg.ts`, A1) for
+ * the ffmpeg/ffprobe BINARY presence/version half, and adds the DECLARED
+ * format/codec support `packages/vgai-sdk/src/render/render-cinematic.ts` itself
+ * hard-codes (`buildEncodeArgs`/`requireValidBackgroundFormat`) — mp4/h264,
+ * webm/vp9(+alpha), and png (no video codec, no container). This is a
+ * DECLARATION of what the render pipeline is WRITTEN to attempt, not an
+ * independent `ffmpeg -codecs`/`-encoders` probe: `checkFfmpegCapability`
+ * itself only runs `<bin> -version` (binary presence), never inspects which
+ * codecs a given ffmpeg build was compiled with — so an ffmpeg binary that
+ * IS present but lacks `libx264`/`libvpx-vp9` still reports success here,
+ * and would only fail later, at actual encode time, with ffmpeg's own raw
+ * stderr (surfaced by `cinematic.render.status`'s error field). This mirrors
+ * `checkFfmpegCapability`'s own scope honestly rather than fabricating a
+ * codec-level guarantee it was never designed to make.
+ *
+ * `FfmpegCapabilityResult`'s failure shape
+ * (`{ ok: false, errors: FfmpegCapabilityError[] }`) does NOT retain
+ * command/version for whichever of ffmpeg/ffprobe DID succeed when the
+ * other is missing (`checkFfmpegCapability`'s own success values are
+ * discarded once any error exists — see its source) — so in that mixed
+ * case this op honestly reports the present-but-unprobed-for-version binary
+ * as `{ ok: true }` with no `command`/`version`, rather than fabricating
+ * either.
+ */
+
+import { z } from 'zod';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import { checkFfmpegCapability } from '../render/capabilities/ffmpeg.js';
+
+const BinaryCapability = z.discriminatedUnion('ok', [
+  z.object({
+    ok: z.literal(true),
+    command: z
+      .string()
+      .optional()
+      .describe('Absent when the sibling binary was missing (see module jsdoc).'),
+    version: z
+      .string()
+      .optional()
+      .describe('Absent when the sibling binary was missing (see module jsdoc).'),
+  }),
+  z.object({ ok: z.literal(false), installGuidance: z.string() }),
+]);
+
+const CinematicCapabilitiesInput = z.object({
+  ffmpegBin: z.string().optional().describe('Override the ffmpeg binary name/path to probe.'),
+  ffprobeBin: z.string().optional().describe('Override the ffprobe binary name/path to probe.'),
+});
+
+const CinematicCapabilitiesResult = z.object({
+  ffmpeg: BinaryCapability,
+  ffprobe: BinaryCapability,
+  supportedFormats: z
+    .array(
+      z.object({
+        format: z.enum(['mp4', 'webm', 'png']),
+        videoCodec: z.string().optional().describe('Absent for png (no video encode step at all).'),
+        alpha: z
+          .boolean()
+          .describe('Whether this format/codec combination can carry an alpha channel.'),
+      }),
+    )
+    .describe(
+      'Formats packages/vgai-sdk/src/render/render-cinematic.ts is WRITTEN to attempt — a declared ' +
+        'capability list, not an independent ffmpeg -codecs probe (see module jsdoc).',
+    ),
+  warnings: z.array(z.string()),
+});
+
+const DECLARED_FORMATS = [
+  { format: 'mp4' as const, videoCodec: 'libx264', alpha: false },
+  { format: 'webm' as const, videoCodec: 'libvpx-vp9', alpha: true },
+  { format: 'png' as const, alpha: true },
+];
+
+export const cinematicCapabilities = defineOperation({
+  name: 'cinematic.capabilities',
+  summary:
+    'Report ffmpeg/ffprobe capture capability and the render pipeline’s declared codec/format support.',
+  description:
+    'Wraps checkFfmpegCapability (A1) for binary presence/version, plus a DECLARED (not probed) ' +
+    'format/codec list matching render-cinematic.ts’s own hard-coded encode args (see module jsdoc ' +
+    'for the honest scope limit).',
+  input: CinematicCapabilitiesInput,
+  result: CinematicCapabilitiesResult,
+  errors: [],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Runs `ffmpeg -version`/`ffprobe -version`; no writes.' },
+  async impl(input) {
+    const check = checkFfmpegCapability({
+      ...(input.ffmpegBin !== undefined ? { ffmpegBin: input.ffmpegBin } : {}),
+      ...(input.ffprobeBin !== undefined ? { ffprobeBin: input.ffprobeBin } : {}),
+    });
+
+    if (check.ok) {
+      return {
+        ffmpeg: { ok: true as const, ...check.ffmpeg },
+        ffprobe: { ok: true as const, ...check.ffprobe },
+        supportedFormats: DECLARED_FORMATS,
+        warnings: [],
+      };
+    }
+
+    const ffmpegErr = check.errors.find((e) => e.binary === 'ffmpeg');
+    const ffprobeErr = check.errors.find((e) => e.binary === 'ffprobe');
+    return {
+      ffmpeg: ffmpegErr
+        ? { ok: false as const, installGuidance: ffmpegErr.installGuidance }
+        : { ok: true as const },
+      ffprobe: ffprobeErr
+        ? { ok: false as const, installGuidance: ffprobeErr.installGuidance }
+        : { ok: true as const },
+      supportedFormats: DECLARED_FORMATS,
+      warnings: check.errors.map((e) => e.message),
+    };
+  },
+});
+
+/** Register cinematic.capabilities onto `registry`. */
+export function registerCapabilitiesOperations(registry: OperationRegistry): void {
+  registry.register(cinematicCapabilities);
+}

package/src/cinematic/cue-operations.ts

@@ -0,0 +1,198 @@
+/**
+ * `cinematic.cue.list` / `cinematic.cue.validate`
+ * (B5, §8 B5 "list cues and validate cue ordering/IDs").
+ *
+ * `CinematicCue` (`packages/engine/src/animation/cinematic-cues.ts`) is
+ * ordinary TypeScript — a plain array literal with a `run`/`reverse`
+ * function per entry (§3.2/§5.4: "Cues must not contain an alternate
+ * property-animation model" — deliberately NOT a VGAI-owned serialized
+ * format). There is therefore no JSON/manifest this op can parse
+ * authoritatively; like B2's `project.xstate.discover`/`.validate`
+ * (`../project/discovery-operations.ts`), this is a STATIC HEURISTIC over
+ * source text, not a parse/execute — it can both miss cues (defined via
+ * spread, computed properties, or indirection) and never proves `run`/
+ * `reverse` themselves are correct. Named as a limit, not silently passed
+ * off as full validation, exactly like that module's own documented limit.
+ *
+ * The heuristic looks for the literal shape every committed cue array in
+ * this repo actually uses (`packages/engine/e2e/reference-cinematic/main.ts`):
+ * `{ id: '...', time: <number>, ... }` — `id` immediately followed by
+ * `time` (whitespace/newlines between fields, comma-separated, matching
+ * `CinematicCue`'s own field order convention).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import type { OperationContext } from '../types.js';
+import { NO_ROOT_ERROR } from './theatre-operations.js';
+
+export const CUE_FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'FILE_NOT_FOUND',
+  summary: 'The referenced cue module file does not exist on disk.',
+  data: z.object({ path: z.string() }),
+};
+
+const CUE_LITERAL_PATTERN =
+  /\{\s*id:\s*['"]([^'"]+)['"]\s*,\s*time:\s*(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g;
+
+export interface HeuristicCue {
+  readonly id: string;
+  readonly time: number;
+}
+
+/**
+ * Extract `{ id: '...', time: <n> }`-shaped object literals from `source`,
+ * in the order they appear in the text (== the array's declaration/
+ * registration order, per `createCueRunner`'s equal-timestamp tiebreak
+ * convention). Best-effort text heuristic — see module jsdoc.
+ */
+export function extractHeuristicCues(source: string): HeuristicCue[] {
+  const cues: HeuristicCue[] = [];
+  for (const match of source.matchAll(CUE_LITERAL_PATTERN)) {
+    const id = match[1];
+    const time = Number(match[2]);
+    if (id !== undefined && Number.isFinite(time)) cues.push({ id, time });
+  }
+  return cues;
+}
+
+const CueSourceInput = z.object({
+  source: z.string().optional().describe('Raw TypeScript source to scan directly.'),
+  path: z
+    .string()
+    .optional()
+    .describe('Path to a TypeScript module to read and scan (absolute, or root-relative).'),
+  root: z
+    .string()
+    .optional()
+    .describe('Base directory for a relative `path`. Defaults to ctx.projectRoot.'),
+});
+
+function resolveSource(input: z.infer<typeof CueSourceInput>, ctx: OperationContext): string {
+  if (input.source !== undefined) return input.source;
+  if (input.path === undefined) {
+    throw new OperationError('BAD_INPUT', 'One of `source` or `path` must be given.', {});
+  }
+  const root = input.root ?? ctx.projectRoot;
+  const absPath = isAbsolute(input.path) ? input.path : root ? join(root, input.path) : undefined;
+  if (!absPath) {
+    throw new OperationError(
+      'NO_ROOT',
+      'A relative `path` was given but neither `root` nor ctx.projectRoot is available.',
+      {},
+    );
+  }
+  if (!existsSync(absPath)) {
+    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+  }
+  return readFileSync(absPath, 'utf-8');
+}
+
+const HeuristicCueSchema = z.object({ id: z.string(), time: z.number() });
+
+// ---------------------------------------------------------------------------
+// cinematic.cue.list
+// ---------------------------------------------------------------------------
+
+const CinematicCueListResult = z.object({
+  cues: z
+    .array(HeuristicCueSchema)
+    .describe('Every {id, time} pair found, in source declaration order.'),
+});
+
+export const cinematicCueList = defineOperation({
+  name: 'cinematic.cue.list',
+  summary: 'Best-effort static list of {id, time} cue entries in a TypeScript cue module.',
+  description:
+    'STATIC HEURISTIC over source text, not a parse/execute (see module jsdoc) — CinematicCue is ' +
+    'ordinary TypeScript (§3.2/§5.4), not a VGAI-owned serialized format.',
+  input: CueSourceInput,
+  result: CinematicCueListResult,
+  errors: [
+    NO_ROOT_ERROR,
+    CUE_FILE_NOT_FOUND_ERROR,
+    { code: 'BAD_INPUT', summary: 'Neither `source` nor `path` was given.', data: z.object({}) },
+  ],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one file’s text (or a given string); no writes.' },
+  async impl(input, ctx) {
+    const source = resolveSource(input, ctx);
+    return { cues: extractHeuristicCues(source) };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.cue.validate
+// ---------------------------------------------------------------------------
+
+const CinematicCueValidateResult = z.object({
+  valid: z.boolean(),
+  issues: z.array(z.string()),
+  cues: z.array(HeuristicCueSchema),
+});
+
+export const cinematicCueValidate = defineOperation({
+  name: 'cinematic.cue.validate',
+  summary:
+    'Validate unique cue IDs and ascending time ordering for the cues found by cinematic.cue.list’s ' +
+    'same heuristic.',
+  description:
+    'STATIC HEURISTIC (see cinematic.cue.list / module jsdoc for the same limit). Two checks, ' +
+    'mirroring createCueRunner’s own runtime contract (packages/engine/src/animation/cinematic-cues.ts): ' +
+    '(1) no duplicate `id` (the runtime throws on this); (2) declaration order is already non-decreasing ' +
+    'by `time` (createCueRunner re-sorts regardless, but declaration order drifting from evaluation order ' +
+    'is a readability/authoring smell worth flagging, not a hard runtime requirement).',
+  input: CueSourceInput,
+  result: CinematicCueValidateResult,
+  errors: [
+    NO_ROOT_ERROR,
+    CUE_FILE_NOT_FOUND_ERROR,
+    { code: 'BAD_INPUT', summary: 'Neither `source` nor `path` was given.', data: z.object({}) },
+  ],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one file’s text (or a given string); no writes.' },
+  async impl(input, ctx) {
+    const source = resolveSource(input, ctx);
+    const cues = extractHeuristicCues(source);
+    const issues: string[] = [];
+
+    const seen = new Map<string, number>();
+    cues.forEach((cue, i) => {
+      if (seen.has(cue.id)) {
+        issues.push(
+          `Duplicate cue id "${cue.id}" at positions ${seen.get(cue.id)} and ${i} — ids must be unique.`,
+        );
+      } else {
+        seen.set(cue.id, i);
+      }
+    });
+
+    for (let i = 1; i < cues.length; i++) {
+      const prev = cues[i - 1]!;
+      const cur = cues[i]!;
+      if (cur.time < prev.time) {
+        issues.push(
+          `Cue "${cur.id}" (time ${cur.time}) is declared after "${prev.id}" (time ${prev.time}) but ` +
+            'has an earlier time — declaration order drifts from evaluation order.',
+        );
+      }
+    }
+
+    return { valid: issues.length === 0, issues, cues };
+  },
+});
+
+/** Register cinematic.cue.list / cinematic.cue.validate onto `registry`. */
+export function registerCueOperations(registry: OperationRegistry): void {
+  registry.register(cinematicCueList);
+  registry.register(cinematicCueValidate);
+}

package/src/cinematic/gsap-operations.ts

@@ -0,0 +1,126 @@
+/**
+ * `cinematic.gsap.inspect` (B5, §8 B5 "inspect registered deterministic GSAP
+ * timelines").
+ *
+ * DECISION (per this unit's brief — "static/metadata where possible; named
+ * error if runtime-only"): this is STATIC-ONLY, by design, not a wiring gap.
+ * `registerGsap` (`packages/engine/src/animation/gsap-registration.ts`)
+ * stores its bookkeeping in a module-private
+ * `WeakMap<AnimationClock, WeakSet<gsap.core.Timeline>>` — deliberately
+ * un-enumerable (no `.list()`/registry object is exported at all, so that
+ * neither a disposed clock nor a disposed timeline is kept reachable/leaked
+ * just so something else could list it later). There is consequently no
+ * live surface — local or over any wire protocol — that could ever answer
+ * "what GSAP timelines are registered on this running clock right now",
+ * independent of this unit's file-ownership boundary (that WeakMap is
+ * `packages/engine/src/animation/gsap-registration.ts`, not
+ * `vgai-sdk`, and adding an enumeration API to it is out of this unit's
+ * scope regardless). So the honest, useful thing this op CAN do is exactly
+ * what B2's `project.xstate.discover` does for XState machines
+ * (`../project/discovery-operations.ts`) — best-effort STATIC discovery of
+ * source files that call `registerGsap(...)`, clearly reported as
+ * static-only, never a live registration count.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { listProjectFiles } from '../project/shared.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import { NO_ROOT_ERROR } from './theatre-operations.js';
+
+/** True when the file text looks like it registers a GSAP timeline for deterministic scrub/export. */
+function findGsapRegistrations(text: string): {
+  importsGsapRegistration: boolean;
+  callCount: number;
+} {
+  const importsGsapRegistration = /from\s+['"][^'"]*gsap-registration(?:\.js)?['"]/.test(text);
+  const callMatches = text.match(/\bregisterGsap\s*\(/g);
+  return { importsGsapRegistration, callCount: callMatches?.length ?? 0 };
+}
+
+const CinematicGsapInspectInput = z.object({
+  root: z
+    .string()
+    .optional()
+    .describe('Directory to scan for GSAP registration call sites. Defaults to ctx.projectRoot.'),
+});
+
+const CinematicGsapInspectResult = z.object({
+  root: z.string(),
+  staticInspectionOnly: z
+    .literal(true)
+    .describe(
+      'Always true — see module jsdoc: registerGsap stores registrations in an un-enumerable ' +
+        'WeakMap/WeakSet by design, so there is no live surface this (or any) op could poll instead.',
+    ),
+  registrations: z
+    .array(
+      z.object({
+        path: z.string(),
+        importsGsapRegistration: z.boolean(),
+        callCount: z
+          .number()
+          .describe(
+            'Number of `registerGsap(` call-site TEXT matches in this file (a heuristic count, not a proof of how many timelines end up registered at runtime).',
+          ),
+      }),
+    )
+    .describe('Every *.ts/*.tsx file whose text imports gsap-registration, sorted by path.'),
+});
+
+export const cinematicGsapInspect = defineOperation({
+  name: 'cinematic.gsap.inspect',
+  summary:
+    'Best-effort static discovery of source files that call registerGsap(...) to register a ' +
+    'deterministic GSAP timeline.',
+  description:
+    'STATIC-ONLY BY DESIGN, not a wiring gap — see module jsdoc. registerGsap’s bookkeeping is an ' +
+    'un-enumerable WeakMap/WeakSet (packages/engine/src/animation/gsap-registration.ts), so no ' +
+    'live "what is registered right now" surface exists anywhere to poll instead.',
+  input: CinematicGsapInspectInput,
+  result: CinematicGsapInspectResult,
+  errors: [NO_ROOT_ERROR],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads *.ts/*.tsx file contents under root; no writes.' },
+  async impl(input, ctx) {
+    const root = input.root ?? ctx.projectRoot;
+    if (!root) {
+      throw new OperationError(
+        'NO_ROOT',
+        'Neither an explicit `root` input nor ctx.projectRoot was given.',
+        {},
+      );
+    }
+    const candidates = listProjectFiles(
+      root,
+      (p) => (p.endsWith('.ts') || p.endsWith('.tsx')) && !p.endsWith('.d.ts'),
+    );
+    const registrations: { path: string; importsGsapRegistration: boolean; callCount: number }[] =
+      [];
+    for (const rel of candidates) {
+      const abs = join(root, rel);
+      let text: string;
+      try {
+        if (!statSync(abs).isFile()) continue;
+        text = readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      const found = findGsapRegistrations(text);
+      if (found.importsGsapRegistration || found.callCount > 0) {
+        registrations.push({ path: rel, ...found });
+      }
+    }
+    return { root, staticInspectionOnly: true as const, registrations };
+  },
+});
+
+/** Register cinematic.gsap.inspect onto `registry`. */
+export function registerGsapOperations(registry: OperationRegistry): void {
+  registry.register(cinematicGsapInspect);
+}

package/src/cinematic/index.ts

@@ -0,0 +1,59 @@
+/**
+ * B5 — `cinematic.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B5). Registered
+ * separately from B1's `registerBuiltinOperations` (`../operations.ts`),
+ * B2's `registerProjectOperations` (`../project/index.ts`), B3's
+ * `registerEditorOperations` (`../editor/index.ts`), and B4's
+ * `registerPlayOperations` (`../play/index.ts`) — the default `operations`
+ * singleton (`../index.ts`) calls all five.
+ *
+ * Removes B1's `cinematic.render` stand-in (`operations.ts`, which always
+ * threw `NOT_IMPLEMENTED`) now that this module registers the REAL
+ * implementation under the same name — same precedent B3 set for
+ * `editor.selection.get` (see `operations.ts`'s updated module jsdoc).
+ */
+
+export * from './capabilities-operations.js';
+export * from './cue-operations.js';
+export * from './gsap-operations.js';
+export * from './preview-operations.js';
+export type {
+  CinematicOpenPreviewFn,
+  CinematicPreviewHandle,
+  CinematicPreviewSession,
+} from './preview-transport.js';
+export {
+  _clearPreviewSessionsForTests,
+  getCinematicOpenPreviewFn,
+  getPreviewSession,
+} from './preview-transport.js';
+export * from './render-operations.js';
+export type {
+  CinematicRenderFn,
+  CinematicRenderJob,
+  CinematicRenderJobError,
+} from './render-transport.js';
+export {
+  _clearRenderJobsForTests,
+  getCinematicRenderFn,
+  getRenderJob,
+} from './render-transport.js';
+export * from './theatre-operations.js';
+
+import type { OperationRegistry } from '../registry.js';
+import { registerCapabilitiesOperations } from './capabilities-operations.js';
+import { registerCueOperations } from './cue-operations.js';
+import { registerGsapOperations } from './gsap-operations.js';
+import { registerPreviewOperations } from './preview-operations.js';
+import { registerRenderOperations } from './render-operations.js';
+import { registerTheatreOperations } from './theatre-operations.js';
+
+/** Register every B5 `cinematic.*` operation onto `registry`. */
+export function registerCinematicOperations(registry: OperationRegistry): void {
+  registerTheatreOperations(registry);
+  registerCueOperations(registry);
+  registerGsapOperations(registry);
+  registerCapabilitiesOperations(registry);
+  registerRenderOperations(registry);
+  registerPreviewOperations(registry);
+}