@vgai/editor-sdk 0.5.35 → 0.5.37

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.35",
+  "version": "0.5.37",
   "type": "module",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.35"
+    "@vgai/sdk": "0.5.37"
   },
   "peerDependencies": {
     "@vgai/engine": "*",

package/src/contributions.ts

@@ -321,6 +321,47 @@ export interface ToolContributionSurfaces {
   readonly Object3DAuthoring: import('react').ComponentType<ToolObject3DAuthoringProps>;
 }
 
+/** One bounded visual-history sample from the live Play recording. */
+export interface ToolContributionRecordingFrame {
+  /** Monotonic within this recording, including after older frames are evicted. */
+  readonly sequence: number;
+  /** Position on the recording clock, measured from `startedAt`. */
+  readonly mediaTimeMs: number;
+  /** Wall-clock capture time, for correlating project-owned event streams. */
+  readonly capturedAt: string;
+  /** Borrowed object URL. It remains valid until this frame is evicted or Play ends. */
+  readonly src: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Stable snapshot returned by the live recording transport. */
+export interface ToolContributionRecordingSnapshot {
+  readonly startedAt: string;
+  readonly width: number;
+  readonly height: number;
+  /** Latest sampled position on the live recording clock. */
+  readonly liveEdgeMs: number;
+  readonly sampleFps: number;
+  readonly retentionMs: number;
+  readonly frames: readonly ToolContributionRecordingFrame[];
+  /** A preview failure never stops the full WebM recording. */
+  readonly previewError: string | null;
+}
+
+/**
+ * Read-only visual history for the current Play recording.
+ *
+ * `getSnapshot` is referentially stable between notifications, so it can be
+ * passed directly to React's `useSyncExternalStore`. A `null` snapshot means
+ * Play is not currently recording (for example, a human-started Play session
+ * that did not explicitly start recording).
+ */
+export interface ToolContributionRecording {
+  readonly getSnapshot: () => ToolContributionRecordingSnapshot | null;
+  readonly subscribe: (listener: () => void) => () => void;
+}
+
 /**
  * The live game a contribution is looking at, or `null` when nothing is
  * playing.
@@ -341,6 +382,8 @@ export interface ToolContributionSurfaces {
 export interface ToolContributionPlay {
   readonly game: unknown;
   readonly instanceId: string;
+  /** The editor-owned recording transport shared by every project tool. */
+  readonly recording: ToolContributionRecording;
 }
 
 export interface ToolContributionProps {