@vgai/editor-sdk 0.5.38 → 0.5.39

package/README.md

@@ -79,7 +79,7 @@ export default function MapBuilder({ tool, client, account }: ToolContributionPr
 }
 ```
 
-The package registration chooses `workspace.document`, `workspace.utility`,
+The package registration chooses `workspace.document`, `workspace.utility`, `workspace.analytics`,
 `selection.inspector`, `asset.inspector`, or `generation.result`. Selection
 Inspector contributions receive `node`/`nodeId` and export
 `match(node, adapter)`; asset Inspector contributions receive `asset` and

package/package.json

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

package/src/client.ts

@@ -297,9 +297,9 @@ export class EditorClient {
    *  query engine. Omitted, the filename keeps its exact unnamed shape. */
   /*  `opts.record` (`vgai play --record <name>`) — NAMES this run's recording
    *  file. It does not ENABLE recording: every relayed play records, with no
-   *  flag (see `editor/src/play-recording.ts`). Omitted, the clip lands in the
-   *  rotating `.vgai/recordings/play-latest.webm`; named, in
-   *  `.vgai/recordings/<name>.webm`, which nothing ever rotates. */
+   *  flag (see `editor/src/play-recording.ts`). Omitted, the clip is named for
+   *  the durable Gameplay Session; named, it becomes an explicit keepsake in
+   *  `.vgai/recordings/<name>.webm`. */
   async play(opts?: {
     seed?: number;
     name?: string | null;

package/src/contributions.ts

@@ -362,6 +362,63 @@ export interface ToolContributionRecording {
   readonly subscribe: (listener: () => void) => () => void;
 }
 
+/** One structured row from a Gameplay Session's durable JSONL record. */
+export interface ToolGameplaySessionEntry {
+  readonly t?: number;
+  readonly level?: string;
+  readonly source?: string;
+  readonly sub?: string;
+  readonly msg?: string;
+  readonly meta?: Readonly<Record<string, unknown>>;
+  readonly tick?: number;
+  readonly simT?: number;
+  readonly world?: string;
+  readonly simSpeed?: number;
+  readonly [field: string]: unknown;
+}
+
+export interface ToolGameplaySessionRecording {
+  readonly file: string;
+  readonly url: string;
+  readonly startedAt: number | null;
+  readonly finalized: boolean;
+  readonly bytes: number | null;
+}
+
+/** One Play interval, durable after Stop and editor reload. */
+export interface ToolGameplaySession {
+  readonly id: string;
+  readonly run: string | null;
+  readonly status: 'live' | 'completed';
+  readonly startedAt: number;
+  readonly endedAt: number | null;
+  /** Real elapsed wall time. Simulation time remains an entry field. */
+  readonly durationMs: number;
+  readonly logFile: string;
+  readonly entries: readonly ToolGameplaySessionEntry[];
+  readonly recording: ToolGameplaySessionRecording | null;
+}
+
+export interface ToolGameplaySessionsSnapshot {
+  readonly sessions: readonly ToolGameplaySession[];
+  readonly selectedSessionId: string | null;
+  readonly selectedSession: ToolGameplaySession | null;
+  /** Shared analytics cursor, measured in real milliseconds from Play start. */
+  readonly cursorMs: number;
+  readonly liveEdgeMs: number;
+  readonly loading: boolean;
+  readonly error: string | null;
+}
+
+/** Stable external store supplied to the built-in Analytics contribution. */
+export interface ToolGameplaySessions {
+  readonly getSnapshot: () => ToolGameplaySessionsSnapshot;
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly select: (sessionId: string) => void;
+  readonly seek: (realTimeMs: number) => void;
+  readonly refresh: () => Promise<void>;
+}
+
 /**
  * The live game a contribution is looking at, or `null` when nothing is
  * playing.
@@ -423,6 +480,21 @@ export interface ToolUtilityContributionProps extends Omit<ToolContributionProps
   readonly tool?: ProjectToolCatalogEntry;
 }
 
+/**
+ * A game's analytics body. The editor owns session selection, real-time
+ * transport, and optional video preview; this component owns only the charts
+ * and readouts that give the selected session meaning for this game.
+ *
+ * `play` is intentionally absent. Historical analysis consumes the durable
+ * Gameplay Session record, so the type itself prevents an Analytics surface
+ * from accidentally depending on a live module graph.
+ */
+export interface ToolAnalyticsContributionProps
+  extends Omit<ToolContributionProps, 'tool' | 'play'> {
+  readonly tool?: ProjectToolCatalogEntry;
+  readonly gameplaySessions: ToolGameplaySessions;
+}
+
 /**
  * A `selection.inspector`'s props. `tool` is OPTIONAL here for the same reason
  * it is on a utility: a section may present state the editor already has —

package/src/extension.ts

@@ -6,7 +6,7 @@
  *
  * (a) **Editor panels** — registered into the Dockview workspace as documents
  *     or utilities via a tool contribution (`package.json#vgai.tools` →
- *     `contributes: [{ point: 'workspace.document' | 'workspace.utility' }]`).
+ *     `contributes: [{ point: 'workspace.document' | 'workspace.utility' | 'workspace.analytics' }]`).
  *     Types: `ToolContributionProps` in `@vgai/editor-sdk/contributions`.
  *     Panels are never a parallel rail — Dockview owns all layout.
  * (b) **Inspector sections** — `point: 'selection.inspector'` /

package/src/types.ts

@@ -104,8 +104,8 @@ export interface GameCapture {
 export interface GameplayRecordingOptions {
   /** Requested real-time capture cadence. Defaults to 30; range 1–60. */
   fps?: number;
-  /** Names the file under `.vgai/recordings/`. Absent takes the rotating
-   *  `play-latest.webm`, which the next play overwrites. */
+  /** Names the file under `.vgai/recordings/`. During Play, absence names the
+   *  clip after its durable Gameplay Session. */
   name?: string | null;
 }
 
@@ -121,7 +121,7 @@ export interface GameplayRecordingStarted {
   /** Where the bytes are landing — known at START, so a caller can say where
    *  the evidence for a run still in progress will be. */
   path: string;
-  /** True for the rotating unnamed clip; false for a `--record <name>` keepsake. */
+  /** True only for the out-of-session rotating fallback. */
   rotates: boolean;
   /** This run's `logs/play-*.jsonl`, whose event timestamps map to clip offsets. */
   logFile: string | null;