@vgai/editor-sdk 0.5.13 → 0.5.15

package/package.json

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

package/src/client.ts

@@ -2,6 +2,7 @@ import type { GenerationJobsDocument } from '@vgai/sdk/generations';
 import type { DocumentProbeResult, DocumentProbeStep } from './document-probe.js';
 import type {
   ActiveDocumentCapture,
+  AnimationCaptureAction,
   AssetCompareCapture,
   AssetCompareOptions,
   AssetKind,
@@ -12,7 +13,11 @@ import type {
   EditorState,
   EditorView,
   GameCapture,
+  GameplayRecordingCapture,
+  GameplayRecordingOptions,
+  GameplayRecordingStarted,
   HelperVisibility,
+  InspectedFieldWrite,
   InspectedHierarchy,
   InspectedInspection,
   LabeledShotSetCapture,
@@ -46,7 +51,7 @@ const DEFAULT_URL = 'http://127.0.0.1:20173';
  * `/__editor/command` has always answered `{ ok: false, error, code }` and
  * this client has always dropped the `code` on the floor, so every caller that
  * wanted to react to a specific refusal had to substring-match an English
- * sentence. `vgai screenshot`'s hidden-tab fallback is the first caller that
+ * sentence. `vgai screenshot`'s loop-recovery fallback is the first caller that
  * genuinely must branch (`BRIDGE_SCREENSHOT_STALE` has a working recovery;
  * "not in play mode" does not), and a fallback keyed on prose would fire on
  * the wrong failure the first time someone rewords the message.
@@ -148,19 +153,36 @@ export class EditorClient {
    */
   readonly game: GameDebugDoor;
 
-  constructor(opts?: { url?: string }) {
+  /**
+   * Called with the raw body of EVERY response this client receives — command
+   * envelopes and `/__editor/state` alike, on success AND on refusal.
+   *
+   * It exists for exactly one contract: the server stamps `unresolvedConsole`
+   * onto every envelope (`server-utils.ts`'s `commandResponseFor`), and the CLI
+   * has to see those counts to be loud about them. Routing that through a
+   * single observer here — rather than teaching each of the CLI's output sites
+   * to unpack a response — is what keeps the loudness contract ONE mechanism.
+   * The observer must not throw; anything it raises is swallowed, because a
+   * reporting hook may never break the command it is reporting on.
+   */
+  private readonly onEnvelope: ((body: unknown) => void) | null;
+
+  constructor(opts?: { url?: string; onEnvelope?: (body: unknown) => void }) {
     if (opts !== undefined && (typeof opts !== 'object' || opts === null || Array.isArray(opts))) {
       throw new TypeError(
         'EditorClient options must be an object. Use new EditorClient({ url: "http://127.0.0.1:20173" }), not new EditorClient("...").',
       );
     }
-    const unknownOptions = Object.keys(opts ?? {}).filter((key) => key !== 'url');
+    const unknownOptions = Object.keys(opts ?? {}).filter(
+      (key) => key !== 'url' && key !== 'onEnvelope',
+    );
     if (unknownOptions.length > 0) {
       throw new Error(
         `EditorClient: unknown option${unknownOptions.length === 1 ? '' : 's'} ${unknownOptions.map((key) => `"${key}"`).join(', ')}. Use { url: "http://127.0.0.1:<port>" } to target an editor.`,
       );
     }
     this.baseUrl = (opts?.url ?? DEFAULT_URL).replace(/\/$/, '');
+    this.onEnvelope = opts?.onEnvelope ?? null;
     this.game = {
       state: async (name: string): Promise<unknown> => {
         // `keys` narrows the relay to the one provider asked for, so a panel
@@ -202,6 +224,7 @@ export class EditorClient {
       );
     }
     const data = (await res.json()) as { ok: boolean; error?: string; code?: string } & T;
+    this.observe(data);
     if (!data.ok) {
       throw new EditorCommandError(
         data.error ?? `Editor command failed: ${res.status}`,
@@ -329,13 +352,13 @@ export class EditorClient {
    * debug seam") or no game canvas is mounted yet. Never returns a blank or
    * editor-only frame as a stand-in.
    *
-   * `opts.refreshHiddenFrame` is the hidden-tab leg: a backgrounded tab
-   * pauses the loop, so the canvas holds a provably stale frame and the relay
+   * `opts.refreshStarvedFrame` is the loop-starvation leg: without recent rAF
+   * progress the canvas holds a provably stale frame and the relay
    * refuses it with `BRIDGE_SCREENSHOT_STALE` rather than pass it off as
    * current. Setting this asks the relay to render exactly ONE deterministic
    * tick (`runTicks(1, {render:'last'})`) first — the same escape
    * `@vgai/live`'s `RelayTransport.screenshot` has always used, which is why
-   * `vgai eval` could capture hidden frames while `vgai screenshot` could not.
+   * `vgai eval` could recover these frames while `vgai screenshot` could not.
    * Off by default: a caller who does not ask must never be handed a frame
    * that only exists because the capture drove the game.
    *
@@ -346,12 +369,12 @@ export class EditorClient {
    * worthless — so the contamination only happens when someone asks for it.
    */
   async captureGame(opts?: {
-    refreshHiddenFrame?: boolean;
+    refreshStarvedFrame?: boolean;
     devLayers?: boolean;
   }): Promise<GameCapture> {
     const data = await this.command<GameCapture>({
       type: 'bridge-screenshot',
-      ...(opts?.refreshHiddenFrame === true ? { refreshHiddenFrame: true } : {}),
+      ...(opts?.refreshStarvedFrame === true ? { refreshStarvedFrame: true } : {}),
       ...(opts?.devLayers === true ? { devLayers: true } : {}),
     });
     const layers = data.layers;
@@ -367,10 +390,28 @@ export class EditorClient {
       // warning sentence is written where the pixels are, so nothing here
       // re-derives (or softens) it.
       ...(flatness && typeof flatness.dominantFraction === 'number' ? { flatness } : {}),
-      ...(data.hiddenFrame === true ? { hiddenFrame: true } : {}),
+      ...(data.loopRecoveryFrame === true ? { loopRecoveryFrame: true } : {}),
     };
   }
 
+  /** Start recording the same clean running-game composite `captureGame`
+   * photographs. Recording state lives in the editor page, so another process
+   * may stop it later through the same project session. */
+  async startGameplayRecording(
+    options: GameplayRecordingOptions = {},
+  ): Promise<GameplayRecordingStarted> {
+    return this.command<GameplayRecordingStarted>({
+      type: 'bridge-recording-start',
+      ...(options.fps !== undefined ? { fps: options.fps } : {}),
+      ...(options.devLayers === true ? { devLayers: true } : {}),
+    });
+  }
+
+  /** Stop the page-owned recorder and return its WebM path and metadata. */
+  async stopGameplayRecording(): Promise<GameplayRecordingCapture> {
+    return this.command<GameplayRecordingCapture>({ type: 'bridge-recording-stop' });
+  }
+
   /**
    * Capture an isolated, deterministic four-view preview through the editor's
    * native Asset Lab. The SDK delegates rendering to the editor; it never
@@ -572,14 +613,21 @@ export class EditorClient {
     return data.hierarchy;
   }
 
-  /** Write one editable path through the active Inspector's own IO. */
-  async setInspectionField(path: string, value: unknown): Promise<InspectedInspection> {
-    const data = await this.command<{ subject: InspectedInspection }>({
+  /**
+   * Write one editable path through the active Inspector's own IO.
+   *
+   * The answer carries `write` as well as the subject, because an ack alone
+   * cannot be believed: a write with no persistence route open succeeds and
+   * changes no byte, and `write.persisted` is how the caller tells the two
+   * apart without diffing the tree (`InspectedWriteDestination` in `types.ts`).
+   */
+  async setInspectionField(path: string, value: unknown): Promise<InspectedFieldWrite> {
+    const data = await this.command<InspectedFieldWrite>({
       type: 'set-inspection-field',
       path,
       value,
     });
-    return data.subject;
+    return { subject: data.subject, write: data.write };
   }
 
   /**
@@ -622,21 +670,6 @@ export class EditorClient {
 
   // --- Display (set semantics) ---
 
-  /**
-   * The Game document's "Persist to game source" consent, over the relay —
-   * the same session-scoped switch the checkbox flips, refused for the same
-   * reasons (it answers with the server's own words when the base cannot be
-   * written). `recorder` names who accounts for the diff a write produces.
-   */
-  async setSourcePersistConsent(
-    enabled: boolean,
-  ): Promise<{ enabled: boolean; recorder: string | null }> {
-    return this.command<{ enabled: boolean; recorder: string | null }>({
-      type: 'set-source-persist-consent',
-      enabled,
-    });
-  }
-
   async setGrid(enabled: boolean): Promise<void> {
     await this.command({ type: 'set-grid', enabled });
   }
@@ -653,6 +686,11 @@ export class EditorClient {
     await this.command({ type: 'set-shading-mode', mode });
   }
 
+  /** Drive the recorder owned by the active native animation document. */
+  async recordAnimation(action: AnimationCaptureAction): Promise<void> {
+    await this.command({ type: 'animation-capture', action });
+  }
+
   async setHelperType(helperType: keyof HelperVisibility, enabled: boolean): Promise<void> {
     await this.command({ type: 'set-helper-type', helperType, enabled });
   }
@@ -800,7 +838,19 @@ export class EditorClient {
   async getState(): Promise<EditorState> {
     const res = await fetch(`${this.baseUrl}/__editor/state`);
     if (!res.ok) throw new Error(`Failed to get editor state: ${res.status} ${res.statusText}`);
-    return (await res.json()) as EditorState;
+    const state = (await res.json()) as EditorState;
+    this.observe(state);
+    return state;
+  }
+
+  /** Hand one response body to {@link onEnvelope}, never letting it throw. */
+  private observe(body: unknown): void {
+    if (this.onEnvelope === null) return;
+    try {
+      this.onEnvelope(body);
+    } catch {
+      // A reporting hook may never break the command it is reporting on.
+    }
   }
 
   /**

package/src/contributions.ts

@@ -41,6 +41,15 @@ export interface ToolContributionNode {
 export interface ToolObject3DPreviewSource {
   readonly root: Object3D;
   readonly animations?: readonly AnimationClip[];
+  /**
+   * The source's OWN tick, and the host drives it EXACTLY ONCE per mount — for
+   * the bounded design-time settle that gives a physics-owned body the pose it
+   * actually rests in (`authoring/design-time-settle.ts`). It is never a frame
+   * loop: content time does not advance on a design-time surface, so a source
+   * that animates from here shows its settled pose and then holds it. Play is
+   * where a world runs.
+   */
+  update?(deltaSeconds: number): void;
   dispose(): void;
 }
 
@@ -73,7 +82,6 @@ export interface ToolObject3DPreviewProps {
   readonly height?: number | string;
   readonly background?: ColorRepresentation;
   readonly showSkeleton?: boolean;
-  readonly autoplay?: boolean;
   readonly cameraDirection?: readonly [number, number, number];
   /** Host diagnostic grid. Defaults off with setupPreview, on otherwise. */
   readonly showGrid?: boolean;
@@ -124,7 +132,6 @@ export interface ToolObject3DAuthoringProps {
    *  viewport dressing (environment, gradient backdrop, key light). */
   readonly background?: ColorRepresentation;
   readonly cameraDirection?: readonly [number, number, number];
-  readonly autoplay?: boolean;
   /**
    * Optional binding from live native clips back to ordinary project source.
    * Project code only serializes its own TypeScript shape; the editor owns the
@@ -280,8 +287,29 @@ export interface ToolAnimationSourceBinding {
   readonly serialize: (animations: readonly AnimationClip[]) => string;
 }
 
+/** Format-neutral identity for a project-owned Asset Lab document.
+ *
+ * This surface deliberately accepts no React children. Project tools may run
+ * a different React major than the editor, so their native UI stays in their
+ * own runtime while this editor-owned subject publishes the standard Asset
+ * Lab context, selection floor, and Inspector identity row beside it.
+ */
+export interface ToolAssetDocumentProps {
+  /** Stable id of the open workspace document. */
+  readonly documentId: string;
+  /** Subject name shown by the Inspector. */
+  readonly title: string;
+  /** Ecosystem-neutral asset kind shown by the Inspector. */
+  readonly type: string;
+  /** Optional provenance or concise state shown with the identity row. */
+  readonly status?: string;
+  /** Whether this is the active center document. */
+  readonly active?: boolean;
+}
+
 /** Editor-owned native surfaces available to ordinary project React tools. */
 export interface ToolContributionSurfaces {
+  readonly AssetDocument: import('react').ComponentType<ToolAssetDocumentProps>;
   readonly Object3DPreview: import('react').ComponentType<ToolObject3DPreviewProps>;
   readonly Object3DAuthoring: import('react').ComponentType<ToolObject3DAuthoringProps>;
 }

package/src/editor-view.ts

@@ -1,7 +1,9 @@
 import type { AssetKind, EditorCameraState, EditorView, ViewPreset } from './types.js';
+import { EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS } from './types.js';
 
 const PREFIX = 'view.';
 const MAX_QUERY_LENGTH = 4096;
+const WORKSPACE_DOCUMENT_IDS = new Set<string>(EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS);
 const ASSET_KINDS = new Set<AssetKind>([
   'model',
   'image',
@@ -147,16 +149,7 @@ function parseDocument(params: URLSearchParams): EditorView['document'] {
   if (kind === 'project-tool') return { kind, name: value };
   if (kind === 'generation') return { kind, id: value };
   if (kind === 'story') return parseStoryDocument(params, value);
-  if (
-    kind === 'workspace' &&
-    [
-      'workspace:scene',
-      'workspace:game',
-      'workspace:build-profiles',
-      'account',
-      'project-tools',
-    ].includes(value)
-  ) {
+  if (kind === 'workspace' && WORKSPACE_DOCUMENT_IDS.has(value)) {
     return {
       kind,
       id: value as Extract<NonNullable<EditorView['document']>, { kind: 'workspace' }>['id'],

package/src/index.ts

@@ -29,6 +29,7 @@ export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
 export type { ExtensionContributionState } from './extension.js';
 export type {
   ActiveDocumentCapture,
+  AnimationCaptureAction,
   AssetCompareCapture,
   AssetCompareOptions,
   AssetCompareView,
@@ -47,9 +48,13 @@ export type {
   EditorView,
   EditorViewDocument,
   GameCapture,
+  GameplayRecordingCapture,
+  GameplayRecordingOptions,
+  GameplayRecordingStarted,
   HelperVisibility,
   InspectedAction,
   InspectedField,
+  InspectedFieldWrite,
   InspectedHierarchy,
   InspectedHierarchyRow,
   InspectedInspection,
@@ -57,6 +62,7 @@ export type {
   InspectedSection,
   InspectedSectionBody,
   InspectedSubject,
+  InspectedWriteDestination,
   InspectionPresentationKind,
   InspectionSurface,
   LabeledShotSetCapture,

package/src/types.ts

@@ -25,6 +25,7 @@ export interface HelperVisibility {
   cameras: boolean;
   colliders: boolean;
   joints: boolean;
+  particles: boolean;
   lod: boolean;
   audio: boolean;
   splines: boolean;
@@ -72,10 +73,10 @@ export interface ViewportCapture {
  * never a silently HUD-less image passed off as the whole game. `layers` is
  * only present on the composite leg.
  *
- * `flatness` and `hiddenFrame` are the same honesty contract applied to the
- * PIXELS: how much of the frame is one flat surface (a near-blank capture
+ * `flatness` and `loopRecoveryFrame` are the same honesty contract applied to
+ * the PIXELS: how much of the frame is one flat surface (a near-blank capture
  * carries its own "weak evidence" warning), and whether the frame exists only
- * because the capture asked a hidden tab's runtime for one deterministic tick.
+ * because capture recovered a starved host loop with one deterministic tick.
  */
 export interface GameCapture {
   base64: string;
@@ -92,9 +93,38 @@ export interface GameCapture {
     /** Present iff `degenerate`; the sentence to show the caller verbatim. */
     warning?: string;
   };
-  /** True when the editor tab was hidden-paused and the runtime rendered one
+  /** True when the host loop was starved and the runtime rendered one
    *  deterministic tick to produce this frame. */
-  hiddenFrame?: boolean;
+  loopRecoveryFrame?: boolean;
+}
+
+/** Options for recording the clean running-game composite. */
+export interface GameplayRecordingOptions {
+  /** Requested real-time capture cadence. Defaults to 30; range 1–60. */
+  fps?: number;
+  /** Include `dev: true` game layers. Off by default so ordinary evidence is
+   * the player-visible game, not its debugging overlay. */
+  devLayers?: boolean;
+}
+
+/** Facts fixed when a gameplay recording starts. */
+export interface GameplayRecordingStarted {
+  startedAt: string;
+  mimeType: string;
+  width: number;
+  height: number;
+  fps: number;
+  audio: boolean;
+  layers: { canvases: number; domOverlays: number };
+}
+
+/** 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;
 }
 
 export type AssetPreviewView = 'front' | 'right' | 'top' | 'perspective';
@@ -307,13 +337,14 @@ export interface EditorState {
    * Issue #175 — the REAL engine `GameLoop.liveness` behind the current play
    * session, distinct from `playState` above (editor UI state — a store
    * flag that never reflected whether the loop was actually ticking).
-   * `'hidden-paused'` means the T2.1 idle throttle stopped the loop because
-   * the editor tab is backgrounded — deliberate and reversible, but the
-   * game is advancing ZERO ticks right now even though `playState` still
-   * reads `'playing'`. `null` while not in play mode (no loop to report on)
-   * or against an older server that predates this field.
+   * `'loop-starved'` means the host loop has observed no recent rAF progress:
+   * either the current `document.hidden` gate deliberately parked it, or an
+   * armed visible-page callback has not arrived within the starvation
+   * interval. It is explicitly NOT a conclusion that the tab is hidden.
+   * `null` while not in play mode (no loop to report on) or against an older
+   * server that predates this field.
    */
-  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null;
+  loopLiveness?: 'running' | 'loop-starved' | 'stopped' | null;
   /**
    * The connected editor tab's OWN reported visibility/focus
    * (`command-listener.ts`'s `collectPresence`, straight off
@@ -323,8 +354,20 @@ export interface EditorState {
    * BACKGROUNDED tab satisfies perfectly while the engine hidden-pauses its
    * loop underneath. `null` when the page has no `document` at all; absent
    * against an older server that predates the field.
+   *
+   * P21 — `reportedAt` is `Date.now()` in the TAB at the moment those two
+   * values were read. It is what makes this snapshot readable as a
+   * measurement rather than a fact: the tab re-POSTs state on
+   * visibilitychange/focus/blur, after commands and on store changes, so
+   * between those moments this ages, and a reader with no age has no way to
+   * tell a 40ms-old reading from a 40s-old one. Absent against an editor
+   * page that predates the field — never fabricated from the read time.
    */
-  presence?: { visibility: 'visible' | 'hidden' | 'prerender'; focused: boolean } | null;
+  presence?: {
+    visibility: 'visible' | 'hidden' | 'prerender';
+    focused: boolean;
+    reportedAt?: number;
+  } | null;
   /**
    * The pending-restart reason when source changed while the game was
    * RUNNING and the running session is now stale (e.g. an R3F entry-file
@@ -394,6 +437,13 @@ export interface EditorState {
    * attach/detach report, and the command receipts). Absent against an older
    * server, and absent for a tab the server cannot measure.
    *
+   * `pageErrors` is the OTHER half of that verdict — WHY. Uncaught errors and
+   * unhandled rejections captured by the page shell's inline bootstrap, which
+   * runs before the module graph, so the boot failure that leaves no listener
+   * is exactly the one they explain. They come back on a plain GET and need no
+   * cooperation from the page beyond the handler itself. `[]` means the page
+   * reported none; absent means the server cannot measure this tab.
+   *
    * `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
@@ -408,12 +458,17 @@ export interface EditorState {
     presentFor: number;
     lastBeatAgo: number | null;
     epochCount: number;
+    /** Age of the DOCUMENT running in this tab (this page-load), as opposed
+     *  to `presentFor`, which is the age of the tab and survives its
+     *  reloads. Absent against an older server. */
+    epochAgeMs?: number;
     visibility: 'visible' | 'hidden';
     route: 'project' | 'no-project' | 'unknown';
     blessed: boolean;
     channel: 'open' | 'down';
     unresponsive: boolean;
     commandListener?: 'ready' | 'not attached' | (string & {});
+    pageErrors?: string[];
     census?: {
       heapUsedMB: number | null;
       heapLimitMB: number | null;
@@ -432,6 +487,33 @@ export interface EditorState {
    * stopped trying — the browser, not the editor, is what to check.
    */
   tabAutoOpen?: { attempts: number; stopped: boolean };
+  /**
+   * Epoch ms of the last genuine HTML page load this server served — i.e.
+   * when the editor tab last did a FULL document load (first open, reload,
+   * self-heal). Server-observed (`editor-server.ts`'s response-finish
+   * middleware), never browser-reported. `null` until the first page load.
+   *
+   * P20 reads this against {@link publicAssets} to answer "did bytes under
+   * `public/` change since the running document loaded", which is when
+   * module-scope loaders and the page-lifetime asset caches (Pixi `Assets`,
+   * three's loader caches) can still be serving the OLD bytes.
+   */
+  lastIndexRequestAt?: number | null;
+  /**
+   * P20 — what the server has OBSERVED land under this project's `public/`
+   * during this server lifetime, from the same chokidar watcher that
+   * broadcasts `assets-changed`. `lastChangedAt` is `null` when nothing has
+   * changed since the server started. Absent against an older server.
+   *
+   * This is a divergence signal, not a cache verdict: nothing here knows
+   * whether the running page actually holds a stale copy of those bytes,
+   * only that they changed after it loaded.
+   */
+  publicAssets?: {
+    lastChangedAt: number | null;
+    lastPath: string | null;
+    changedCount: number;
+  };
   /**
    * Epoch ms when the server last received a state POST from a browser tab —
    * i.e. the age of the cached snapshot above. Omitted if no tab has ever
@@ -515,13 +597,76 @@ export interface EditorState {
    * project has no readable manifest name.
    */
   projectName?: string | null;
+  /**
+   * The open project's ADAPTER, resolved (ARCHITECTURE-CORE §The editor
+   * protocol). `source: 'module'` means the project's own `vgai.adapter.ts`
+   * supplied the binding table; `'native'` means it declared none and got
+   * `nativeAdapter()` — the declared native default, not a silent fallback.
+   *
+   * `null`/absent means NOBODY HAS LOOKED YET (no project open, or the load
+   * has not finished), which is deliberately distinct from a loaded adapter
+   * whose `scenes.entries` is empty — that is a real, gradable answer. A
+   * non-null `error` means the project's own module did NOT load and the
+   * table below is the native default standing in, with the failure named.
+   *
+   * Structurally declared here rather than imported from
+   * `@vgai/engine/adapter/adapter-module` because this interface is the WIRE
+   * contract: everything in it has already been through JSON.
+   */
+  adapter?: {
+    source: 'module' | 'native';
+    modulePath: string | null;
+    regions: {
+      id: string;
+      surface: string;
+      /** true = this region grades the game's own dev layer, not shipped content. */
+      dev: boolean;
+      projector: string;
+      dialect: string | null;
+      anchors: string[];
+    }[];
+    scenes: {
+      default: string | null;
+      entries: {
+        id: string;
+        label: string;
+        kind: 'scene' | 'prefab';
+        region: string | null;
+        authorable: boolean;
+        reach: { kind: string; [field: string]: unknown };
+        source?: { path: string; export?: string };
+        finder?: string;
+      }[];
+    };
+    notes: string[];
+    error: string | null;
+  } | null;
 }
 
 export type ViewPreset = 'top' | 'front' | 'right' | 'perspective';
 export type ShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+
+/** One operation on the active native animation document's recorder. */
+export type AnimationCaptureAction = 'start' | 'stop' | 'review' | 'commit' | 'discard';
 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. */
+export const EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS = [
+  'workspace:scene',
+  'workspace:game',
+  'workspace:3d-components',
+  'workspace:2d-components',
+  'workspace:ui-components',
+  'workspace:dev',
+  'workspace:build-profiles',
+  'account',
+  'project-tools',
+] as const;
+
+export type EditorViewWorkspaceDocumentId = (typeof EDITOR_VIEW_WORKSPACE_DOCUMENT_IDS)[number];
+
 /**
  * A durable, intentionally small projection of what an editor is presenting.
  * This is not workspace persistence: panel sizes, transient tool state, and
@@ -538,12 +683,7 @@ export type EditorViewDocument =
   | { kind: 'generation'; id: string }
   | {
       kind: 'workspace';
-      id:
-        | 'workspace:scene'
-        | 'workspace:game'
-        | 'workspace:build-profiles'
-        | 'account'
-        | 'project-tools';
+      id: EditorViewWorkspaceDocumentId;
     };
 
 export interface EditorView {
@@ -556,7 +696,7 @@ export interface EditorView {
     frame?: 'document' | 'selection';
     grid?: boolean;
   };
-  utility?: 'profiler' | 'console' | 'animation' | 'light-explorer';
+  utility?: 'profiler' | 'console' | 'animation' | 'behavior' | 'light-explorer';
 }
 
 export interface PresentedEditorView {
@@ -727,6 +867,41 @@ export interface InspectedNothing {
  *  Narrow with `'none' in result`. */
 export type InspectedInspection = InspectedSubject | InspectedNothing;
 
+/**
+ * WHERE THIS WRITE WENT — carried by every `editor.setField()` ack.
+ *
+ * A write with no persistence route still succeeds: it lands on the live
+ * object and journals live-only, exactly as designed. Without this the ack was
+ * indistinguishable from one that reached a file, so a caller could only find
+ * out by diffing the tree — and a healthy consent-off session read as a silent
+ * no-op. `persisted: false` with `destination: "live-only (not saved)"` is the
+ * honest floor: never silence, and never a fabricated file name.
+ *
+ * IT IS PER-EDIT, produced by the component that performed the write and
+ * returned through the editor's persistence pipe — never a property of the
+ * session, the surface or the adapter. A composite holding a live-only three
+ * root beside a source-backed DOM root has no single true answer, and the
+ * adapter-wide one it used to give was the DOM root's (measured on the
+ * vendored racing game: a three-root edit acked `persisted: true` against a
+ * file it never touched). The ack is also AWAITED: it resolves after the bytes
+ * have landed, so a caller holding it can diff the tree immediately.
+ */
+export interface InspectedWriteDestination {
+  /** Where THIS edit's bytes landed, in the writer's own words — a source
+   *  file, the game's own JSX, or a named non-target like
+   *  `"live-only (not saved)"`. */
+  destination: string;
+  /** Whether a byte actually moved for THIS edit. */
+  persisted: boolean;
+}
+
+/** What `editor.setField()` answers: the subject after the write, plus where
+ *  the write went. */
+export interface InspectedFieldWrite {
+  subject: InspectedInspection;
+  write: InspectedWriteDestination;
+}
+
 // ---------------------------------------------------------------- hierarchy
 //
 // The wire mirror of the editor's own `SerializedHierarchyPanel`