@vgai/editor-sdk 0.5.21 → 0.5.23

package/README.md

@@ -48,8 +48,7 @@ One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
   the independent `bounds` category). Shading targets the active Scene/Game
   viewport and remains render-only, session-local state.
 - Transform tools: `setTransformMode`, `setTransformSpace`, `setSnap`
-- Scene/project: `openScene`, `createProject`, `openProject`, `getProject`,
-  `listRecentProjects`
+- Project: `createProject`, `openProject`, `getProject`, `listRecentProjects`
 - State/logs: `getState`, `waitForState(predicate, timeoutMs)`,
   `getLogEntries`
 - Project tools: `listProjectTools`, `runProjectTool`

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "type": "module",
   "repository": {
     "type": "git",
@@ -19,11 +19,12 @@
     ".": "./src/index.ts",
     "./contributions": "./src/contributions.ts",
     "./document-probe": "./src/document-probe.ts",
-    "./extension": "./src/extension.ts"
+    "./extension": "./src/extension.ts",
+    "./share": "./src/share.ts"
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.21"
+    "@vgai/sdk": "0.5.23"
   },
   "peerDependencies": {
     "@vgai/engine": "*",

package/src/client.ts

@@ -21,6 +21,7 @@ import type {
   InspectedHierarchy,
   InspectedInspection,
   LabeledShotSetCapture,
+  PlayStarted,
   PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
@@ -294,11 +295,21 @@ export class EditorClient {
    *  `logs/play-*.jsonl` filename and its session-journal line. Findability
    *  only: no registry, no uniqueness, no lookup verb — grep and `ls` are the
    *  query engine. Omitted, the filename keeps its exact unnamed shape. */
-  async play(opts?: { seed?: number; name?: string | null }): Promise<void> {
-    await this.command({
+  /*  `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. */
+  async play(opts?: {
+    seed?: number;
+    name?: string | null;
+    record?: string | null;
+  }): Promise<PlayStarted> {
+    return this.command<PlayStarted>({
       type: 'play',
       ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),
       ...(opts?.name ? { name: opts.name } : {}),
+      ...(opts?.record ? { record: opts.record } : {}),
     });
   }
 
@@ -307,8 +318,10 @@ export class EditorClient {
     await this.command({ type: 'play' });
   }
 
-  async stop(): Promise<void> {
-    await this.command({ type: 'stop' });
+  /** Stops play, and finalizes this run's recording before the surface it was
+   *  photographing is torn down. The capture is absent when nothing recorded. */
+  async stop(): Promise<{ recording?: GameplayRecordingCapture }> {
+    return this.command<{ recording?: GameplayRecordingCapture }>({ type: 'stop' });
   }
 
   async pause(): Promise<void> {
@@ -806,12 +819,6 @@ export class EditorClient {
     await this.command({ type: 'set-snap', enabled });
   }
 
-  // --- Scene ---
-  //
-  // `openScene(path)` lived here, relaying `{type:'open-scene', path}`. That
-  // verb now rejects — the `.vscn.json` format it opened is deleted, and a three
-  // root is opened by activating its root.
-
   // --- Project management ---
 
   async createProject(
@@ -962,11 +969,13 @@ export class EditorClient {
       `${this.baseUrl}/__editor/console${opts?.all === true ? '?all=1' : ''}`,
       { signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS) },
     );
-    const body = await this.readJson(res, true);
+    // Status first: a 404's empty body would otherwise die inside readJson
+    // with a parse error that hides the one fact the caller classifies on
+    // (does this server SERVE the console route at all?).
     if (!res.ok) {
       throw new Error(`Failed to read unresolved console: ${res.status}`);
     }
-    return body;
+    return await this.readJson(res, true);
   }
 
   /** Acknowledge one named console condition. The response is observed and
@@ -993,6 +1002,27 @@ export class EditorClient {
    * original request. That makes a subsequent `process.exit()` safe: the
    * observer has already received every condition and occurrence count. */
   private async readJson(res: Response, consoleComplete = false): Promise<unknown> {
+    // Every one of this client's twelve routes funnels through here, so this is
+    // where "did the editor server answer?" is asked — the same question, and
+    // the same JSON-content-type rule, that
+    // `packages/editor/src/editor-server-response.ts` owns on the browser side.
+    // It is asked again rather than imported because THIS package is published
+    // and depends on neither `@vgai/engine` nor the editor bundle (see
+    // `DEFAULT_URL` above for that policy).
+    //
+    // Not theoretical here: `baseUrl` is whatever `--url`/`VGAI_EDITOR_URL`
+    // says, so the CLI is routinely pointed at a SHARE TUNNEL or a static host
+    // — both of which answer `200 text/html` for a route nothing serves, and
+    // `res.json()` then died as `Unexpected token '<'`, naming neither the URL
+    // nor the cause.
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+      throw new Error(
+        `The editor at ${this.baseUrl} answered with its page fallback ` +
+          `(${contentType || 'no content-type'}) rather than JSON, so no editor server handled ` +
+          'the request. Check that this URL is a running `vgai edit` session.',
+      );
+    }
     const body: unknown = await res.json();
     this.observe(body, { unresolvedConsoleComplete: consoleComplete });
     if (

package/src/extension.ts

@@ -14,7 +14,7 @@
  *     Types: `ToolInspectorContributionProps` and friends, same module.
  * (c) **System adapters** — runtime capabilities (networking, debug, …)
  *     registered from game code via `ctx.registerSystemAdapter?.(kind, impl)`
- *     (`SystemAdapters` in `@vgai/engine`'s `runtime/types` /
+ *     (`SystemAdapters` in `@vgai/engine`'s
  *     `adapter/system-adapter`). Deliberately NOT re-exported here: the
  *     engine already publishes that seam and every consumer of it also
  *     imports the engine — an alias would be a dead surface.

package/src/index.ts

@@ -73,6 +73,7 @@ export type {
   InspectionPresentationKind,
   InspectionSurface,
   LabeledShotSetCapture,
+  PlayStarted,
   PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
@@ -83,7 +84,9 @@ export type {
   RagdollGenerationResult,
   RecentProject,
   ShadingMode,
+  ShotSetPoseMorph,
   ShotSetPoseRotation,
+  ShotSetPoseStep,
   ShotSetShot,
   StoryCaptureOptions,
   StoryVariantCapture,
@@ -98,5 +101,6 @@ export type {
 export {
   EDITOR_VIEW_BUILT_IN_UTILITY_IDS,
   EDITOR_VIEW_TOOL_UTILITY_PREFIX,
+  EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS,
   isEditorViewUtility,
 } from './types.js';

package/src/share.ts

@@ -0,0 +1,160 @@
+/**
+ * THE share-session wire — `/__editor/share-control`'s payloads, declared once.
+ *
+ * This route has three clients living in three different compilation units:
+ * the editor SERVER that serves it (`packages/editor/server/`), the browser
+ * PANEL that polls it (`packages/editor/src/`), and the `vgai share` CLI
+ * (`packages/vgai-cli/src/`). Each of them used to declare its own copy of the
+ * payload, and the copies had already drifted — silently, in both directions,
+ * because an under-declared read of a JSON superset is a type error nowhere:
+ *
+ *   - the CLI's invitation had no `delivery`, so `vgai share` could not report
+ *     that the invitation email had FAILED to send — the one state the field
+ *     exists for;
+ *   - the CLI's audit rows typed `type` and `capability` as bare `string`,
+ *     which accepts any spelling of an event the server never emits;
+ *   - the browser panel's invitation had no `inviterAccountId`;
+ *   - the browser panel had no `audit` at all, and re-declared the tunnel
+ *     health shape inline instead of naming it.
+ *
+ * This package is the right home for all three: `@vgai/editor` and `@vgai/cli`
+ * both already depend on it, it depends on neither, and the CLI's esbuild
+ * bundle inlines it. (The CLI's standing "no editor-package dependency" rule is
+ * about `@vgai/editor` — the server+UI package whose express/vite/chokidar
+ * graph the standalone bundle must not drag in. This is a types-only module.)
+ *
+ * Two things deliberately stay OFF this wire, and stay off it structurally
+ * rather than by memory:
+ *
+ *   - the invitation TOKEN HASH, which is a local extension on the server
+ *     (`share-host.ts`'s `StoredShareInvitation extends ShareInvitationRecord`);
+ *   - a participant's ORGANIZATION list, which the gateway holds on its own
+ *     `ShareAccountProjection` to resolve team invitations. {@link ShareAccount}
+ *     is what a participant projects to, so `status()` narrows to it.
+ */
+
+/**
+ * A share role, least authority first.
+ *
+ * `maintainer` is deliberately absent: it is local-only and has no share role,
+ * which is why the editor's `CollaborationRole` is this union PLUS `maintainer`
+ * rather than the other way around.
+ */
+export type ShareRole = 'viewer' | 'commenter' | 'tester' | 'editor' | 'terminal';
+
+export type ShareTunnelProvider = 'cloudflared' | 'ngrok';
+
+export type ShareTunnelState = 'stopped' | 'starting' | 'healthy' | 'failed';
+
+export interface ShareTunnelHealth {
+  checkedAt: string;
+  latencyMs: number;
+}
+
+/**
+ * The capability vocabulary a grant is checked against.
+ *
+ * Wider than the roles on purpose: `public` and `never-share` are DECLARATIONS
+ * a route makes about itself, and `maintain` is the local-only authority no
+ * share role reaches — so this union is not derivable from {@link ShareRole}.
+ */
+export type ShareCapability =
+  | 'public'
+  | 'view'
+  | 'comment'
+  | 'test'
+  | 'edit'
+  | 'terminal'
+  | 'maintain'
+  | 'never-share';
+
+/** A verified VGAI account, as a share participant projects onto the wire. */
+export interface ShareAccount {
+  id: string;
+  email: string;
+  name?: string;
+}
+
+/**
+ * How the invitation was DELIVERED, when we delivered it.
+ *
+ * Present-and-`failed` is the state this field exists for: an invitation
+ * created whose email never left is otherwise indistinguishable, on every
+ * surface, from one that arrived.
+ */
+export interface ShareInvitationDelivery {
+  channel: 'clerk-email';
+  status: 'sent' | 'failed';
+  providerInvitationId?: string;
+  sentAt?: string;
+  problem?: string;
+}
+
+export interface ShareInvitationRecord {
+  id: string;
+  inviterAccountId: string;
+  recipientAccountId?: string;
+  recipientEmail?: string;
+  recipientOrganizationId?: string;
+  recipientOrganizationName?: string;
+  recipientOrganizationDomain?: string;
+  /** The highest role this invitation may ever be raised to. */
+  roleCeiling: ShareRole;
+  usePolicy: 'person' | 'team';
+  createdAt: string;
+  expiresAt: string;
+  revokedAt?: string;
+  delivery?: ShareInvitationDelivery;
+}
+
+export interface ShareParticipant {
+  participantId: string;
+  account: ShareAccount;
+  invitationId: string;
+  role: ShareRole;
+  roleCeiling: ShareRole;
+  credentials: number;
+  joined: boolean;
+}
+
+export type ShareAuditEventType =
+  | 'auth-failed'
+  | 'auth-started'
+  | 'invite-redeemed'
+  | 'capability-denied'
+  | 'role-changed'
+  | 'participant-kicked'
+  | 'invitation-revoked'
+  | 'terminal-invoked';
+
+export interface ShareAuditEvent {
+  at: string;
+  type: ShareAuditEventType;
+  invitationId?: string;
+  participantId?: string;
+  accountId?: string;
+  capability?: ShareCapability;
+  /** The role a `role-changed` event settled on. */
+  role?: ShareRole;
+}
+
+/** The `/__editor/share-control/status` payload. */
+export interface ShareStatus {
+  active: boolean;
+  sessionId: string;
+  projectRoot: string;
+  publicUrl?: string;
+  tunnelProvider?: ShareTunnelProvider;
+  tunnel: ShareTunnelState;
+  health?: ShareTunnelHealth;
+  invitations: readonly ShareInvitationRecord[];
+  participants: readonly ShareParticipant[];
+  audit: readonly ShareAuditEvent[];
+  problem?: string;
+}
+
+/** The `/__editor/share-control/invitations` reply. */
+export interface CreatedShareInvitation {
+  invitation: ShareInvitationRecord;
+  url: string;
+}

package/src/types.ts

@@ -1,10 +1,10 @@
 /**
  * The two viewport tabs — the editor's two MODES, named for what the user is
  * doing rather than for what happens to be mounted (ARCHITECTURE-CORE
- * §Vocabulary, decided 2026-08-02). They were `'scene' | 'game'` until WO-LR1:
- * `'scene'` outlived the `.vscn` scene format that named it (a three root is
- * TSX now, and asset/story/tool documents live on that tab too), and `'game'`
- * named the mounted artifact rather than the mode. Not to be confused with the
+ * §Vocabulary, decided 2026-08-02). Deliberately not `'scene' | 'game'`:
+ * `'scene'` names a document format (a three root is TSX, and
+ * asset/story/tool documents live on that tab too), and `'game'`
+ * names the mounted artifact rather than the mode. Not to be confused with the
  * PLAY TRANSPORT (the five stable controls) — this is which tab is showing.
  */
 export type ViewportTab = 'edit' | 'play';
@@ -104,6 +104,9 @@ 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. */
+  name?: string | null;
 }
 
 /** Facts fixed when a gameplay recording starts. */
@@ -115,15 +118,34 @@ export interface GameplayRecordingStarted {
   fps: number;
   audio: boolean;
   layers: { canvases: number; domOverlays: number };
+  /** 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. */
+  rotates: boolean;
+  /** This run's `logs/play-*.jsonl`, whose event timestamps map to clip offsets. */
+  logFile: string | null;
 }
 
 /** Final browser recording. Media chunks stream directly to the project while
  * recording, so the command result stays small even for a long playthrough. */
 export interface GameplayRecordingCapture extends GameplayRecordingStarted {
-  path: string;
   durationMs: number;
   droppedFrames: number;
   frameErrors: number;
+  /** The cadence ACHIEVED (frames over wall duration), which diverges from the
+   *  requested `fps` on a throttled hidden tab. Read this before reasoning
+   *  about a clip's timing. */
+  effectiveFps: number;
+  /** True when the tab was hidden for any part of the recording. */
+  hidden: boolean;
+}
+
+/** What `play` reports back once the run is up and recording. */
+export interface PlayStarted {
+  /** Absent only when the recorder could not start; play is up either way and
+   *  the editor console carries the reason. */
+  recording?: GameplayRecordingStarted;
 }
 
 export type AssetPreviewView = 'front' | 'right' | 'top' | 'perspective';
@@ -241,32 +263,60 @@ export interface AssetCompareCapture {
 }
 
 /**
+ * THE shot-set contract. This block is the ONE declaration of it.
+ *
  * A project-defined labeled shot set (`vgai screenshot <target> --shots <set>`).
  * The DEFINITION is project data: a registered project tool named
  * `project.<set>.previewShots` returns it (installed capabilities register
- * theirs — e.g. the humanoid capability contributes its canonical verify set),
- * and the editor's generic capture engine renders it — turntable yaw angles
- * and skeleton-anchored zoom crops, optionally under a named pose applied to
- * a disposable snapshot (see `packages/editor/src/asset-preview.ts`).
+ * theirs — the bird, humanoid and walking-castle capabilities each contribute
+ * their canonical verify set), and the editor's generic capture engine renders
+ * it — turntable yaw angles and skeleton-anchored zoom crops, optionally under
+ * a named pose applied to a disposable snapshot. Every shot is labeled so a
+ * flat directory of PNGs is self-describing without a manifest file.
+ *
+ * The contract lives HERE, in the SDK, because it crosses the editor relay:
+ * the capability tool that authors a set, the CLI that ships it across, and
+ * `packages/editor/src/asset-preview.ts`'s capture engine that renders it are
+ * three different programs. Each of those used to declare its own copy — five
+ * declarations in total — and the copies had already drifted on what a pose
+ * step's `radians` is measured FROM. Every side now type-checks against this
+ * one: the capture engine annotates its parser's return with
+ * `AssetPreviewShotSetDefinition`, and each capability tool annotates its
+ * exported set with it, so a Zod schema that stops matching this shape is a
+ * compile error rather than a runtime surprise at the relay.
  */
 export interface ShotSetPoseRotation {
   bone: string;
   axis: 'x' | 'y' | 'z';
+  /**
+   * A DELTA about the bone's own local axis, in radians, relative to the
+   * loaded GLB's baked rest pose — NOT an absolute local rotation.
+   *
+   * That is what the capture engine does with it: `bone.rotateX/Y/Z(radians)`,
+   * which composes onto the bone's existing local quaternion. The consequence
+   * to watch for is that "rest pose" means whatever the GLB baked, not
+   * identity — a rig baked mid-gait needs `pose(t) - pose(0)` here, while a
+   * rig baked at identity can pass its absolute angle unchanged. Getting that
+   * backwards silently double-applies the baked pose.
+   */
   radians: number;
 }
 
 /** The other half of a pose: a named morph target driven to an influence.
- *  A rig whose meshes carry no such morph is posed by the rotations alone —
- *  the same degrade-don't-throw rule the rotations follow for a missing
- *  joint. */
+ *  Morphs are how a rig expresses what a joint cannot — an eyelid sliding over
+ *  an eyeball, a brow band tilting — so a set that poses a FACE needs both
+ *  halves or it can only ever show the jaw. A rig whose meshes carry no such
+ *  morph is posed by the rotations alone: the same degrade-don't-throw rule
+ *  the rotations follow for a missing joint. */
 export interface ShotSetPoseMorph {
   morph: string;
   influence: number;
 }
 
-/** One step of a named pose. A pose is a flat list so a single expression
- *  (a jaw ROTATION plus a brow MORPH) is one entry in `poses`, not two
- *  parallel lists the capture engine would have to zip. */
+/** One step of a named pose. A flat union rather than two parallel lists: a
+ *  single expression is normally one rotation AND one morph (a jaw ROTATION
+ *  plus a brow MORPH), so keeping them in one ordered list means a definition
+ *  never has to zip them. */
 export type ShotSetPoseStep = ShotSetPoseRotation | ShotSetPoseMorph;
 
 export type ShotSetShot =
@@ -276,12 +326,19 @@ export type ShotSetShot =
       view: 'bone-zoom';
       bones: string[];
       spanFraction: number;
-      /** The angle the crop is taken FROM, in the same radian convention as
-       *  a turntable shot's `yaw` (0 the front camera, -PI/2 the subject's
-       *  left). Omitted means 0. The front camera is not a general answer
-       *  for a long subject: a crop anchored on the tail root of an 8 m
-       *  quadruped otherwise photographs the hind legs standing in front of
-       *  it. */
+      /**
+       * The angle the crop is taken FROM, in the same convention and units as
+       * a turntable shot's `yaw` (radians; 0 is the front camera, -PI/2 the
+       * subject's left, +PI/2 its right). Omitted means 0 — the front-camera
+       * framing every bone-zoom shot had before this field existed, so an
+       * existing shot set renders unchanged.
+       *
+       * It exists because the front camera is not a general answer for a long
+       * subject: on an 8 m quadruped a crop anchored on the tail root
+       * photographs the hind legs standing between the camera and the tail. A
+       * junction whose axis runs down the body's length is inspectable only
+       * from the side.
+       */
       yaw?: number | undefined;
       pose?: string | undefined;
     };
@@ -289,8 +346,8 @@ export type ShotSetShot =
 export interface AssetPreviewShotSetDefinition {
   /** The set's name (the CLI's `--shots <name>`), echoed in error messages. */
   name: string;
-  /** Joints that must exist on the loaded GLB's OWN skeleton (zoom anchors
-   *  plus a loud failure naming the missing joints — never a silent
+  /** Joints that must exist on the loaded GLB's OWN skeleton — zoom anchors
+   *  plus a loud failure naming the missing joints (never a silent
    *  bounding-box fallback for a set that promised skeleton anchoring). */
   requiredBones?: string[];
   /** Optional clause appended to rig-requirement errors,
@@ -447,12 +504,12 @@ export interface EditorState {
    *
    * `census` is the tab's RESOURCE PROFILE, sampled by the page every five
    * seconds and carried on the heartbeat: what a browser-level renderer death
-   * would otherwise leave unexplained. `heapUsedMB`/`heapLimitMB` are null off
-   * Chromium (`performance.memory` is non-standard); the renderer counts are
-   * absent, never zero, when no game has registered a render-debug adapter.
-   * `mountEpochs` counts the project module generations accumulated in this
-   * document; it is absent against an older server. `censusAgeMs` says how
-   * stale the profile is — a hidden tab is not sampled.
+   * would otherwise leave unexplained. It is `@vgai/sdk/tab-census`'s
+   * {@link RecordedTabCensus} — the census MINUS the `mountEpochs` guarantee,
+   * because this is a response and the server that answered it may be older
+   * than that field; every other absence (`heapUsedMB` off Chromium, renderer
+   * counts with no mounted adapter) is documented on the type itself.
+   * `censusAgeMs` says how stale the profile is — a hidden tab is not sampled.
    */
   tabs?: Array<{
     tabId8: string;
@@ -470,16 +527,7 @@ export interface EditorState {
     unresponsive: boolean;
     commandListener?: 'ready' | 'not attached' | (string & {});
     pageErrors?: string[];
-    census?: {
-      heapUsedMB: number | null;
-      heapLimitMB: number | null;
-      mountEpochs?: number;
-      canvases: number;
-      canvasMB: number;
-      textures?: number;
-      geometries?: number;
-      programs?: number;
-    } | null;
+    census?: RecordedTabCensus | null;
     censusAgeMs?: number | null;
   }>;
   /**
@@ -654,8 +702,17 @@ export type AnimationCaptureAction = 'start' | 'stop' | 'review' | 'commit' | 'd
 export type TransformMode = 'translate' | 'rotate' | 'scale';
 export type TransformSpace = 'world' | 'local';
 
-/** Stable editor-owned workspace documents that may appear in a shareable
- * view. One runtime list owns both URL parsing and the public id type. */
+/**
+ * Stable editor-owned workspace documents that may appear in a shareable
+ * view. One runtime list owns both URL parsing and the public id type.
+ *
+ * This SDK cannot import the editor — the dependency runs the other way — so
+ * nothing links this list to the documents the editor actually registers, and
+ * an id added there is silently unaddressable here (a view carrying it
+ * round-trips to nothing). The link is asserted from the side that CAN see
+ * both: `packages/editor/test/editor-view-address-space.test.ts`. Adding a
+ * document id means adding it here too.
+ */
 export const EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS = [
   'workspace:scene',
   'workspace:canvas-scene',
@@ -664,6 +721,7 @@ export const EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS = [
   'workspace:2d-components',
   'workspace:ui-components',
   'workspace:build-profiles',
+  'workspace:asset-budget',
   'account',
   'project-tools',
 ] as const;
@@ -677,13 +735,28 @@ export type EditorViewWorkspaceDocumentId = (typeof EDITOR_VIEW_WORKSPACE_DOCUME
  * reason: a separate hand-written union and parser allowlist drift silently
  * (`behavior` was in the union and missing from the allowlist, so a view
  * carrying it round-tripped to nothing).
+ *
+ * This must equal the editor's live `BUILT_IN_WORKSPACE_UTILITIES`
+ * (`packages/editor/src/workspace-core-utilities.ts`). It had drifted to five
+ * of thirteen — every id from `generations` onward was unaddressable in a
+ * shared view. As above, the SDK cannot import the editor to derive this, so
+ * `packages/editor/test/editor-view-address-space.test.ts` asserts the
+ * equality from the side that sees both.
  */
 export const EDITOR_VIEW_BUILT_IN_UTILITY_IDS = [
-  'profiler',
-  'console',
   'animation',
   'behavior',
+  'generations',
+  'console',
+  'profiler',
+  'state-watch',
   'light-explorer',
+  'network',
+  'audio',
+  'build-output',
+  'story-actions',
+  'story-interactions',
+  'story-accessibility',
 ] as const;
 
 export type EditorViewBuiltInUtilityId = (typeof EDITOR_VIEW_BUILT_IN_UTILITY_IDS)[number];
@@ -801,6 +874,7 @@ export type ProjectToolOutcome =
     };
 
 import type { GenerationJob } from '@vgai/sdk/generations';
+import type { RecordedTabCensus } from '@vgai/sdk/tab-census';
 
 export type {
   ProjectToolCatalog,