@vgai/editor-sdk 0.5.2 → 0.5.3

package/README.md

@@ -11,8 +11,8 @@ to the caller.
 ```ts
 import { EditorClient } from '@vgai/editor-sdk';
 
-const editor = new EditorClient(); // default http://localhost:5173
-const projectEditor = new EditorClient({ url: 'http://localhost:25786' });
+const editor = new EditorClient(); // default http://127.0.0.1:20173
+const projectEditor = new EditorClient({ url: 'http://127.0.0.1:25786' });
 await editor.play();
 
 // Present the same editor subject/view to the connected human and get a
@@ -69,7 +69,7 @@ import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';
 export default function MapBuilder({ tool, client, account }: ToolContributionProps) {
   return (
     <Button
-      variant="solid"
+      variant="primary"
       onClick={() => void client.runProjectTool(tool.name, { seed: 42 }, { confirm: true })}
       title={`Default execution: ${account.preferredRoute}`}
     >
@@ -99,7 +99,7 @@ utilities. Badges are for short statuses and counts, not headings.
 ### Extension contract (`@vgai/editor-sdk/extension`)
 
 The typed contract for everything a game project contributes TO the editor —
-four surfaces, one degradation ladder (`ExtensionContributionTier`:
+three surfaces, one degradation ladder (`ExtensionContributionTier`:
 `active` / `absent` / `failed`). An absent contribution hides its surface
 (the editor never fabricates placeholder data); a failing one is contained
 per-contribution and reported loudly on the editor console — never a crashed
@@ -110,36 +110,7 @@ editor, never silent fake output.
    there is no parallel rail.
 2. **Inspector sections** — `selection.inspector` / `asset.inspector` tool
    contributions with an exported `match`.
-3. **Per-component viewport gizmos** — a `GameComponent` subclass declares
-   `static editorGizmo: ComponentGizmoHook` (the Unity `OnDrawGizmos`
-   analog). The editor renders its objects for every scene entity carrying
-   that component — editor-only layer, Helpers ▸ Components toggle,
-   raycast-excluded, draw-only. Props arrive schema-parsed through the
-   component's own Zod `static schema`; build objects with `ctx.three` (the
-   editor's three module):
-
-   ```ts
-   import type { ComponentGizmoHook } from '@vgai/editor-sdk/extension';
-
-   export class TriggerZone extends GameComponent {
-     static schema = z.object({ radius: z.number().default(2) });
-     static editorGizmo: ComponentGizmoHook = ({ props, three }) => {
-       const geo = new three.RingGeometry(0.98 * (props.radius as number), props.radius as number);
-       return new three.Mesh(geo, new three.MeshBasicMaterial({ wireframe: true }));
-     };
-     update() {}
-   }
-   ```
-
-   The scaffold template's `SceneCamera` (`src/scripts/components/
-   scene-camera.ts`) is the worked reference.
-
-   Editing a component file in edit mode re-captures the registry and
-   redraws contributed gizmos (script-HMR); registry restructures may need a
-   project reopen. Recorded deferral: in the HOSTED (browser) editor,
-   contributed component gizmos resolve `absent` — example registries are
-   evaluated for play but not captured at design time.
-4. **System adapters** — runtime capabilities registered from game code via
+3. **System adapters** — runtime capabilities registered from game code via
    `ctx.registerSystemAdapter?.(kind, impl)` (`SystemAdapters` in
    `@vgai/engine`). Deliberately not re-exported here: the engine already
    publishes that seam and every consumer of it also imports the engine.
@@ -168,7 +139,7 @@ buffers and images must resolve on the same project origin. The thin CLI
 equivalent writes the four views and contact sheet to disk:
 
 ```bash
-npm run vgai -- asset-preview --asset /models/storefront.glb --out artifacts/storefront
+npm run vgai -- screenshot /models/storefront.glb --out artifacts/storefront
 ```
 
 ## Limitations

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.2"
+    "@vgai/sdk": "0.5.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/client.ts

@@ -12,6 +12,7 @@ import type {
   EditorView,
   GameCapture,
   HelperVisibility,
+  InspectedInspection,
   LabeledShotSetCapture,
   PresentedEditorView,
   ProjectInfo,
@@ -20,31 +21,111 @@ import type {
   ProjectToolOutcome,
   RecentProject,
   ShadingMode,
+  StoryCaptureOptions,
+  StoryVariantCapture,
   TransformMode,
   TransformSpace,
   Vec3Value,
   ViewPreset,
   ViewportCapture,
+  ViewportTab,
 } from './types.js';
 
-const DEFAULT_URL = 'http://localhost:5173';
+// The editor's default origin, spelled out because this package deliberately
+// does not depend on `@vgai/engine`. `DEFAULT_EDITOR_PORT` in
+// `packages/engine/src/manifest/editor-port.ts` is the owner of the number and
+// of the never-`localhost` rule; keep this in step with it.
+const DEFAULT_URL = 'http://127.0.0.1:20173';
+
+/**
+ * A refused editor command, carrying the relay's own STRUCTURED failure code
+ * alongside the prose.
+ *
+ * `/__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
+ * 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.
+ */
+export class EditorCommandError extends Error {
+  readonly code: string | undefined;
+  constructor(message: string, code?: string | undefined) {
+    super(message);
+    this.name = 'EditorCommandError';
+    this.code = code;
+  }
+}
+
+/**
+ * The GAME DEBUG PLANE, as a contribution's client sees it.
+ *
+ * Deliberately the same two words `@vgai/live`'s session binding uses
+ * (`game.state(name)` / `game.command(name, ...args)`), because it is the same
+ * plane: whatever the running game registered through `ctx.debug` — a provider
+ * read by name, a command invoked by name. A tool contribution that wants the
+ * game's own vitals in its panel has this door and no other; there is
+ * deliberately no per-capability method, because a game names its own
+ * providers and commands.
+ *
+ * Both legs reject LOUDLY (`EditorCommandError`) rather than answer with a
+ * placeholder: play not running is `'not in play mode — start play before
+ * using the debug seam'`, and an unregistered command carries
+ * `code: 'DEBUG_COMMAND_NOT_REGISTERED'`. A panel decides what to show for
+ * those; the client never invents one.
+ */
+export interface GameDebugDoor {
+  /**
+   * Read ONE registered state provider by name (`'bot.tester'`). `undefined`
+   * when the running game registered no such provider — or no debug adapter at
+   * all, which is an honest answer rather than a refusal.
+   */
+  state(name: string): Promise<unknown>;
+  /** Invoke ONE registered debug command by name, with its own arguments. */
+  command(name: string, ...args: unknown[]): Promise<unknown>;
+}
 
 export class EditorClient {
   private readonly baseUrl: string;
 
+  /**
+   * The running game's debug plane — see {@link GameDebugDoor}. It rides the
+   * SAME `/__editor/command` relay every other method here uses (relay cases
+   * `inspect-gameplay-state` / `invoke-debug-command`, `command-listener.ts`),
+   * so a tool contribution reaches the game through the client it already has
+   * rather than a second channel of its own.
+   */
+  readonly game: GameDebugDoor;
+
   constructor(opts?: { url?: string }) {
     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://localhost:5173" }), not new EditorClient("...").',
+        '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');
     if (unknownOptions.length > 0) {
       throw new Error(
-        `EditorClient: unknown option${unknownOptions.length === 1 ? '' : 's'} ${unknownOptions.map((key) => `"${key}"`).join(', ')}. Use { url: "http://localhost:<port>" } to target an editor.`,
+        `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.game = {
+      state: async (name: string): Promise<unknown> => {
+        // `keys` narrows the relay to the one provider asked for, so a panel
+        // polling one vital never drags the whole plane's `stateAll()` across
+        // the wire. A game with no debug adapter answers `{ state: null }`.
+        const data = await this.command<{ state: Record<string, unknown> | null }>({
+          type: 'inspect-gameplay-state',
+          keys: [name],
+        });
+        return data.state?.[name];
+      },
+      command: async (name: string, ...args: unknown[]): Promise<unknown> =>
+        (await this.command<{ result: unknown }>({ type: 'invoke-debug-command', name, args }))
+          .result,
+    };
   }
 
   private async command<T extends object = Record<string, never>>(
@@ -55,9 +136,9 @@ export class EditorClient {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
     });
-    const data = (await res.json()) as { ok: boolean; error?: string } & T;
+    const data = (await res.json()) as { ok: boolean; error?: string; code?: string } & T;
     if (!data.ok) {
-      throw new Error(data.error ?? `Editor command failed: ${res.status}`);
+      throw new EditorCommandError(data.error ?? `Editor command failed: ${res.status}`, data.code);
     }
     return data;
   }
@@ -118,6 +199,17 @@ export class EditorClient {
     await this.command({ type: 'focus-selection' });
   }
 
+  /**
+   * Frame the EDIT viewport camera on one entity — the strict sibling of
+   * {@link focusEntity}. Same framing; an id the scene does not know is a
+   * refusal naming the id (`EditorCommandError`, code `ENTITY_NOT_FOUND`)
+   * rather than `focusEntity`'s silent no-op, so a caller that frames an
+   * entity before capturing it cannot photograph the wrong thing.
+   */
+  async frameEntity(id: string): Promise<void> {
+    await this.command({ type: 'frame-entity', id });
+  }
+
   async viewPreset(preset: ViewPreset): Promise<void> {
     await this.command({ type: 'view-preset', preset });
   }
@@ -142,7 +234,7 @@ export class EditorClient {
   /**
    * Unit 4 (live-front-door wave) — capture the RUNNING GAME (`vgai
    * screenshot`'s wire leg). Sends the SAME `bridge-screenshot` relay op
-   * `@vgai/e2e`'s `RelayTransport.screenshot` (and therefore
+   * `@vgai/live`'s `RelayTransport.screenshot` (and therefore
    * `game.screenshot()` on the relay path) already sends, so all three
    * surfaces composite the identical full game stack — canvas(es) plus the
    * HUD/react DOM layers — rather than any of them inventing a second,
@@ -154,10 +246,34 @@ export class EditorClient {
    * mode isn't running ("not in play mode — start play before using the
    * 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
+   * 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.
+   * Off by default: a caller who does not ask must never be handed a frame
+   * that only exists because the capture drove the game.
+   *
+   * `opts.devLayers` puts the game's DEV LAYERS (`dev: true` roots — its own
+   * in-game dev GUI) INTO the frame. Also off by default, for the mirror-image
+   * reason: a panel frame at the moment of a failure is strong evidence, and a
+   * "does the game look right" frame with the panel painted over it is
+   * worthless — so the contamination only happens when someone asks for it.
    */
-  async captureGame(): Promise<GameCapture> {
-    const data = await this.command<GameCapture>({ type: 'bridge-screenshot' });
+  async captureGame(opts?: {
+    refreshHiddenFrame?: boolean;
+    devLayers?: boolean;
+  }): Promise<GameCapture> {
+    const data = await this.command<GameCapture>({
+      type: 'bridge-screenshot',
+      ...(opts?.refreshHiddenFrame === true ? { refreshHiddenFrame: true } : {}),
+      ...(opts?.devLayers === true ? { devLayers: true } : {}),
+    });
     const layers = data.layers;
+    const flatness = data.flatness;
     return {
       base64: data.base64,
       mimeType: data.mimeType,
@@ -165,6 +281,11 @@ export class EditorClient {
       ...(layers && Number.isInteger(layers.canvases) && Number.isInteger(layers.domOverlays)
         ? { layers }
         : {}),
+      // Pass the pixel-honesty fields through as the page reported them: the
+      // 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 } : {}),
     };
   }
 
@@ -191,7 +312,7 @@ export class EditorClient {
   }
 
   /**
-   * A project-defined labeled shot set (`vgai asset-preview --shots <set>`):
+   * A project-defined labeled shot set (`vgai screenshot <target> --shots <set>`):
    * the DEFINITION travels with the command (project data — see
    * `AssetPreviewShotSetDefinition`; the CLI resolves it from the registered
    * `project.<set>.previewShots` tool), and the editor's generic
@@ -215,13 +336,15 @@ export class EditorClient {
       width: data.width,
       height: data.height,
       shots: data.shots,
+      // An older editor predates the empty-frame guard and sends none.
+      warnings: data.warnings ?? [],
       contactSheet: data.contactSheet,
     };
   }
 
   /**
-   * B8.4 — score the asset against a reference GLB (`vgai asset-preview
-   * --compare <ref.glb>`): matched orthographic front + side silhouettes
+   * B8.4 — score the asset against a reference GLB (`vgai screenshot
+   * <model.glb> --compare <ref.glb>`): matched orthographic front + side silhouettes
    * (equal-height bounding-box framing, both yaw-normalized to face the
    * camera), per-view IoU numbers, and overlay evidence images. The
    * reference GLB's raw bytes travel base64 in the command; the editor
@@ -242,9 +365,38 @@ export class EditorClient {
     return { width: data.width, height: data.height, views: data.views };
   }
 
+  /**
+   * The STORY lane (`vgai screenshot <file>.stories.tsx`): every CSF export of
+   * one project story file rendered in the live session's DOM and captured
+   * through the same composite leg {@link captureGame} uses, returned as
+   * per-export images plus one variant sheet. `options.story` narrows to a
+   * single export.
+   *
+   * Rendering happens in the EDITOR — the SDK never imports, composes or
+   * mounts a CSF module itself; the session already owns that machinery for
+   * its Stories panel and this drives it.
+   */
+  async captureStoryVariants(
+    modulePath: string,
+    options: StoryCaptureOptions = {},
+  ): Promise<StoryVariantCapture> {
+    const data = await this.command<StoryVariantCapture>({
+      type: 'capture-story-variants',
+      modulePath,
+      ...options,
+    });
+    return {
+      modulePath: data.modulePath,
+      width: data.width,
+      height: data.height,
+      variants: data.variants,
+      contactSheet: data.contactSheet,
+    };
+  }
+
   // --- Panels ---
 
-  async showViewport(tab: 'scene' | 'game'): Promise<void> {
+  async showViewport(tab: ViewportTab): Promise<void> {
     await this.command({ type: 'viewport-tab', tab });
   }
 
@@ -252,6 +404,18 @@ export class EditorClient {
     await this.command({ type: 'active-tab', key: '__inspector__' });
   }
 
+  /** Show several instances of the running game split-screen — multiplayer
+   *  authoring. Pass a total `count` (default "Player N" labels) or an array of
+   *  `names` (its length is the count; index 0 is the primary). Requires a live
+   *  play session. */
+  async setInstanceCount(countOrNames: number | string[]): Promise<void> {
+    await this.command(
+      Array.isArray(countOrNames)
+        ? { type: 'set-instance-count', names: countOrNames }
+        : { type: 'set-instance-count', count: countOrNames },
+    );
+  }
+
   async openAsset(path: string, kind: AssetKind): Promise<void> {
     await this.command({ type: 'open-asset-tab', path, kind });
   }
@@ -278,6 +442,27 @@ export class EditorClient {
     return { view: presented.view, url: presented.url, warnings: presented.warnings };
   }
 
+  /**
+   * The INSPECTION SUBJECT the editor is showing right now, as data — the
+   * serialized projection of the inspection model (design:
+   * `docs/ARCHITECTURE-CORE.md` §Editor chrome, "The Inspection Model").
+   *
+   * The same subject a human reads in the inspector: identity, presentation,
+   * verbs, and the identified sections in display order — with a `fields`
+   * section's CURRENT VALUES read through the same io the field rows edit
+   * through. With nothing selected it answers the active surface's own
+   * no-selection subject when it has one, exactly as the panel does; it never
+   * reports another surface's, and when the panel itself is unmounted it
+   * answers `{none: true}` rather than a subject nobody is looking at. A
+   * `custom` section body is a named opaque (`{kind, id, title}`) — the editor
+   * renders those with React — plus its displayed values under `data` when it
+   * has any (the Transform section's position/rotation/scale).
+   */
+  async inspect(): Promise<InspectedInspection> {
+    const data = await this.command<{ subject: InspectedInspection }>({ type: 'inspect' });
+    return data.subject;
+  }
+
   /** Read the editor's actual current durable projection. */
   async currentView(): Promise<EditorView> {
     const data = await this.command<{ view: EditorView }>({ type: 'current-view' });
@@ -329,10 +514,10 @@ export class EditorClient {
   }
 
   // --- Scene ---
-
-  async openScene(path: string): Promise<void> {
-    await this.command({ type: 'open-scene', path });
-  }
+  //
+  // `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 ---
 
@@ -397,12 +582,20 @@ export class EditorClient {
   async runProjectTool(
     name: string,
     input: unknown = {},
-    options: { confirm?: boolean } = {},
+    options: { confirm?: boolean; instance?: string } = {},
   ): Promise<ProjectToolOutcome> {
     const res = await fetch(`${this.baseUrl}/__editor/project-tools/run`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ name, input, confirm: options.confirm === true }),
+      body: JSON.stringify({
+        name,
+        input,
+        confirm: options.confirm === true,
+        // Omitted (not null) when unset — the wire body is JSON and the tool
+        // host reads absence as "the sole instance", same convention as the
+        // relay's `instance`.
+        ...(options.instance !== undefined ? { instance: options.instance } : {}),
+      }),
     });
     const body = (await res.json()) as ProjectToolOutcome;
     if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {

package/src/contributions.ts

@@ -26,7 +26,6 @@ export interface ToolContributionNode {
   readonly kind: string;
   readonly parentId: string | null;
   readonly childIds: string[];
-  readonly flags: object;
 }
 
 /**
@@ -97,8 +96,28 @@ export interface ToolObject3DPreviewProps {
 export interface ToolObject3DAuthoringProps {
   readonly documentId: string;
   readonly sourcePath: string;
+  /**
+   * Produce the graph to author. Called ONCE PER ACTIVATION, not once per
+   * document: the host tears its scene down whenever the document goes inactive
+   * (an ordinary tab switch) and calls this again on the way back, disposing
+   * whatever the previous call returned. So a caller must pick one of two
+   * shapes, and there is no third:
+   *
+   *  - a FACTORY — build a fresh graph every call, and let the returned
+   *    `dispose` free it (what the model/entity asset documents do); or
+   *  - an OWNED graph — return the same root every call with an EMPTY `dispose`,
+   *    and free it from the caller's own lifetime instead (what the 3D
+   *    components board and the story turntable do, because their graph is
+   *    async to create).
+   *
+   * Returning a graph you cannot rebuild synchronously AND a `dispose` that
+   * really frees it is the third shape, and it renders a black panel on the
+   * second activation.
+   */
   readonly build: () => ToolObject3DPreviewSource;
   readonly displayName?: string;
+  /** Explicit flat scene background. Omit it to inherit the editor's standard
+   *  viewport dressing (environment, gradient backdrop, key light). */
   readonly background?: ColorRepresentation;
   readonly cameraDirection?: readonly [number, number, number];
   readonly autoplay?: boolean;

package/src/extension.ts

@@ -2,7 +2,7 @@
  * Extension contract (W3a) — the published surface a game project uses to
  * contribute to the editor, with the degradation ladder made API.
  *
- * A project extends the editor through exactly four surfaces:
+ * A project extends the editor through exactly three surfaces:
  *
  * (a) **Editor panels** — registered into the Dockview workspace as documents
  *     or utilities via a tool contribution (`package.json#vgai.tools` →
@@ -12,11 +12,7 @@
  * (b) **Inspector sections** — `point: 'selection.inspector'` /
  *     `'asset.inspector'` tool contributions with an exported `match`.
  *     Types: `ToolInspectorContributionProps` and friends, same module.
- * (c) **Per-component viewport gizmos** (this module) — a `GameComponent`
- *     subclass declares `static editorGizmo: ComponentGizmoHook`; the editor
- *     renders its objects for every scene entity carrying that component,
- *     on the editor-only layer, alongside the built-in gizmos.
- * (d) **System adapters** — runtime capabilities (networking, debug, …)
+ * (c) **System adapters** — runtime capabilities (networking, debug, …)
  *     registered from game code via `ctx.registerSystemAdapter?.(kind, impl)`
  *     (`SystemAdapters` in `@vgai/engine`'s `runtime/types` /
  *     `adapter/system-adapter`). Deliberately NOT re-exported here: the
@@ -36,74 +32,8 @@
  *   console) — never silently swallowed into fake output.
  */
 
-import type * as THREE from 'three';
-
 /**
  * Capability tier of a single extension contribution — the degradation
  * ladder made API (see the module doc above for the exact semantics).
  */
 export type ExtensionContributionTier = 'active' | 'absent' | 'failed';
-
-/** Resolved status of one per-component gizmo contribution. */
-export interface ComponentGizmoStatus {
-  tier: ExtensionContributionTier;
-  /** Present only for `'failed'` — the contained error's message. */
-  error?: string;
-}
-
-/**
- * What a component gizmo hook receives. Draw with `ctx.three` — the EDITOR's
- * three module — so returned objects render in the editor viewport
- * regardless of which physical `three` copy the project itself resolves.
- */
-export interface ComponentGizmoContext {
-  /** The component's registry name (the key in `entity.components`). */
-  componentName: string;
-  /**
-   * The entity's authored component data. When the component class declares
-   * a `static schema` (Zod), this is the schema-parsed value — defaults
-   * applied, invalid data already rejected (a parse failure fails the
-   * contribution loudly instead of fabricating defaults).
-   */
-  props: Record<string, unknown>;
-  /** The editor's `three` module — build all gizmo objects with this. */
-  three: typeof THREE;
-}
-
-/**
- * Per-component viewport gizmo contribution (critique O11 — the
- * `OnDrawGizmos` half of the extension contract). Declared as a STATIC on a
- * `GameComponent` subclass:
- *
- * ```ts
- * import type { ComponentGizmoHook } from '@vgai/editor-sdk/extension';
- *
- * export class TriggerZone extends GameComponent {
- *   static schema = z.object({ radius: z.number().default(2) });
- *   static editorGizmo: ComponentGizmoHook = ({ props, three }) => {
- *     const ring = new three.LineLoop(circleGeometry(props.radius as number),
- *       new three.LineBasicMaterial({ color: 0x44ff88 }));
- *     return ring;
- *   };
- *   // …
- * }
- * ```
- *
- * Contract:
- * - Runs at DESIGN TIME in the editor (never in the running game). Called
- *   whenever the editor (re)builds gizmos for an entity carrying the
- *   component; treat it as pure — read `props`, return fresh objects.
- * - Returned objects are parented to the entity's `Object3D` (local space),
- *   tagged as editor helpers on the editor-only render layer, excluded from
- *   raycast selection, and toggled by the viewport's Helpers ▸ Components
- *   filter. The editor disposes them with the entity's other gizmos.
- * - Return `null` (or an empty array) to draw nothing for this entity.
- * - Draw-only, v1: gizmos visualize; they do not edit. Interactive handles
- *   stay editor-internal until a consumer needs them (no dead surface).
- * - Throwing (or returning a non-Object3D) marks the contribution
- *   `'failed'`: contained, hidden, reported loudly. The editor never
- *   substitutes a fallback drawing.
- */
-export type ComponentGizmoHook = (
-  ctx: ComponentGizmoContext,
-) => THREE.Object3D | readonly THREE.Object3D[] | null;

package/src/index.ts

@@ -4,7 +4,8 @@ export type {
   GenerationJobStatus,
   GenerationJobsDocument,
 } from '@vgai/sdk/generations';
-export { EditorClient } from './client.js';
+export type { GameDebugDoor } from './client.js';
+export { EditorClient, EditorCommandError } from './client.js';
 export type {
   ToolAssetInspectorContributionMatch,
   ToolAssetInspectorContributionProps,
@@ -16,12 +17,7 @@ export type {
   ToolInspectorContributionProps,
 } from './contributions.js';
 export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
-export type {
-  ComponentGizmoContext,
-  ComponentGizmoHook,
-  ComponentGizmoStatus,
-  ExtensionContributionTier,
-} from './extension.js';
+export type { ExtensionContributionTier } from './extension.js';
 export type {
   ActiveDocumentCapture,
   AssetCompareCapture,
@@ -32,7 +28,9 @@ export type {
   AssetPreviewCapture,
   AssetPreviewOptions,
   AssetPreviewShotSetDefinition,
+  AssetPreviewShotWarning,
   AssetPreviewSource,
+  AssetPreviewStage,
   AssetPreviewView,
   EditorCameraState,
   EditorEntitySummary,
@@ -41,6 +39,15 @@ export type {
   EditorViewDocument,
   GameCapture,
   HelperVisibility,
+  InspectedAction,
+  InspectedField,
+  InspectedInspection,
+  InspectedNothing,
+  InspectedSection,
+  InspectedSectionBody,
+  InspectedSubject,
+  InspectionPresentationKind,
+  InspectionSurface,
   LabeledShotSetCapture,
   PresentedEditorView,
   ProjectInfo,
@@ -53,9 +60,13 @@ export type {
   ShadingMode,
   ShotSetPoseRotation,
   ShotSetShot,
+  StoryCaptureOptions,
+  StoryVariantCapture,
+  StoryVariantImage,
   TransformMode,
   TransformSpace,
   Vec3Value,
   ViewPreset,
   ViewportCapture,
+  ViewportTab,
 } from './types.js';

package/src/types.ts

@@ -1,3 +1,14 @@
+/**
+ * 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
+ * PLAY TRANSPORT (the five stable controls) — this is which tab is showing.
+ */
+export type ViewportTab = 'edit' | 'play';
+
 export type AssetKind =
   | 'model'
   | 'image'
@@ -19,8 +30,6 @@ export interface HelperVisibility {
   splines: boolean;
   navmesh: boolean;
   skeletons: boolean;
-  /** Per-component gizmo contributions (W3a extension contract). */
-  components: boolean;
 }
 
 export interface Vec3Value {
@@ -60,25 +69,74 @@ export interface ViewportCapture {
  * container, no DOM `Image`/`XMLSerializer`, or a rasterization failure) —
  * 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
+ * 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.
  */
 export interface GameCapture {
   base64: string;
   mimeType: 'image/png';
   composite: boolean;
   layers?: { canvases: number; domOverlays: number };
+  /** Degeneracy measure — `packages/editor/src/composite-screenshot.ts`'s
+   *  `measureFlatness`. Absent when pixel readback was unavailable. */
+  flatness?: {
+    dominantFraction: number;
+    dominantColor: string;
+    distinctRegions: number;
+    degenerate: boolean;
+    /** 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
+   *  deterministic tick to produce this frame. */
+  hiddenFrame?: boolean;
 }
 
 export type AssetPreviewView = 'front' | 'right' | 'top' | 'perspective';
 export type AssetPreviewBackground = 'neutral' | 'transparent';
 
+/**
+ * What the Asset Lab is being asked to photograph: a same-origin project
+ * model path, a live scene entity, or RAW GLB BYTES that travel with the
+ * command.
+ *
+ * The bytes form exists because rasterization only happens where there is a
+ * GPU. A Node host that built a model in memory — the module-look lane's
+ * `project.bake.preview`, which compiles a project TS module's `Object3D` and
+ * exports it to an in-memory GLB without writing anything — has pixels
+ * nowhere until the live editor session renders them. It is four-view,
+ * lab-stage only: bytes stand nowhere, so `stage: 'scene'`, the shot-set /
+ * source-review modes and compare are all refused by name at the relay.
+ */
 export type AssetPreviewSource =
-  | { assetPath: string; entityId?: never }
-  | { entityId: string; assetPath?: never };
+  | { assetPath: string; entityId?: never; glbBase64?: never }
+  | { entityId: string; assetPath?: never; glbBase64?: never }
+  | { glbBase64: string; assetPath?: never; entityId?: never };
+
+/**
+ * Where an ENTITY capture is staged.
+ *
+ * `'lab'` (the default on every surface) is the editor's neutral Asset Lab
+ * stage: an isolated, yaw-normalized snapshot under fixed studio lighting,
+ * identical whatever the entity's surroundings are. `'scene'` photographs the
+ * entity where it stands in the live scene, under the scene's own lighting,
+ * with the editor's own grid/gizmos/helpers excluded — see
+ * `packages/editor/src/asset-preview.ts`'s `captureSceneStageAssetPreview`.
+ *
+ * `'scene'` is an ENTITY-only, four-view option: the relay refuses it by name
+ * for an `assetPath` source (a model loaded from disk stands nowhere) and for
+ * the shot-set / source-review / compare modes (each stages its own subject).
+ */
+export type AssetPreviewStage = 'lab' | 'scene';
 
 export interface AssetPreviewOptions {
   width?: number;
   height?: number;
   background?: AssetPreviewBackground;
+  stage?: AssetPreviewStage;
 }
 
 export interface AssetPreviewCapture {
@@ -89,8 +147,39 @@ export interface AssetPreviewCapture {
 }
 
 /**
- * B8.4 — the asset-preview compare mode (`vgai asset-preview --compare
- * <ref.glb>`): the asset and a caller-supplied reference GLB rendered with
+ * The STORY lane (`vgai screenshot <file>.stories.tsx`): a project CSF file's
+ * exports rendered in the live session's DOM and captured through the same
+ * composite leg the game lane uses, as ONE variant sheet per file. `story`
+ * narrows to a single export. See `packages/editor/src/story-capture.ts`.
+ */
+export interface StoryCaptureOptions {
+  /** Narrow the sheet to one CSF export name (`--story <export>`). */
+  story?: string;
+  /** Per-variant cell size in CSS pixels; defaults to a 960x540 rectangle,
+   *  because a UI story is not the Asset Lab's square 3D view. */
+  width?: number;
+  height?: number;
+}
+
+export interface StoryVariantImage extends ViewportCapture {
+  /** The CSF export name — the file name each variant PNG is written under. */
+  name: string;
+  /** Storybook's human-facing story name. */
+  label: string;
+}
+
+export interface StoryVariantCapture {
+  /** Project-relative path of the CSF module that was photographed. */
+  modulePath: string;
+  width: number;
+  height: number;
+  variants: StoryVariantImage[];
+  contactSheet: ViewportCapture & { width: number; height: number };
+}
+
+/**
+ * B8.4 — the Asset Lab compare mode (`vgai screenshot <model.glb>
+ * --compare <ref.glb>`): the asset and a caller-supplied reference GLB rendered with
  * matched orthographic front + side framing (equal-height bounding-box
  * normalization, both yaw-normalized to face the camera), scored by
  * silhouette IoU with per-view overlay evidence (orange asset / cyan
@@ -121,7 +210,7 @@ export interface AssetCompareCapture {
 }
 
 /**
- * A project-defined labeled shot set (`vgai asset-preview --shots <set>`).
+ * 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),
@@ -135,6 +224,20 @@ export interface ShotSetPoseRotation {
   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. */
+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. */
+export type ShotSetPoseStep = ShotSetPoseRotation | ShotSetPoseMorph;
+
 export type ShotSetShot =
   | { label: string; view: 'turntable'; yaw: number; pose?: string | undefined }
   | {
@@ -142,6 +245,13 @@ 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. */
+      yaw?: number | undefined;
       pose?: string | undefined;
     };
 
@@ -155,16 +265,37 @@ export interface AssetPreviewShotSetDefinition {
   /** Optional clause appended to rig-requirement errors,
    *  e.g. "a Mixamo-named humanoid skeleton". */
   rigRequirementHint?: string;
-  /** Named poses (bone rotations applied to a disposable snapshot only);
-   *  shots opt in via their `pose` field. */
-  poses?: Record<string, ShotSetPoseRotation[]>;
+  /** Named poses (bone rotations and morph influences applied to a disposable
+   *  snapshot only); shots opt in via their `pose` field. */
+  poses?: Record<string, ShotSetPoseStep[]>;
   shots: ShotSetShot[];
 }
 
+/**
+ * A shot the capture engine rendered but does not vouch for.
+ *
+ * `'empty-frame'` — the shot's frame contained no renderable geometry, so
+ * the PNG is background only. It is reported rather than thrown because one
+ * mis-aimed crop must not kill a 20-shot render; it is reported LOUDLY
+ * because a background tile on a contact sheet otherwise reads as coverage.
+ */
+export interface AssetPreviewShotWarning {
+  label: string;
+  reason: 'empty-frame';
+  /** Already names the shot, its anchor joints and its pose — surfaces print
+   *  this string rather than re-composing one. */
+  message: string;
+  bones?: string[];
+  pose?: string;
+}
+
 export interface LabeledShotSetCapture {
   width: number;
   height: number;
   shots: Array<ViewportCapture & { label: string }>;
+  /** Empty when every shot framed geometry. Absent against an editor that
+   *  predates the empty-frame guard. */
+  warnings: AssetPreviewShotWarning[];
   contactSheet: ViewportCapture & { width: number; height: number };
 }
 
@@ -182,18 +313,29 @@ export interface EditorState {
    */
   loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null;
   /**
-   * R1 (docs/R3F-FOLLOW-THROUGH-SPEC.md) — 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 write-back during play, a registry.ts
-   * edit). The editor's Restart button surfaces the same reason; one restart
-   * (`vgai play`, or the button) remounts every root from fresh source and
-   * clears it. `null` when the running session is fresh; absent against an
-   * older server that predates the field.
+   * The connected editor tab's OWN reported visibility/focus
+   * (`command-listener.ts`'s `collectPresence`, straight off
+   * `document.visibilityState`/`document.hasFocus()`). This is the only field
+   * that distinguishes a usable session from a merely attached one:
+   * `connected` answers "is an SSE client holding the session open", which a
+   * 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.
+   */
+  presence?: { visibility: 'visible' | 'hidden' | 'prerender'; focused: boolean } | 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
+   * write-back during play, a registry.ts edit). The editor's Restart button
+   * surfaces the same reason; one restart (`vgai play`, or the button)
+   * remounts every root from fresh source and clears it. `null` when the
+   * running session is fresh; absent against an older server that predates
+   * the field.
    */
   restartRequired?: string | null;
   selectedEntityId: string | null;
   selectedEntityIds: string[];
-  activeViewportTab: 'scene' | 'game';
+  activeViewportTab: ViewportTab;
   /** The actual active center document, including tool/source documents. */
   activeDocumentId?: string | null;
   activeTabKey: string;
@@ -233,7 +375,8 @@ export interface EditorState {
   stateUpdatedAt?: number;
   /**
    * Validate-on-change (#103): per-file validation status for every
-   * `*.vscn.json`/`*.prefab.json`/`vgai.game.json` the dev server has seen
+   * Project `src/**` source / `vgai.project.json` the dev
+   * server has seen
    * change since it booted (or since the last project switch). Server-
    * computed — unlike the rest of `EditorState`, it is NOT part of the
    * browser-POSTed snapshot, so it is always current. A file appears here
@@ -243,6 +386,32 @@ export interface EditorState {
    * read it unconditionally.
    */
   projectValidation?: Record<string, { errors: string[]; at: number }>;
+  /**
+   * PD-13: the WARNING half of the same server-computed validation pass —
+   * authoring-convention findings (the R3F00x codes, OID surface conflicts)
+   * that do not make a file invalid but do make it unauthorable. Same shape,
+   * same lifecycle and same freshness guarantee as `projectValidation` above:
+   * whole-project (not just the open document), keyed by project-relative
+   * path, present only while the file currently warns, `{}` when clean.
+   *
+   * The server has sent this since the R3F authoring diagnostics landed; it
+   * was missing from this interface, so every typed consumer — `vgai status`
+   * included — could only reach it through a cast. Declared here so a caller
+   * that wants to react to authoring warnings can see they exist.
+   */
+  projectWarnings?: Record<string, { warnings: string[]; at: number }>;
+  /**
+   * PD-14: whether the SOURCE half of the validation pass above is running at
+   * all. `'active'` is the normal state; `'awaiting-src'` means the project
+   * has no `src/` directory yet, so nothing under `src/` is being validated —
+   * an empty `projectValidation`/`projectWarnings` says nothing about source
+   * files while this reads `'awaiting-src'`. It is not terminal: the watcher
+   * is armed on the not-yet-existing path and flips to `'active'` (running
+   * the boot-equivalent scan) the moment `src/` appears, with no restart.
+   * `'no-project'` when no project is open. Server-computed, like its
+   * neighbors above.
+   */
+  sourceValidation?: 'active' | 'awaiting-src' | 'no-project';
   /**
    * #124: the absolute path of the project this editor server currently has
    * open — server-computed (never part of the browser-POSTed snapshot,
@@ -257,7 +426,7 @@ export interface EditorState {
   projectRoot?: string | null;
   /**
    * #124: the open project's declared name, alongside `projectRoot` above
-   * (`vgai.game.json`'s `name`). `null` when no project is open, or the open
+   * (`vgai.project.json`'s `name`). `null` when no project is open, or the open
    * project has no readable manifest name.
    */
   projectName?: string | null;
@@ -366,3 +535,104 @@ export type {
   ProjectToolContribution,
   ToolContributionPoint,
 } from '@vgai/sdk/project-tool-catalog';
+
+// ---------------------------------------------------------------------------
+// Inspection — the serialized inspection subject (`EditorClient.inspect`)
+// ---------------------------------------------------------------------------
+//
+// The wire mirror of the editor's own `SerializedInspectionSubject`
+// (`packages/editor/src/inspection/serialize.ts`, which owns the contract and
+// carries the reasoning). `command-listener.ts` annotates its `inspect`
+// payload with this type, so `tsc` checks the two sides against each other on
+// every build rather than letting them drift silently.
+
+/** Where the inspector's subject lives; `asset-lab` is an open asset
+ *  document — the three paradigm scoped to a subtree, inspected in the same
+ *  box as the scene. */
+export type InspectionSurface = 'three' | 'canvas' | 'dom' | 'asset-lab';
+
+/** Which LAYOUT the one inspector box is in: the compact box over the
+ *  viewport, or the same sections stacked in the dock column. */
+export type InspectionPresentationKind = 'card' | 'column';
+
+/** One inspected field: a stable scriptable `path` and the value at it. */
+export interface InspectedField {
+  path: string;
+  label: string;
+  type: 'string' | 'number' | 'boolean' | 'vec3' | 'color' | 'enum' | 'asset' | 'json';
+  /** Absent when nothing is at that address, or when `mixed` is set. */
+  value?: unknown;
+  /** The inspected subjects disagree about this field. */
+  mixed?: true;
+  /** The value shown is the declared default — the document does not carry it. */
+  defaulted?: boolean;
+  readonly?: boolean;
+  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
+ *  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.
+ *
+ *  A custom body carries `data` when it can say what it DISPLAYS — the keys
+ *  are the section's own vocabulary, not a shared schema. The shipped case is
+ *  `transform`: `{position, rotation, scale}`, three numbers each, with
+ *  rotation in Euler XYZ DEGREES exactly as the rotation inputs show it (the
+ *  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: 'preview'; id: string; title: string };
+
+export interface InspectedSection {
+  id: string;
+  title: string;
+  order: number;
+  description?: string;
+  body: InspectedSectionBody;
+}
+
+/** A verb on the subject (the visibility eye, the Asset Editor jump). */
+export interface InspectedAction {
+  id: string;
+  title: string;
+  label?: string;
+  /** Toggle state, for verbs that have one — how visibility is read. */
+  pressed?: boolean;
+  disabled?: boolean;
+}
+
+/** The whole inspection subject, as data — what a human sees in the
+ *  inspector, for an agent (`vgai eval 'editor.inspect()'`). */
+export interface InspectedSubject {
+  id: string;
+  title: string;
+  kindLabel?: string;
+  /** The quiet line a subject with nothing to edit explains itself with. */
+  hint?: string;
+  presentation: {
+    preferred: InspectionPresentationKind;
+    resolved?: InspectionPresentationKind;
+    surface?: InspectionSurface;
+  };
+  quickActions: readonly InspectedAction[];
+  /** Already in display order. */
+  sections: readonly InspectedSection[];
+}
+
+/** NOTHING is being inspected: the inspector is unmounted, so the honest
+ *  answer is not an empty subject but the absence of one. Distinct from a
+ *  missing reply, which means nobody answered
+ *  (`editor.inspection.get`'s `INSPECTION_UNAVAILABLE`). */
+export interface InspectedNothing {
+  none: true;
+}
+
+/** What `editor.inspect()` answers: the subject showing, or nothing at all.
+ *  Narrow with `'none' in result`. */
+export type InspectedInspection = InspectedSubject | InspectedNothing;