@vgai/live 0.5.13 → 0.5.15

package/src/index.ts

@@ -71,6 +71,8 @@ export type {
 export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame, type LiveGame } from './game.js';
 export * from './game-client/index.js';
+export type { GameplayRecordingResult } from './recording.js';
+export { LiveGameplayRecording } from './recording.js';
 export type {
   ProjectSessionHint,
   ResolvedSession,
@@ -82,8 +84,18 @@ export type { LazySession } from './singleton.js';
 export { createLazySession } from './singleton.js';
 export { LiveTools } from './tools.js';
 
-/** A `game.page(step)`-shaped call — see this module's doc comment for the closure-capture limitation. */
-export type PageStep = GameClient['page'];
+/**
+ * The `page` binding: a `game.page(step)`-shaped CALL (see this module's doc
+ * comment for the closure-capture limitation) that also carries the one page
+ * verb no step can express — `page.reload()`.
+ *
+ * `reload` is a property rather than a step because a step that navigates
+ * destroys the channel its own result would return on: `page(p =>
+ * p.evaluate(() => location.reload()))` was the only spelling available, and
+ * it resolves on a send while failing outright outside play mode. See
+ * `GameClient.reloadPage`.
+ */
+export type PageStep = GameClient['page'] & { reload: GameClient['reloadPage'] };
 
 export interface LiveSession extends LiveBindings {
   /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
@@ -97,7 +109,9 @@ export interface LiveBindings {
    *  several mounted instances (multiplayer authoring). A bare `game` call
    *  targets the sole instance and refuses when several are live. */
   game: LiveGame;
-  /** `GameClient.page` bound to `game` — see this module's own doc comment for the wire limitation. */
+  /** `GameClient.page` bound to `game`, plus `page.reload()` — see this
+   *  module's own doc comment for the wire limitation, and {@link PageStep}
+   *  for why reload is a property rather than a step. */
   page: PageStep;
   /** Registered project callables: enumerate, inspect, and invoke. */
   tools: LiveTools;
@@ -112,7 +126,8 @@ function bindTo(port: number, projectRoot: string): LiveBindings {
   const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
   const editor = new LiveEditor(client);
   const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'));
-  const page: PageStep = (step) => game.page(step);
+  const step: GameClient['page'] = (fn) => game.page(fn);
+  const page: PageStep = Object.assign(step, { reload: () => game.reloadPage() });
   const tools = new LiveTools(client);
   return { editor, game, page, tools };
 }

package/src/recording.ts

@@ -0,0 +1,70 @@
+/**
+ * `editor.recording` — real-time gameplay evidence through the existing live
+ * editor session. The browser owns MediaRecorder and the game pixels/audio;
+ * the project server streams the standard WebM to disk while this namespace
+ * exposes the start/stop controls and optional final copy destination.
+ *
+ * Recording deliberately is not a CLI workflow of its own. Agents start and
+ * stop it through the one general door (`vgai eval`) and use ordinary ffmpeg,
+ * ffprobe, and filesystem tools to review or trim the result.
+ */
+
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, resolve } from 'node:path';
+import type {
+  EditorClient,
+  GameplayRecordingOptions,
+  GameplayRecordingStarted,
+} from '@vgai/editor-sdk';
+
+export interface GameplayRecordingResult extends GameplayRecordingStarted {
+  /** Absolute path to the standard WebM written on stop. */
+  path: string;
+  durationMs: number;
+  droppedFrames: number;
+  frameErrors: number;
+}
+
+function recordingPath(destination: string): string {
+  if (destination.trim() === '') throw new Error('recording destination must not be empty');
+  const withExtension = extname(destination) === '' ? `${destination}.webm` : destination;
+  return isAbsolute(withExtension) ? withExtension : resolve(process.cwd(), withExtension);
+}
+
+export class LiveGameplayRecording {
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
+
+  /** Start one clean game recording. The page owns it until `stop()`, even
+   * when start and stop are issued by separate `vgai eval` processes. */
+  async start(options: GameplayRecordingOptions = {}): Promise<GameplayRecordingStarted> {
+    return this.#client.startGameplayRecording(options);
+  }
+
+  /** Finalize the active recording, write it to disk, and return honest media
+   * metadata without echoing the large base64 transport payload to stdout. */
+  async stop(destination?: string): Promise<GameplayRecordingResult> {
+    const capture = await this.#client.stopGameplayRecording();
+    const path = destination === undefined ? capture.path : recordingPath(destination);
+    if (path !== capture.path) {
+      await mkdir(dirname(path), { recursive: true });
+      await copyFile(capture.path, path);
+    }
+    return {
+      path,
+      startedAt: capture.startedAt,
+      mimeType: capture.mimeType,
+      width: capture.width,
+      height: capture.height,
+      fps: capture.fps,
+      audio: capture.audio,
+      durationMs: capture.durationMs,
+      droppedFrames: capture.droppedFrames,
+      frameErrors: capture.frameErrors,
+      layers: capture.layers,
+    };
+  }
+}