@vgai/editor-sdk 0.5.14 → 0.5.16

package/package.json

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

package/src/client.ts

@@ -26,6 +26,7 @@ import type {
   ProjectTemplate,
   ProjectToolCatalog,
   ProjectToolOutcome,
+  RagdollGenerationResult,
   RecentProject,
   ShadingMode,
   StoryCaptureOptions,
@@ -103,6 +104,23 @@ export class EditorCommandError extends Error {
  */
 const COMMAND_DEADLINE_MS = 150_000;
 
+/**
+ * Ceiling on {@link EditorClient.getUnresolvedConsole}. The CLI drains this
+ * on every verb, including ones that never wait for a command envelope, so
+ * a silent hang here would become a silent hang on `vgai examples`. The
+ * server route is a plain in-process GET; 1.5s is already longer than it
+ * should ever take.
+ */
+const CONSOLE_DRAIN_TIMEOUT_MS = 1_500;
+
+/** Context accompanying one {@link EditorClient} response observation. */
+export interface EditorEnvelopeObservation {
+  /** True only when this body came from the console-ledger endpoint and its
+   *  `entries` field is therefore the complete named console set. Command
+   *  payloads may also own an unrelated `entries` field. */
+  readonly unresolvedConsoleComplete: boolean;
+}
+
 /**
  * The GAME DEBUG PLANE, as a contribution's client sees it.
  *
@@ -130,6 +148,27 @@ export interface HistoryStep {
   readonly redoLabel: string | null;
 }
 
+/** What `open()` acknowledges: the workspace document the scene-table entry
+ *  resolved to, and the title its tab now carries — the game's own word for
+ *  that composition, not a filename. */
+export interface OpenedDocument {
+  readonly documentId: string;
+  readonly title: string;
+  /**
+   * The GAME's own answer, present only when opening navigated a running game
+   * (a scene the adapter declares reachable through the game's scenes
+   * contract, or a native swap-slot remount): what was asked for, and which
+   * scene the game reports it is in once its own navigation settled. `current`
+   * can differ from `requested` — that is the game's reading, not a host claim.
+   */
+  readonly scene?: { readonly requested: string; readonly current: string | null };
+  /**
+   * Present when opening restarted play at a native swap-slot key rather than
+   * navigating a live contract — the slot is a module-level const.
+   */
+  readonly restart?: true;
+}
+
 export interface GameDebugDoor {
   /**
    * Read ONE registered state provider by name (`'bot.tester'`). `undefined`
@@ -165,9 +204,14 @@ export class EditorClient {
    * 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 }) {
+  private readonly onEnvelope:
+    | ((body: unknown, observation: EditorEnvelopeObservation) => void)
+    | null;
+
+  constructor(opts?: {
+    url?: string;
+    onEnvelope?: (body: unknown, observation: EditorEnvelopeObservation) => 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("...").',
@@ -223,8 +267,7 @@ export class EditorClient {
         true,
       );
     }
-    const data = (await res.json()) as { ok: boolean; error?: string; code?: string } & T;
-    this.observe(data);
+    const data = (await this.readJson(res)) as { ok: boolean; error?: string; code?: string } & T;
     if (!data.ok) {
       throw new EditorCommandError(
         data.error ?? `Editor command failed: ${res.status}`,
@@ -543,6 +586,11 @@ export class EditorClient {
     await this.command({ type: 'open-asset-tab', path, kind });
   }
 
+  /** Generate a project-owned native Rapier ragdoll from a rigged model asset. */
+  async generateRagdoll(assetPath: string): Promise<RagdollGenerationResult> {
+    return this.command<RagdollGenerationResult>({ type: 'generate-ragdoll', assetPath });
+  }
+
   async closeAsset(key: string): Promise<void> {
     await this.command({ type: 'close-asset-tab', key });
   }
@@ -586,6 +634,15 @@ export class EditorClient {
     return data.subject;
   }
 
+  /** Run one verb exposed by the active Inspector subject, by its id. */
+  async runInspectionAction(actionId: string): Promise<InspectedInspection> {
+    const data = await this.command<{ subject: InspectedInspection }>({
+      type: 'run-inspection-action',
+      actionId,
+    });
+    return data.subject;
+  }
+
   /**
    * The HIERARCHY PANEL's actual rendered row tree, as data.
    *
@@ -630,6 +687,57 @@ export class EditorClient {
     return { subject: data.subject, write: data.write };
   }
 
+  /**
+   * REMOVE one editable path's authored override — the other half of the write
+   * door, and the only one that can express byte-ABSENCE.
+   *
+   * {@link setInspectionField} writes a VALUE, so reverting a property an
+   * authoring gesture ADDED puts the default back EXPLICITLY and leaves the
+   * source one attribute heavier than it started. This drops the property, so
+   * whatever governs it in its absence takes over — the same `io.remove` the
+   * Inspector's revert arrow calls, the same persistence pipe, the same awaited
+   * `{ destination, persisted }` ack.
+   *
+   * Rejects with `code: 'REMOVAL_UNAVAILABLE'` when the field does not declare
+   * itself removable or the lane implements no removal door. That refusal is a
+   * MISSING SEAM, not a failed removal, and it is coded rather than phrased
+   * precisely so a caller can grade the two differently.
+   */
+  async removeInspectionField(path: string): Promise<InspectedFieldWrite> {
+    const data = await this.command<InspectedFieldWrite>({
+      type: 'remove-inspection-field',
+      path,
+    });
+    return { subject: data.subject, write: data.write };
+  }
+
+  /**
+   * OPEN one piece of the adapter's SCENE TABLE by id — a scene, a prefab, or
+   * a story state, because the table makes them siblings (they differ only in
+   * instance site). The ids are exactly what `getState().adapter.scenes.entries`
+   * reports, so the table is both the menu and the address space.
+   *
+   * With a game LIVE in the session, opening a scene the adapter declares
+   * reachable through that game's own scenes contract NAVIGATES it — the same
+   * switch the editor's own scene picker makes — and the answer carries the
+   * game's own reading (`scene`).
+   *
+   * Rejects with a coded reason rather than prose: `SCENE_NOT_FOUND` (and it
+   * names the ids that DO exist), `SCENE_NOT_OPENABLE` carrying the adapter's
+   * own declared reason for a scene it says nothing can reach,
+   * `SCENE_NAVIGATION_NOT_RUNNING` for a live-only scene with no game running,
+   * `SCENE_CONTRACT_UNAVAILABLE` / `SCENE_NOT_IN_CONTRACT` (naming the ids the
+   * game itself publishes) / `SCENE_SWITCH_FAILED` when the running game's own
+   * navigation cannot take it, `SCENE_NOT_OPENABLE_LIVE` when this session has
+   * no remount for a native swap-slot scene,
+   * `SCENE_TABLE_UNAVAILABLE` before the adapter has loaded, and
+   * `SCENE_DOCUMENT_NOT_MOUNTED` when the host has no document for a piece the
+   * table says is openable — a host gap, not a table statement.
+   */
+  async open(id: string): Promise<OpenedDocument> {
+    return this.command<OpenedDocument>({ type: 'open', id });
+  }
+
   /**
    * Undo / redo one project transaction — the same queue the keyboard shortcut
    * drives. `moved` is false when there was nothing left in that direction.
@@ -728,12 +836,16 @@ export class EditorClient {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name, location, template, ...(exampleId ? { exampleId } : {}) }),
     });
+    const data = (await this.readJson(res)) as {
+      ok?: boolean;
+      error?: string;
+      path?: string;
+      config?: ProjectInfo['config'];
+    };
     if (!res.ok) {
-      const body = (await res.json()) as { error?: string };
-      throw new Error(body.error ?? `Create project failed: ${res.status}`);
+      throw new Error(data.error ?? `Create project failed: ${res.status}`);
     }
-    const data = (await res.json()) as { ok: boolean; path: string; config: ProjectInfo['config'] };
-    return { path: data.path, config: data.config };
+    return { path: data.path as string, config: data.config as ProjectInfo['config'] };
   }
 
   async openProject(path: string): Promise<void> {
@@ -742,23 +854,23 @@ export class EditorClient {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ path }),
     });
+    const body = (await this.readJson(res)) as { error?: string };
     if (!res.ok) {
-      const body = (await res.json()) as { error?: string };
       throw new Error(body.error ?? `Open project failed: ${res.status}`);
     }
   }
 
   async getProject(): Promise<ProjectInfo | null> {
     const res = await fetch(`${this.baseUrl}/__editor/project`);
-    if (!res.ok) throw new Error(`Failed to get project: ${res.status}`);
-    const data = (await res.json()) as { project: ProjectInfo | null };
+    const data = (await this.readJson(res)) as { project: ProjectInfo | null; error?: string };
+    if (!res.ok) throw new Error(data.error ?? `Failed to get project: ${res.status}`);
     return data.project;
   }
 
   async listRecentProjects(): Promise<RecentProject[]> {
     const res = await fetch(`${this.baseUrl}/__editor/recent-projects`);
-    if (!res.ok) throw new Error(`Failed to list projects: ${res.status}`);
-    const data = (await res.json()) as { projects: RecentProject[] };
+    const data = (await this.readJson(res)) as { projects: RecentProject[]; error?: string };
+    if (!res.ok) throw new Error(data.error ?? `Failed to list projects: ${res.status}`);
     return data.projects;
   }
 
@@ -769,8 +881,9 @@ export class EditorClient {
    * editor browser merely because they were listed. */
   async listProjectTools(): Promise<ProjectToolCatalog> {
     const res = await fetch(`${this.baseUrl}/__editor/project-tools`);
+    const body = await this.readJson(res);
     if (!res.ok) throw new Error(`Failed to list project tools: ${res.status}`);
-    return (await res.json()) as ProjectToolCatalog;
+    return body as ProjectToolCatalog;
   }
 
   /** Execute one Node-hosted project tool through the shared validated
@@ -793,7 +906,7 @@ export class EditorClient {
         ...(options.instance !== undefined ? { instance: options.instance } : {}),
       }),
     });
-    const body = (await res.json()) as ProjectToolOutcome;
+    const body = (await this.readJson(res)) as ProjectToolOutcome;
     if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
       throw new Error(`Project tool returned an invalid response (${res.status}).`);
     }
@@ -806,8 +919,9 @@ export class EditorClient {
    * request/result shapes remain on their registered operations. */
   async listGenerationJobs(): Promise<GenerationJobsDocument> {
     const res = await fetch(`${this.baseUrl}/__editor/generations`);
+    const body = await this.readJson(res);
     if (!res.ok) throw new Error(`Failed to list generation jobs: ${res.status}`);
-    return (await res.json()) as GenerationJobsDocument;
+    return body as GenerationJobsDocument;
   }
 
   /** Forget operational job state. Accepted provenance and project assets
@@ -816,8 +930,9 @@ export class EditorClient {
     const res = await fetch(`${this.baseUrl}/__editor/generations/${encodeURIComponent(id)}`, {
       method: 'DELETE',
     });
-    if (!res.ok) throw new Error(`Failed to forget generation job: ${res.status}`);
-    return ((await res.json()) as { removed: boolean }).removed;
+    const body = (await this.readJson(res)) as { removed?: boolean; error?: string };
+    if (!res.ok) throw new Error(body.error ?? `Failed to forget generation job: ${res.status}`);
+    return body.removed === true;
   }
 
   // --- Logs ---
@@ -826,10 +941,10 @@ export class EditorClient {
     Array<{ t: number; level: string; msg: string; source?: string }>
   > {
     const res = await fetch(`${this.baseUrl}/__editor/log-entries`);
-    if (!res.ok) return [];
-    const data = (await res.json()) as {
+    const data = (await this.readJson(res)) as {
       entries: Array<{ t: number; level: string; msg: string; source?: string }>;
     };
+    if (!res.ok) return [];
     return data.entries;
   }
 
@@ -837,17 +952,88 @@ export class EditorClient {
 
   async getState(): Promise<EditorState> {
     const res = await fetch(`${this.baseUrl}/__editor/state`);
+    const state = (await this.readJson(res)) as EditorState;
     if (!res.ok) throw new Error(`Failed to get editor state: ${res.status} ${res.statusText}`);
-    const state = (await res.json()) as EditorState;
-    this.observe(state);
     return state;
   }
 
+  /**
+   * The complete unresolved console set the session is holding right now.
+   *
+   * Command envelopes only carry COUNTS (`unresolvedConsole` on
+   * `commandResponseFor`). The named conditions live on GET `/__editor/console`.
+   * This is the method that turns "a command that exits before an envelope
+   * arrives" into a real reading: the CLI calls it at start and at exit
+   * through the same {@link onEnvelope} observer every other response uses.
+   * A session that does not answer within {@link CONSOLE_DRAIN_TIMEOUT_MS} is
+   * a thrown error the caller treats as "nothing learned", never a hang.
+   */
+  async getUnresolvedConsole(opts?: { all?: boolean }): Promise<unknown> {
+    const res = await fetch(
+      `${this.baseUrl}/__editor/console${opts?.all === true ? '?all=1' : ''}`,
+      { signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS) },
+    );
+    const body = await this.readJson(res, true);
+    if (!res.ok) {
+      throw new Error(`Failed to read unresolved console: ${res.status}`);
+    }
+    return body;
+  }
+
+  /** Acknowledge one named console condition. The response is observed and
+   *  hydrated through the same path as every other client response. */
+  async acknowledgeConsole(input: {
+    readonly id: string;
+    readonly reason: string;
+    readonly by: string;
+  }): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/__editor/console/ack`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS * 4),
+    });
+    const body = await this.readJson(res);
+    return body;
+  }
+
+  /** Parse one JSON body and hand it to {@link onEnvelope}.
+   *
+   * A command/state envelope carries current counts but not the named set. If
+   * an observer is installed, do the bounded console GET before resolving the
+   * 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> {
+    const body: unknown = await res.json();
+    this.observe(body, { unresolvedConsoleComplete: consoleComplete });
+    if (
+      this.onEnvelope !== null &&
+      !consoleComplete &&
+      body !== null &&
+      typeof body === 'object' &&
+      'unresolvedConsole' in body
+    ) {
+      try {
+        const consoleRes = await fetch(`${this.baseUrl}/__editor/console`, {
+          signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS),
+        });
+        if (consoleRes.ok) {
+          const consoleBody: unknown = await consoleRes.json();
+          this.observe(consoleBody, { unresolvedConsoleComplete: true });
+        }
+      } catch {
+        // The original response remains authoritative. A reporting follow-up
+        // may degrade to its count-only envelope, never break the command.
+      }
+    }
+    return body;
+  }
+
   /** Hand one response body to {@link onEnvelope}, never letting it throw. */
-  private observe(body: unknown): void {
+  private observe(body: unknown, observation: EditorEnvelopeObservation): void {
     if (this.onEnvelope === null) return;
     try {
-      this.onEnvelope(body);
+      this.onEnvelope(body, observation);
     } catch {
       // A reporting hook may never break the command it is reporting on.
     }

package/src/contributions.ts

@@ -40,6 +40,13 @@ export interface ToolContributionNode {
  */
 export interface ToolObject3DPreviewSource {
   readonly root: Object3D;
+  /**
+   * Optional authored roots for the document hierarchy when `root` is a
+   * presentation/lifetime container rather than authored content itself.
+   * Framing, ticking and disposal still own `root`; this list only scopes the
+   * shared Hierarchy. Omitted means `root`, preserving the native tree.
+   */
+  readonly hierarchyRoots?: readonly Object3D[];
   readonly animations?: readonly AnimationClip[];
   /**
    * The source's OWN tick, and the host drives it EXACTLY ONCE per mount — for

package/src/editor-view.ts

@@ -11,7 +11,6 @@ const ASSET_KINDS = new Set<AssetKind>([
   'animation',
   'json',
   'prefab',
-  'material',
   'source',
 ]);
 const CAMERAS = new Set<ViewPreset | 'isometric'>([

package/src/index.ts

@@ -4,7 +4,12 @@ export type {
   GenerationJobStatus,
   GenerationJobsDocument,
 } from '@vgai/sdk/generations';
-export type { GameDebugDoor, HistoryStep } from './client.js';
+export type {
+  EditorEnvelopeObservation,
+  GameDebugDoor,
+  HistoryStep,
+  OpenedDocument,
+} from './client.js';
 export { EditorClient, EditorCommandError } from './client.js';
 export type {
   ToolAssetInspectorContributionMatch,
@@ -73,6 +78,7 @@ export type {
   ProjectToolCatalogEntry,
   ProjectToolContribution,
   ProjectToolOutcome,
+  RagdollGenerationResult,
   RecentProject,
   ShadingMode,
   ShotSetPoseRotation,

package/src/types.ts

@@ -9,15 +9,7 @@
  */
 export type ViewportTab = 'edit' | 'play';
 
-export type AssetKind =
-  | 'model'
-  | 'image'
-  | 'audio'
-  | 'animation'
-  | 'json'
-  | 'prefab'
-  | 'material'
-  | 'source';
+export type AssetKind = 'model' | 'image' | 'audio' | 'animation' | 'json' | 'prefab' | 'source';
 
 export interface HelperVisibility {
   bounds: boolean;
@@ -58,6 +50,16 @@ export interface ViewportCapture {
   mimeType: 'image/png';
 }
 
+/** Result of the editor's native Asset Lab ragdoll-generation operation. */
+export interface RagdollGenerationResult {
+  capability: 'added' | 'present';
+  componentPath: string;
+  storyPath: string;
+  documentId: string;
+  bodies: number;
+  joints: number;
+}
+
 /**
  * Unit 4 (live-front-door wave) — the RUNNING GAME's pixels, as captured by
  * the `bridge-screenshot` relay op (`command-listener.ts`'s
@@ -599,9 +601,13 @@ export interface EditorState {
   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.
+   * protocol). `source` names WHOSE declaration is running: `'project'` = the
+   * project's own `vgai.adapter.ts` supplied the binding table (and it always
+   * outranks the registry); `'registry'` = the HOST's in-tree ingest registry
+   * supplied it, matched on this project's ingest root id, with `modulePath`
+   * naming the repo file — a binding the project did not ship, stated rather
+   * than inferred; `'native'` = 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
@@ -614,7 +620,7 @@ export interface EditorState {
    * contract: everything in it has already been through JSON.
    */
   adapter?: {
-    source: 'module' | 'native';
+    source: 'project' | 'registry' | 'native';
     modulePath: string | null;
     regions: {
       id: string;
@@ -790,14 +796,17 @@ export interface InspectedField {
   /** The value shown is the declared default — the document does not carry it. */
   defaulted?: boolean;
   readonly?: boolean;
+  /** The same reason shown by the Inspector and returned by a refused write. */
+  readonlyReason?: string;
   resettable?: boolean;
   revertsTo?: string;
   group?: string;
   options?: readonly unknown[];
 }
 
-/** A section's content. An opaque body is a NAMED OPAQUE — the editor renders
- *  it with a React component the wire deliberately does not describe. The two
+/** A section's content. Custom RENDERING remains opaque — the wire never
+ *  introspects React — while any ordinary descriptor channel that chrome owns
+ *  remains visible as `fields`, including its write-refusal reasons. The two
  *  opaque kinds are distinguished because "this subject has a live preview"
  *  is a real fact about it: `custom` is a contributed block, `preview` is the
  *  subject's own square view of itself.
@@ -809,7 +818,13 @@ export interface InspectedField {
  *  quaternion behind them is not on this wire). */
 export type InspectedSectionBody =
   | { kind: 'fields'; fields: readonly InspectedField[] }
-  | { kind: 'custom'; id: string; title: string; data?: Record<string, unknown> }
+  | {
+      kind: 'custom';
+      id: string;
+      title: string;
+      data?: Record<string, unknown>;
+      fields?: readonly InspectedField[];
+    }
   | { kind: 'preview'; id: string; title: string };
 
 export interface InspectedSection {