@vgai/editor-sdk 0.4.1 → 0.5.0-canary.20260719.0

package/README.md

@@ -12,7 +12,18 @@ to the caller.
 import { EditorClient } from '@vgai/editor-sdk';
 
 const editor = new EditorClient(); // default http://localhost:5173
+const projectEditor = new EditorClient({ url: 'http://localhost:25786' });
 await editor.play();
+
+// Present the same editor subject/view to the connected human and get a
+// compact share URL. This does not serialize document contents or layout.
+const shown = await editor.present({
+  version: 1,
+  document: { kind: 'tool', id: 'walking-castle-builder' },
+  viewport: { camera: 'isometric', frame: 'document' },
+  utility: 'profiler',
+});
+console.log(shown.url);
 await editor.waitForState((s) => s.playState === 'playing');
 const entries = await editor.getLogEntries(); // proves frames actually ran
 ```
@@ -22,14 +33,15 @@ const entries = await editor.getLogEntries(); // proves frames actually ran
 One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
 `AssetKind`, `ShadingMode`, ...). Methods, by group:
 
-- Play control: `play`, `stop`, `pause`, `resume`, `step`
+- Play control: `play`, `restart`, `stop`, `pause`, `resume`, `step`
 - Selection: `select(id | null)`, `selectMultiple`, `selectAll`
 - Viewport: `focusEntity`, `focusSelection`, `viewPreset`, `setCamera`,
   `captureViewport`
 - Asset preview: `captureAssetPreview` for deterministic front, right, top,
   and three-quarter captures of a project model or authored entity hierarchy
 - Panels: `showViewport('scene'|'game')`, `showInspector`, `openAsset`,
-  `closeAsset`, `toggleConsole`, `toggleCommandPalette`, `showBuild`
+  `closeAsset`, `toggleConsole`, `toggleCommandPalette`, `showBuild`, and
+  `present(EditorView)` for an atomic human-visible view plus share URL
 - Display: `setGrid`, `setHelpers`, `setStats`, `setShadingMode` (`solid`,
   `unlit`, `wireframe`, `normals`, or `overdraw`), `setHelperType` (including
   the independent `bounds` category). Shading targets the active Scene/Game
@@ -54,11 +66,12 @@ registered tool and an already-configured client:
 import { Button } from '@editor/widgets';
 import type { ToolContributionProps } from '@vgai/editor-sdk/contributions';
 
-export default function MapBuilder({ tool, client }: ToolContributionProps) {
+export default function MapBuilder({ tool, client, account }: ToolContributionProps) {
   return (
     <Button
       variant="solid"
       onClick={() => void client.runProjectTool(tool.name, { seed: 42 }, { confirm: true })}
+      title={`Default execution: ${account.preferredRoute}`}
     >
       Build map
     </Button>
@@ -66,16 +79,71 @@ export default function MapBuilder({ tool, client }: ToolContributionProps) {
 }
 ```
 
-The package registration chooses `workspace.document`, `workspace.utility`, or
-`selection.inspector`. Inspector contributions additionally receive
-`node`/`nodeId` and export `match(node, adapter)`. There is no extension class,
-lifecycle, or proprietary UI description.
+The package registration chooses `workspace.document`, `workspace.utility`,
+`selection.inspector`, `asset.inspector`, or `generation.result`. Selection
+Inspector contributions receive `node`/`nodeId` and export
+`match(node, adapter)`; asset Inspector contributions receive `asset` and
+export `match(asset)`. A generation-result contribution receives the durable
+job and raw native poll result inside the editor-owned result document and
+must export `match(job, result)`; registration order never selects a renderer.
+All contributions receive `account`, a validated global projection containing
+plan, credits, spend policy, and provider-specific route availability. It never
+contains an access token. There is no extension class, lifecycle, or
+proprietary UI description.
 
 Use ordinary React/CSS for composition and `@editor/widgets` for controls.
 Shape the UI for its contribution point: a bounded workspace for documents, a
 dense single column for inspector sections, and a compact row/status block for
 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`:
+`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
+editor, never silent fake output.
+
+1. **Editor panels** — `workspace.document` / `workspace.utility` tool
+   contributions (previous section). Panels join the Dockview workspace;
+   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
+   `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.
+
 ### Asset Lab capture
 
 `captureAssetPreview` accepts exactly one source: an authored entity hierarchy
@@ -100,12 +168,12 @@ buffers and images must resolve on the same project origin. The thin CLI
 equivalent writes the four views and contact sheet to disk:
 
 ```bash
-vgai asset-preview --asset /models/storefront.glb --out artifacts/storefront
+npm run vgai -- asset-preview --asset /models/storefront.glb --out artifacts/storefront
 ```
 
 ## Limitations
 
 - The published package exports raw TypeScript (`exports: "./src/index.ts"`),
   so consumers need a TypeScript-aware runner/bundler such as tsx or Vite.
-- Requires the editor dev server (`npm run dev` or `vgai edit`); there is no
+- Requires the editor dev server (`npm run dev` or `npx @vgai/cli@latest edit <project>`); there is no
   offline mode.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.1",
+  "version": "0.5.0-canary.20260719.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,6 +17,15 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./contributions": "./src/contributions.ts"
+    "./contributions": "./src/contributions.ts",
+    "./extension": "./src/extension.ts"
+  },
+  "dependencies": {
+    "@types/three": "^0.180.0",
+    "@vgai/sdk": "0.5.0-canary.20260719.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "three": "^0.180.0"
   }
 }

package/src/client.ts

@@ -1,11 +1,16 @@
+import type { GenerationJobsDocument } from '@vgai/sdk/generations';
 import type {
+  ActiveDocumentCapture,
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
   AssetPreviewSource,
   EditorState,
+  EditorView,
   GameCapture,
   HelperVisibility,
+  HumanoidShotSetCapture,
+  PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
   ProjectToolCatalog,
@@ -25,6 +30,17 @@ export class EditorClient {
   private readonly baseUrl: string;
 
   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("...").',
+      );
+    }
+    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.`,
+      );
+    }
     this.baseUrl = (opts?.url ?? DEFAULT_URL).replace(/\/$/, '');
   }
 
@@ -54,6 +70,11 @@ export class EditorClient {
     await this.command({ type: 'play', ...(opts?.seed !== undefined ? { seed: opts.seed } : {}) });
   }
 
+  /** Dispose the current play session and mount it again from fresh project entry source. */
+  async restart(): Promise<void> {
+    await this.command({ type: 'play' });
+  }
+
   async stop(): Promise<void> {
     await this.command({ type: 'stop' });
   }
@@ -118,7 +139,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/probe`'s `RelayTransport.screenshot` (and therefore
+   * `@vgai/e2e`'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,
@@ -166,6 +187,33 @@ export class EditorClient {
     };
   }
 
+  /**
+   * B7.6 — the canonical humanoid verify shot set (`vgai asset-preview
+   * --shots humanoid`): four turntable angles, tight zooms on the
+   * historical seam sites (head/hands/feet/shoulder), and a deep-bend pose
+   * pair, all framed by the editor from the loaded GLB's OWN skeleton — see
+   * `packages/editor/src/asset-preview.ts`'s `captureHumanoidShotSetAssetPreview`.
+   * Throws (via `command`'s `{ok:false}` unwrap) with a clear message naming
+   * the missing joint(s) when the asset has no Mixamo-named skeleton.
+   */
+  async captureHumanoidShotSetPreview(
+    source: AssetPreviewSource,
+    options: AssetPreviewOptions = {},
+  ): Promise<HumanoidShotSetCapture> {
+    const data = await this.command<HumanoidShotSetCapture>({
+      type: 'capture-asset-preview',
+      ...source,
+      ...options,
+      shots: 'humanoid',
+    });
+    return {
+      width: data.width,
+      height: data.height,
+      shots: data.shots,
+      contactSheet: data.contactSheet,
+    };
+  }
+
   // --- Panels ---
 
   async showViewport(tab: 'scene' | 'game'): Promise<void> {
@@ -196,6 +244,26 @@ export class EditorClient {
     await this.command({ type: 'show-build' });
   }
 
+  /** Atomically present a durable editor view and return its shareable URL. */
+  async present(view: EditorView): Promise<PresentedEditorView> {
+    const presented = await this.command<PresentedEditorView>({ type: 'present-view', view });
+    return { view: presented.view, url: presented.url, warnings: presented.warnings };
+  }
+
+  /** Read the editor's actual current durable projection. */
+  async currentView(): Promise<EditorView> {
+    const data = await this.command<{ view: EditorView }>({ type: 'current-view' });
+    return data.view;
+  }
+
+  /** Capture the active center document exactly as presented to the user. */
+  async captureActiveDocument(size?: number): Promise<ActiveDocumentCapture> {
+    return this.command<ActiveDocumentCapture>({
+      type: 'capture-active-document',
+      ...(size === undefined ? {} : { size }),
+    });
+  }
+
   // --- Display (set semantics) ---
 
   async setGrid(enabled: boolean): Promise<void> {
@@ -315,6 +383,26 @@ export class EditorClient {
     return body;
   }
 
+  // --- First-party generation job activity ---
+
+  /** Read the one project-local generation job ledger. Provider-native
+   * request/result shapes remain on their registered operations. */
+  async listGenerationJobs(): Promise<GenerationJobsDocument> {
+    const res = await fetch(`${this.baseUrl}/__editor/generations`);
+    if (!res.ok) throw new Error(`Failed to list generation jobs: ${res.status}`);
+    return (await res.json()) as GenerationJobsDocument;
+  }
+
+  /** Forget operational job state. Accepted provenance and project assets
+   * are deliberately unaffected. */
+  async forgetGenerationJob(id: string): Promise<boolean> {
+    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;
+  }
+
   // --- Logs ---
 
   async getLogEntries(): Promise<

package/src/contributions.ts

@@ -4,6 +4,16 @@
  * metadata names a module and the editor renders its default export.
  */
 
+import type { GenerationAccountProjection } from '@vgai/sdk/account';
+import type { GenerationJob } from '@vgai/sdk/generations';
+import type {
+  AnimationClip,
+  Camera,
+  ColorRepresentation,
+  Object3D,
+  Scene,
+  WebGLRenderer,
+} from 'three';
 import type { EditorClient } from './client.js';
 import type { ProjectToolCatalogEntry } from './types.js';
 
@@ -19,11 +29,122 @@ export interface ToolContributionNode {
   readonly flags: object;
 }
 
+/**
+ * One disposable native Three.js build supplied to the editor's generic
+ * preview surface. This is a host-lifetime boundary, not a model format or
+ * procedural-asset base class: project code still constructs ordinary
+ * Object3D and AnimationClip instances directly.
+ */
+export interface ToolObject3DPreviewSource {
+  readonly root: Object3D;
+  readonly animations?: readonly AnimationClip[];
+  dispose(): void;
+}
+
+/** Direct native handles for optional project-owned preview presentation. */
+export interface ToolObject3DPreviewContext {
+  readonly scene: Scene;
+  readonly camera: Camera;
+  readonly renderer: WebGLRenderer;
+  /**
+   * A cloned Object3D graph, never the source root itself. Geometry,
+   * materials, and textures are shared read-only with the disposable source;
+   * clone a resource before applying preview-only mutations to it.
+   */
+  readonly model: Object3D;
+}
+
+export interface ToolObject3DPreviewExtension {
+  /** When present, replaces the viewer's default render call for this frame. */
+  render?(deltaSeconds: number): void;
+  /** Resize project-owned composers and render targets with the host viewport. */
+  resize?(width: number, height: number, pixelRatio: number): void;
+  /** Release every light, ground mesh, pass, target, and listener added here. */
+  dispose(): void;
+}
+
+export interface ToolObject3DPreviewProps {
+  /** Build a fresh source. The host disposes it after its preview snapshot. */
+  readonly build: () => ToolObject3DPreviewSource;
+  readonly displayName?: string;
+  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;
+  /** Host studio lights. Defaults off with setupPreview, on otherwise. */
+  readonly useDefaultLighting?: boolean;
+  /** Explicit renderer exposure. Custom presentation otherwise owns it. */
+  readonly exposure?: number;
+  /**
+   * Optional raw Three.js presentation hook for project-specific lights,
+   * ground, or postprocessing. Host grid/studio lights default off when this
+   * is present. It is preview chrome and is never exported.
+   */
+  readonly setupPreview?: (
+    context: ToolObject3DPreviewContext,
+  ) => ToolObject3DPreviewExtension | undefined;
+  readonly active?: boolean;
+}
+
+/**
+ * A native source graph hosted by the editor's normal Three.js authoring
+ * viewport, hierarchy, selection, and Inspector. Unlike Object3DPreview this
+ * surface exposes the live graph as the active workspace document context.
+ */
+export interface ToolObject3DAuthoringProps {
+  readonly documentId: string;
+  readonly sourcePath: string;
+  readonly build: () => ToolObject3DPreviewSource;
+  readonly displayName?: string;
+  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
+   * checksum-guarded write and records it in the canonical project history.
+   * Without this binding the animation workspace remains honestly read-only.
+   */
+  readonly animationSource?: ToolAnimationSourceBinding;
+  readonly active?: boolean;
+}
+
+export interface ToolAnimationSourceBinding {
+  /** Project-relative TypeScript file below src/. */
+  readonly path: string;
+  /** Undo/redo label shown by the editor history. */
+  readonly label?: string;
+  /**
+   * Serialize the same native clips returned by build into project-owned source.
+   * The source loader must accept replacement typed arrays when key counts change.
+   */
+  readonly serialize: (animations: readonly AnimationClip[]) => string;
+}
+
+/** Editor-owned native surfaces available to ordinary project React tools. */
+export interface ToolContributionSurfaces {
+  readonly Object3DPreview: import('react').ComponentType<ToolObject3DPreviewProps>;
+  readonly Object3DAuthoring: import('react').ComponentType<ToolObject3DAuthoringProps>;
+}
+
 export interface ToolContributionProps {
   /** The exact registered callable this contribution presents. */
   readonly tool: ProjectToolCatalogEntry;
+  /** Stable id of this presentation within the registered callable. */
+  readonly contributionId?: string;
   /** Direct editor SDK client; invoke with `client.runProjectTool(tool.name, ...)`. */
   readonly client: EditorClient;
+  /** Generic editor-owned presentation surfaces; project source remains native. */
+  readonly surfaces: ToolContributionSurfaces;
+  /** Sanitized product-account projection. Never contains an access token. */
+  readonly account: GenerationAccountProjection;
+  /** Present when mounted as a workspace document contribution. */
+  readonly documentId?: string;
+  /** Whether that workspace document is the active center subject. */
+  readonly active?: boolean;
 }
 
 export interface ToolInspectorContributionProps extends ToolContributionProps {
@@ -31,6 +152,43 @@ export interface ToolInspectorContributionProps extends ToolContributionProps {
   readonly nodeId: string | null;
 }
 
+/** Stable editor projection of one selected project or external-library asset. */
+export interface ToolContributionAsset {
+  readonly path: string;
+  readonly name: string;
+  readonly kind: string;
+  readonly origin: 'project' | 'library';
+  readonly sourcePath?: string;
+}
+
+export interface ToolAssetInspectorContributionProps extends ToolContributionProps {
+  readonly asset: ToolContributionAsset | null;
+}
+
+/** Optional named export required by `asset.inspector` contributions. */
+export type ToolAssetInspectorContributionMatch = (asset: ToolContributionAsset | null) => boolean;
+
+/**
+ * Provider-owned presentation mounted inside the editor-owned generation
+ * result document. The host owns job state, billing, and acceptance; this
+ * component only interprets the native poll result.
+ */
+export interface ToolGenerationResultContributionProps extends ToolContributionProps {
+  readonly job: GenerationJob;
+  readonly result: unknown;
+}
+
+/**
+ * Required named export for `generation.result` contributions. A single poll
+ * callable may serve many native operations, so presentation selection is
+ * based on the durable job and the provider's unmodified poll result rather
+ * than registration order or a host-owned media taxonomy.
+ */
+export type ToolGenerationResultContributionMatch = (
+  job: GenerationJob,
+  result: unknown,
+) => boolean;
+
 /** Optional named export required by `selection.inspector` contributions. */
 export type ToolInspectorContributionMatch = (
   node: ToolContributionNode | null,

package/src/editor-view.ts

@@ -0,0 +1,223 @@
+import type { AssetKind, EditorCameraState, EditorView, ViewPreset } from './types.js';
+
+const PREFIX = 'view.';
+const MAX_QUERY_LENGTH = 4096;
+const ASSET_KINDS = new Set<AssetKind>([
+  'model',
+  'image',
+  'audio',
+  'animation',
+  'json',
+  'scene',
+  'prefab',
+  'material',
+]);
+const CAMERAS = new Set<ViewPreset | 'isometric'>([
+  'top',
+  'front',
+  'right',
+  'perspective',
+  'isometric',
+]);
+type EditorViewDiagnostic = NonNullable<NonNullable<EditorView['viewport']>['diagnostic']>;
+type EditorViewUtility = NonNullable<EditorView['utility']>;
+const DIAGNOSTICS = new Set<EditorViewDiagnostic>([
+  'solid',
+  'unlit',
+  'wireframe',
+  'normals',
+  'overdraw',
+  'uv',
+  'vertex-colors',
+  'bounds',
+  'skeleton',
+]);
+const UTILITIES = new Set<EditorViewUtility>(['profiler', 'console', 'animation', 'debugger']);
+
+function nonEmpty(value: string | null): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function writeDocument(params: URLSearchParams, document: EditorView['document']): void {
+  if (!document) return;
+  params.set(`${PREFIX}docKind`, document.kind);
+  if (document.kind === 'asset' && document.entityId) {
+    params.set(`${PREFIX}doc`, document.entityId);
+    params.set(`${PREFIX}assetSource`, 'entity');
+  } else if (document.kind === 'asset') {
+    params.set(`${PREFIX}doc`, document.path!);
+  } else if (document.kind === 'scene' || document.kind === 'data') {
+    params.set(`${PREFIX}doc`, document.path);
+  } else if (document.kind === 'story') {
+    params.set(`${PREFIX}doc`, document.modulePath);
+    params.set(`${PREFIX}story`, document.storyName);
+    if (document.mode === 'docs') params.set(`${PREFIX}storyMode`, 'docs');
+  } else if (document.kind === 'project-tool') {
+    params.set(`${PREFIX}doc`, document.name);
+  } else {
+    params.set(`${PREFIX}doc`, document.id);
+  }
+  if (document.kind === 'asset' && document.assetKind) {
+    params.set(`${PREFIX}assetKind`, document.assetKind);
+  }
+}
+
+function writeViewport(params: URLSearchParams, viewport: EditorView['viewport']): void {
+  if (!viewport) return;
+  if (typeof viewport.camera === 'string') params.set(`${PREFIX}camera`, viewport.camera);
+  else if (viewport.camera) {
+    params.set(`${PREFIX}camera`, 'pose');
+    params.set(
+      `${PREFIX}cameraPosition`,
+      [viewport.camera.position.x, viewport.camera.position.y, viewport.camera.position.z].join(
+        ',',
+      ),
+    );
+    params.set(
+      `${PREFIX}cameraTarget`,
+      [viewport.camera.target.x, viewport.camera.target.y, viewport.camera.target.z].join(','),
+    );
+    if (viewport.camera.fov !== undefined)
+      params.set(`${PREFIX}cameraFov`, String(viewport.camera.fov));
+  }
+  if (viewport.diagnostic) params.set(`${PREFIX}diagnostic`, viewport.diagnostic);
+  if (viewport.frame) params.set(`${PREFIX}frame`, viewport.frame);
+  if (viewport.grid !== undefined) params.set(`${PREFIX}grid`, viewport.grid ? '1' : '0');
+}
+
+function parseVec3(value: string | null): EditorCameraState['position'] | null {
+  if (!value) return null;
+  const parts = value.split(',').map(Number);
+  if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) return null;
+  return { x: parts[0]!, y: parts[1]!, z: parts[2]! };
+}
+
+function parseCamera(params: URLSearchParams): NonNullable<EditorView['viewport']>['camera'] {
+  const camera = params.get(`${PREFIX}camera`);
+  if (camera && CAMERAS.has(camera as ViewPreset | 'isometric')) {
+    return camera as ViewPreset | 'isometric';
+  }
+  if (camera !== 'pose') return undefined;
+  const position = parseVec3(params.get(`${PREFIX}cameraPosition`));
+  const target = parseVec3(params.get(`${PREFIX}cameraTarget`));
+  const fovValue = params.get(`${PREFIX}cameraFov`);
+  const fov = fovValue === null ? undefined : Number(fovValue);
+  if (!position || !target || (fov !== undefined && !Number.isFinite(fov))) return undefined;
+  return { position, target, ...(fov !== undefined ? { fov } : {}) };
+}
+
+function parseStoryDocument(params: URLSearchParams, modulePath: string): EditorView['document'] {
+  const storyName = nonEmpty(params.get(`${PREFIX}story`));
+  if (!storyName) return undefined;
+  return {
+    kind: 'story',
+    modulePath,
+    storyName,
+    ...(params.get(`${PREFIX}storyMode`) === 'docs' ? { mode: 'docs' as const } : {}),
+  };
+}
+
+function parseAssetDocument(params: URLSearchParams, value: string): EditorView['document'] {
+  const assetKind = params.get(`${PREFIX}assetKind`);
+  if (params.get(`${PREFIX}assetSource`) === 'entity') {
+    return { kind: 'asset', entityId: value, assetKind: 'model' };
+  }
+  return {
+    kind: 'asset',
+    path: value,
+    ...(assetKind && ASSET_KINDS.has(assetKind as AssetKind)
+      ? { assetKind: assetKind as AssetKind }
+      : {}),
+  };
+}
+
+function parseDocument(params: URLSearchParams): EditorView['document'] {
+  const kind = params.get(`${PREFIX}docKind`);
+  const value = nonEmpty(params.get(`${PREFIX}doc`));
+  if (!value) return undefined;
+  if (kind === 'scene') return { kind, path: value };
+  if (kind === 'tool') return { kind, id: value };
+  if (kind === 'world') return { kind, id: value };
+  if (kind === 'data') return { kind, path: value };
+  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:data-assets',
+      'workspace:build-profiles',
+      'account',
+      'project-tools',
+    ].includes(value)
+  ) {
+    return {
+      kind,
+      id: value as Extract<NonNullable<EditorView['document']>, { kind: 'workspace' }>['id'],
+    };
+  }
+  return kind === 'asset' ? parseAssetDocument(params, value) : undefined;
+}
+
+function parseViewport(params: URLSearchParams): EditorView['viewport'] {
+  const camera = parseCamera(params);
+  const diagnostic = params.get(`${PREFIX}diagnostic`);
+  const frame = params.get(`${PREFIX}frame`);
+  const grid = params.get(`${PREFIX}grid`);
+  const viewport = {
+    ...(camera ? { camera } : {}),
+    ...(diagnostic && DIAGNOSTICS.has(diagnostic as EditorViewDiagnostic)
+      ? { diagnostic: diagnostic as EditorViewDiagnostic }
+      : {}),
+    ...(frame === 'document' || frame === 'selection'
+      ? { frame: frame as 'document' | 'selection' }
+      : {}),
+    ...(grid === '0' || grid === '1' ? { grid: grid === '1' } : {}),
+  };
+  return Object.keys(viewport).length > 0 ? viewport : undefined;
+}
+
+/** Apply only the view-owned query parameters, preserving project/scene routing params. */
+export function editorViewUrl(view: EditorView, baseUrl: string | URL): string {
+  const url = new URL(baseUrl);
+  for (const key of [...url.searchParams.keys()]) {
+    if (key.startsWith(PREFIX)) url.searchParams.delete(key);
+  }
+  url.searchParams.set(`${PREFIX}v`, '1');
+  writeDocument(url.searchParams, view.document);
+  if (view.selection?.ids.length) {
+    for (const id of view.selection.ids) url.searchParams.append(`${PREFIX}select`, id);
+    if (view.selection.focus) url.searchParams.set(`${PREFIX}focus`, '1');
+  }
+  writeViewport(url.searchParams, view.viewport);
+  if (view.utility) url.searchParams.set(`${PREFIX}utility`, view.utility);
+  if (url.search.length > MAX_QUERY_LENGTH) {
+    throw new Error(`Editor view URL exceeds the ${MAX_QUERY_LENGTH}-character share limit.`);
+  }
+  return url.toString();
+}
+
+/** Parse a shareable editor projection. Malformed projections are ignored at boot. */
+export function editorViewFromUrl(value: string | URL): EditorView | null {
+  const url = value instanceof URL ? value : new URL(value, 'http://editor.invalid');
+  const params = url.searchParams;
+  if (params.get(`${PREFIX}v`) !== '1') return null;
+  const view: EditorView = { version: 1 };
+  const document = parseDocument(params);
+  if (document) view.document = document;
+  const ids = params
+    .getAll(`${PREFIX}select`)
+    .filter((id) => id.length > 0)
+    .slice(0, 32);
+  if (ids.length) view.selection = { ids, focus: params.get(`${PREFIX}focus`) === '1' };
+  const viewport = parseViewport(params);
+  if (viewport) view.viewport = viewport;
+  const utility = params.get(`${PREFIX}utility`);
+  if (utility && UTILITIES.has(utility as EditorViewUtility)) {
+    view.utility = utility as EditorViewUtility;
+  }
+  return view;
+}

package/src/extension.ts

@@ -0,0 +1,109 @@
+/**
+ * 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) **Editor panels** — registered into the Dockview workspace as documents
+ *     or utilities via a tool contribution (`package.json#vgai.tools` →
+ *     `contributes: [{ point: 'workspace.document' | 'workspace.utility' }]`).
+ *     Types: `ToolContributionProps` in `@vgai/editor-sdk/contributions`.
+ *     Panels are never a parallel rail — Dockview owns all layout.
+ * (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, …)
+ *     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
+ *     engine already publishes that seam and every consumer of it also
+ *     imports the engine — an alias would be a dead surface.
+ *
+ * Degradation ladder (the anti-shim rule, as API): every contribution
+ * resolves to a {@link ExtensionContributionTier} —
+ *
+ * - `'active'` — the contribution loaded and produced its surface.
+ * - `'absent'` — nothing was contributed. The editor HIDES the surface
+ *   entirely; it never fabricates placeholder data for a missing
+ *   contribution.
+ * - `'failed'` — the contribution exists but threw / violated the contract.
+ *   The failure is contained per-contribution (the editor never crashes),
+ *   the surface is hidden, and the error is reported LOUDLY (editor
+ *   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

@@ -1,11 +1,29 @@
+export type {
+  GenerationBilling,
+  GenerationJob,
+  GenerationJobStatus,
+  GenerationJobsDocument,
+} from '@vgai/sdk/generations';
 export { EditorClient } from './client.js';
 export type {
+  ToolAssetInspectorContributionMatch,
+  ToolAssetInspectorContributionProps,
+  ToolContributionAsset,
   ToolContributionNode,
   ToolContributionProps,
+  ToolGenerationResultContributionProps,
   ToolInspectorContributionMatch,
   ToolInspectorContributionProps,
 } from './contributions.js';
+export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
+export type {
+  ComponentGizmoContext,
+  ComponentGizmoHook,
+  ComponentGizmoStatus,
+  ExtensionContributionTier,
+} from './extension.js';
 export type {
+  ActiveDocumentCapture,
   AssetKind,
   AssetPreviewBackground,
   AssetPreviewCapture,
@@ -15,8 +33,13 @@ export type {
   EditorCameraState,
   EditorEntitySummary,
   EditorState,
+  EditorView,
+  EditorViewDocument,
   GameCapture,
   HelperVisibility,
+  HumanoidShotLabel,
+  HumanoidShotSetCapture,
+  PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
   ProjectToolCatalog,
@@ -31,3 +54,4 @@ export type {
   ViewPreset,
   ViewportCapture,
 } from './types.js';
+export { HUMANOID_SHOT_LABELS } from './types.js';

package/src/types.ts

@@ -13,10 +13,14 @@ export interface HelperVisibility {
   lights: boolean;
   cameras: boolean;
   colliders: boolean;
+  joints: boolean;
+  lod: boolean;
   audio: boolean;
   splines: boolean;
   navmesh: boolean;
   skeletons: boolean;
+  /** Per-component gizmo contributions (W3a extension contract). */
+  components: boolean;
 }
 
 export interface Vec3Value {
@@ -84,6 +88,33 @@ export interface AssetPreviewCapture {
   contactSheet: ViewportCapture & { width: number; height: number };
 }
 
+/**
+ * B7.6 — the canonical humanoid verify shot set (`vgai asset-preview --shots
+ * humanoid`): four turntable angles, tight zooms on the historical seam
+ * sites (head/hands/feet/shoulder), and a deep-bend pose pair, all framed
+ * from the loaded GLB's OWN skeleton (see `packages/editor/src/asset-preview.ts`).
+ */
+export const HUMANOID_SHOT_LABELS = [
+  'front',
+  'back',
+  'left',
+  'right',
+  'zoom-head',
+  'zoom-hands',
+  'zoom-feet',
+  'zoom-shoulder',
+  'bend-front',
+  'bend-quarter',
+] as const;
+export type HumanoidShotLabel = (typeof HUMANOID_SHOT_LABELS)[number];
+
+export interface HumanoidShotSetCapture {
+  width: number;
+  height: number;
+  shots: Array<ViewportCapture & { label: HumanoidShotLabel }>;
+  contactSheet: ViewportCapture & { width: number; height: number };
+}
+
 export interface EditorState {
   playState: 'stopped' | 'playing' | 'paused';
   /**
@@ -97,9 +128,21 @@ export interface EditorState {
    * or against an older server that predates this field.
    */
   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.
+   */
+  restartRequired?: string | null;
   selectedEntityId: string | null;
   selectedEntityIds: string[];
   activeViewportTab: 'scene' | 'game';
+  /** The actual active center document, including tool/source documents. */
+  activeDocumentId?: string | null;
   activeTabKey: string;
   showGrid: boolean;
   showHelpers: boolean;
@@ -172,6 +215,69 @@ export type ShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdra
 export type TransformMode = 'translate' | 'rotate' | 'scale';
 export type TransformSpace = 'world' | 'local';
 
+/**
+ * A durable, intentionally small projection of what an editor is presenting.
+ * This is not workspace persistence: panel sizes, transient tool state, and
+ * authored document contents remain outside the URL.
+ */
+export type EditorViewDocument =
+  | { kind: 'scene'; path: string }
+  | { kind: 'asset'; path: string; entityId?: never; assetKind?: AssetKind }
+  | { kind: 'asset'; entityId: string; path?: never; assetKind?: 'model' }
+  | { kind: 'tool'; id: string }
+  | { kind: 'world'; id: string }
+  | { kind: 'story'; modulePath: string; storyName: string; mode?: 'preview' | 'docs' }
+  | { kind: 'data'; path: string }
+  | { kind: 'project-tool'; name: string }
+  | { kind: 'generation'; id: string }
+  | {
+      kind: 'workspace';
+      id:
+        | 'workspace:scene'
+        | 'workspace:game'
+        | 'workspace:data-assets'
+        | 'workspace:build-profiles'
+        | 'account'
+        | 'project-tools';
+    };
+
+export interface EditorView {
+  version: 1;
+  document?: EditorViewDocument;
+  selection?: { ids: string[]; focus?: boolean };
+  viewport?: {
+    camera?: ViewPreset | 'isometric' | EditorCameraState;
+    diagnostic?: ShadingMode | 'uv' | 'vertex-colors' | 'bounds' | 'skeleton';
+    frame?: 'document' | 'selection';
+    grid?: boolean;
+  };
+  utility?: 'profiler' | 'console' | 'animation' | 'debugger';
+}
+
+export interface PresentedEditorView {
+  view: EditorView;
+  /** Shareable URL for the durable projection that was applied. */
+  url: string;
+  /** Honest degradations; an unsupported requested view is never silent. */
+  warnings: string[];
+}
+
+/** The pixels of the active center document, with enough provenance for an
+ * agent to prove which user-visible subject it captured. Editor chrome is
+ * deliberately excluded. */
+export interface ActiveDocumentCapture extends ViewportCapture {
+  document: {
+    id: string;
+    title: string;
+    kind: string;
+    sourcePath?: string;
+    rootId?: string;
+  };
+  view: EditorView;
+  source: 'scene-viewport' | 'game-composite' | 'object3d-document' | 'document-composite';
+  layers?: { canvases: number; domOverlays: number };
+}
+
 /** Template ids accepted by the editor's create-project endpoint. */
 export type ProjectTemplate = 'default' | '2d' | 'react' | 'example';
 
@@ -187,43 +293,8 @@ export interface RecentProject {
   thumbnail?: string;
 }
 
-export interface ProjectToolCatalogEntry {
-  name: string;
-  summary: string;
-  description: string;
-  sourcePath: string;
-  inputSchema: unknown;
-  resultSchema: unknown;
-  errors: Array<{ code: string; summary: string; dataSchema?: unknown }>;
-  requires: Record<string, boolean | undefined>;
-  host: 'node' | 'editor-browser' | 'runtime-page';
-  mutates: boolean;
-  supportsDryRun: boolean;
-  longRunning: boolean;
-  permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
-  contributions: ProjectToolContribution[];
-}
-
-export type ToolContributionPoint =
-  | 'workspace.document'
-  | 'selection.inspector'
-  | 'workspace.utility';
-
-export interface ProjectToolContribution {
-  id: string;
-  point: ToolContributionPoint;
-  title: string;
-  /** Project-relative or package-absolute browser module path. */
-  entryPath: string;
-}
-
-export interface ProjectToolCatalog {
-  tools: ProjectToolCatalogEntry[];
-  loadErrors: Array<{ sourcePath: string; message: string }>;
-}
-
 export type ProjectToolOutcome =
-  | { ok: true; data: unknown }
+  | { ok: true; data: unknown; generation?: GenerationJob; generationWarning?: string }
   | {
       ok: false;
       error: {
@@ -233,3 +304,12 @@ export type ProjectToolOutcome =
         issues?: Array<{ path?: PropertyKey[]; message?: string; [key: string]: unknown }>;
       };
     };
+
+import type { GenerationJob } from '@vgai/sdk/generations';
+
+export type {
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolContribution,
+  ToolContributionPoint,
+} from '@vgai/sdk/project-tool-catalog';