@vgai/sdk 0.4.0-canary.20260715.0

package/src/cinematic/theatre-operations.ts

@@ -0,0 +1,306 @@
+/**
+ * `cinematic.project.list` / `cinematic.sheet.list` / `cinematic.sequence.inspect`
+ * (B5, §8 B5 "list Theatre projects/sheets", "inspect sequence length and objects").
+ *
+ * STATIC, file-native ops (host: 'node') — they read the COMMITTED Theatre
+ * project-state JSON directly off disk, exactly like B2's
+ * `project.theatre.discover`/`project.theatre.validate`
+ * (`../project/discovery-operations.ts`), which they deliberately reuse
+ * (`listProjectFiles`) rather than duplicate. The key difference from B2's
+ * `project.*` versions: `cinematic.*` targets "a controlled render runtime"
+ * (§5.7), which in practice is very often NOT inside a vgai game project at
+ * all — the committed reference fixtures this unit proves against
+ * (`packages/engine/e2e/{reference,render}-cinematic/theatre-project.json`)
+ * are engine e2e fixtures with no `vgai.game.json` anywhere above them. So
+ * these ops take an explicit `root` (falling back to `ctx.projectRoot` when
+ * omitted) rather than being HARD-confined to `ctx.projectRoot` the way
+ * `project.*` ops are — there is deliberately no `PATH_OUTSIDE_PROJECT`-style
+ * confinement here; `cinematic.render`'s own `entry`/`out` fields have the
+ * same unconfined shape (arbitrary filesystem paths), for the same reason.
+ *
+ * `sheetsById`'s outer shape is validated the same "shape-only" way B2's
+ * `project.theatre.validate` does (§3.2/§5.3: Theatre's internal per-track
+ * keyframe format is a real, versioned, proprietary format this repo does
+ * not own) — PLUS one layer deeper into `sequence` (`length`,
+ * `subUnitsPerUnit`, `tracksByObject`'s KEYS), which is exactly the "sequence
+ * length and objects" the B5 AC asks for and nothing past that (never a
+ * single keyframe/track's internal content).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { listProjectFiles } from '../project/shared.js';
+import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import type { OperationContext } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Shared path resolution: `root` (explicit) > `ctx.projectRoot` (fallback).
+// ---------------------------------------------------------------------------
+
+export const NO_ROOT_ERROR: ErrorDefinition = {
+  code: 'NO_ROOT',
+  summary: 'Neither an explicit `root` input nor ctx.projectRoot was given.',
+  data: z.object({}).describe('No additional data.'),
+};
+
+export const THEATRE_FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'FILE_NOT_FOUND',
+  summary: 'The referenced Theatre project-state file does not exist on disk.',
+  data: z.object({ path: z.string() }),
+};
+
+export const INVALID_THEATRE_PROJECT_ERROR: ErrorDefinition = {
+  code: 'INVALID_THEATRE_PROJECT',
+  summary:
+    "The file's outer shape (sheetsById/definitionVersion/revisionHistory, and — for " +
+    'sequence.inspect — sheetsById[sheet].sequence) does not match Theatre project state.',
+  data: z.object({ issues: z.array(z.string()) }),
+};
+
+export const SHEET_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'SHEET_NOT_FOUND',
+  summary: 'No sheet with the given name exists in this Theatre project’s sheetsById.',
+  data: z.object({ sheetName: z.string(), availableSheets: z.array(z.string()) }),
+};
+
+/** Resolve `root` input against `ctx.projectRoot`, requiring at least one. */
+function resolveRoot(root: string | undefined, ctx: OperationContext): string {
+  const resolved = root ?? ctx.projectRoot;
+  if (!resolved) {
+    throw new OperationError(
+      'NO_ROOT',
+      'Neither an explicit `root` input nor ctx.projectRoot was given.',
+      {},
+    );
+  }
+  return resolved;
+}
+
+/** Resolve a Theatre project-state path against `root` — absolute paths pass through unconfined (see module jsdoc); relative paths join `root`. */
+function resolveTheatreProjectPath(root: string, theatreProjectPath: string): string {
+  return isAbsolute(theatreProjectPath) ? theatreProjectPath : join(root, theatreProjectPath);
+}
+
+function readTheatreProjectFile(absPath: string): unknown {
+  if (!existsSync(absPath)) {
+    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+  }
+  return JSON.parse(readFileSync(absPath, 'utf-8'));
+}
+
+// Same "outer shape only" convention as B2's project.theatre.validate — see
+// module jsdoc for why this repo does not own the internal keyframe format.
+const TheatreProjectOuterShape = z.object({
+  sheetsById: z.record(z.string(), z.unknown()),
+  definitionVersion: z.string(),
+  revisionHistory: z.array(z.unknown()),
+});
+
+// One layer deeper — sequence.length/subUnitsPerUnit + tracksByObject KEYS
+// only (never a track/keyframe's own content).
+const TheatreSequenceShape = z.object({
+  length: z.number(),
+  subUnitsPerUnit: z.number().optional(),
+  tracksByObject: z.record(z.string(), z.unknown()),
+});
+const TheatreSheetShape = z.object({
+  sequence: TheatreSequenceShape,
+  staticOverrides: z.unknown().optional(),
+});
+const TheatreProjectDeepShape = z.object({
+  sheetsById: z.record(z.string(), TheatreSheetShape),
+  definitionVersion: z.string(),
+  revisionHistory: z.array(z.unknown()),
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.project.list
+// ---------------------------------------------------------------------------
+
+const CinematicProjectListInput = z.object({
+  root: z
+    .string()
+    .optional()
+    .describe('Directory to search for *.theatre-project.json files. Defaults to ctx.projectRoot.'),
+});
+
+const CinematicProjectListResult = z.object({
+  root: z.string().describe('The directory actually searched.'),
+  theatreProjectFiles: z
+    .array(z.string())
+    .describe(
+      'Root-relative paths to every committed *.theatre-project.json / theatre-project.json file found, sorted.',
+    ),
+});
+
+export const cinematicProjectList = defineOperation({
+  name: 'cinematic.project.list',
+  summary: 'List every committed Theatre project-state file under a directory.',
+  description:
+    'Static, file-native discovery (§8 B5 "list Theatre projects"). Matches both the ' +
+    '`*.theatre-project.json` naming convention (packages/engine/test/fixtures/) and the plain ' +
+    '`theatre-project.json` convention used by the render-mode e2e fixtures ' +
+    '(packages/engine/e2e/{reference,render,audio}-cinematic/).',
+  input: CinematicProjectListInput,
+  result: CinematicProjectListResult,
+  errors: [NO_ROOT_ERROR],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Walks a file tree; no writes.' },
+  async impl(input, ctx) {
+    const root = resolveRoot(input.root, ctx);
+    const theatreProjectFiles = listProjectFiles(root, (p) => p.endsWith('theatre-project.json'));
+    return { root, theatreProjectFiles };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.sheet.list
+// ---------------------------------------------------------------------------
+
+const CinematicSheetListInput = z.object({
+  theatreProjectPath: z
+    .string()
+    .describe('Path to a committed Theatre project-state JSON file (absolute, or root-relative).'),
+  root: z
+    .string()
+    .optional()
+    .describe('Base directory for a relative theatreProjectPath. Defaults to ctx.projectRoot.'),
+});
+
+const CinematicSheetListResult = z.object({
+  sheets: z.array(z.string()).describe('Every sheet name in sheetsById, sorted.'),
+});
+
+export const cinematicSheetList = defineOperation({
+  name: 'cinematic.sheet.list',
+  summary: 'List every sheet name in a committed Theatre project-state file.',
+  description: 'Static, file-native (§8 B5 "list Theatre ... sheets"). Outer-shape validated only.',
+  input: CinematicSheetListInput,
+  result: CinematicSheetListResult,
+  errors: [NO_ROOT_ERROR, THEATRE_FILE_NOT_FOUND_ERROR, INVALID_THEATRE_PROJECT_ERROR],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one Theatre project-state file; no writes.' },
+  async impl(input, ctx) {
+    const root = resolveRoot(input.root, ctx);
+    const absPath = resolveTheatreProjectPath(root, input.theatreProjectPath);
+    const json = readTheatreProjectFile(absPath);
+    const parsed = TheatreProjectOuterShape.safeParse(json);
+    if (!parsed.success) {
+      throw new OperationError(
+        'INVALID_THEATRE_PROJECT',
+        `${absPath} does not match Theatre project-state's outer shape.`,
+        { issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) },
+      );
+    }
+    return { sheets: Object.keys(parsed.data.sheetsById).sort() };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// cinematic.sequence.inspect
+// ---------------------------------------------------------------------------
+
+const CinematicSequenceInspectInput = z.object({
+  theatreProjectPath: z
+    .string()
+    .describe('Path to a committed Theatre project-state JSON file (absolute, or root-relative).'),
+  sheetName: z.string().describe('Which sheet in sheetsById to inspect.'),
+  root: z
+    .string()
+    .optional()
+    .describe('Base directory for a relative theatreProjectPath. Defaults to ctx.projectRoot.'),
+});
+
+const CinematicSequenceInspectResult = z.object({
+  sheetName: z.string(),
+  length: z.number().describe('Sequence length in seconds (Theatre’s `sequence.length`).'),
+  subUnitsPerUnit: z
+    .number()
+    .optional()
+    .describe('Theatre’s `sequence.subUnitsPerUnit`, when present.'),
+  objects: z
+    .array(z.string())
+    .describe('Every tracked Sheet Object name (tracksByObject’s keys), sorted.'),
+  trackCountByObject: z
+    .record(z.string(), z.number())
+    .describe(
+      'Number of property tracks declared per object (trackIdByPropPath’s size), where present.',
+    ),
+});
+
+export const cinematicSequenceInspect = defineOperation({
+  name: 'cinematic.sequence.inspect',
+  summary:
+    'Inspect one sheet’s sequence length and tracked objects in a Theatre project-state file.',
+  description:
+    'Static, file-native (§8 B5 "inspect sequence length and objects"). Descends one layer past ' +
+    'the outer shape (sequence.length/subUnitsPerUnit/tracksByObject KEYS) — never a track/keyframe’s ' +
+    'own content, which stays Theatre Studio’s proprietary authoring concern (§3.2/§5.3).',
+  input: CinematicSequenceInspectInput,
+  result: CinematicSequenceInspectResult,
+  errors: [
+    NO_ROOT_ERROR,
+    THEATRE_FILE_NOT_FOUND_ERROR,
+    INVALID_THEATRE_PROJECT_ERROR,
+    SHEET_NOT_FOUND_ERROR,
+  ],
+  requires: {},
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one Theatre project-state file; no writes.' },
+  async impl(input, ctx) {
+    const root = resolveRoot(input.root, ctx);
+    const absPath = resolveTheatreProjectPath(root, input.theatreProjectPath);
+    const json = readTheatreProjectFile(absPath);
+    const parsed = TheatreProjectDeepShape.safeParse(json);
+    if (!parsed.success) {
+      throw new OperationError(
+        'INVALID_THEATRE_PROJECT',
+        `${absPath} does not match Theatre project-state's shape (incl. per-sheet sequence).`,
+        { issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) },
+      );
+    }
+    const sheet = parsed.data.sheetsById[input.sheetName];
+    if (!sheet) {
+      throw new OperationError(
+        'SHEET_NOT_FOUND',
+        `No sheet named "${input.sheetName}" in ${absPath}.`,
+        { sheetName: input.sheetName, availableSheets: Object.keys(parsed.data.sheetsById).sort() },
+      );
+    }
+    const objects = Object.keys(sheet.sequence.tracksByObject).sort();
+    const trackCountByObject: Record<string, number> = {};
+    for (const [objectName, trackEntry] of Object.entries(sheet.sequence.tracksByObject)) {
+      const trackIdByPropPath = (trackEntry as { trackIdByPropPath?: Record<string, unknown> })
+        .trackIdByPropPath;
+      trackCountByObject[objectName] = trackIdByPropPath
+        ? Object.keys(trackIdByPropPath).length
+        : 0;
+    }
+    return {
+      sheetName: input.sheetName,
+      length: sheet.sequence.length,
+      ...(sheet.sequence.subUnitsPerUnit !== undefined
+        ? { subUnitsPerUnit: sheet.sequence.subUnitsPerUnit }
+        : {}),
+      objects,
+      trackCountByObject,
+    };
+  },
+});
+
+/** Register cinematic.project.list / cinematic.sheet.list / cinematic.sequence.inspect onto `registry`. */
+export function registerTheatreOperations(registry: OperationRegistry): void {
+  registry.register(cinematicProjectList);
+  registry.register(cinematicSheetList);
+  registry.register(cinematicSequenceInspect);
+}

package/src/editor/camera-operations.ts

@@ -0,0 +1,169 @@
+/**
+ * `editor.viewport.camera.get` / `editor.viewport.camera.set`
+ * (B3, §8 B3 "viewport camera read/set").
+ *
+ * B3-followup: both directions are now genuinely wired to the live viewport
+ * camera, not just the three relay verbs.
+ *
+ * GET reads the REAL pose: `collectState` in `packages/editor/src/command-listener.ts`
+ * now reports `camera: {position, target, fov}` straight off the bound Three.js
+ * viewport camera + orbit target (`EditorStore.cameraPose`, populated once
+ * `ViewportPanel.tsx` binds a camera). `HttpEditorTransport.getCamera` reads it
+ * off `GET /__editor/state`. The declared `CAMERA_STATE_UNAVAILABLE` error still
+ * exists for the narrow window before any browser tab has bound/reported a
+ * camera (a session IS connected — this is a timing gap, not a fabricated pose).
+ *
+ * SET now supports a genuine arbitrary pose in addition to the three original
+ * relay verbs (focus-entity/focus-selection/view-preset): a `{mode:'pose',
+ * position, target, fov?}` input relays `{type:'set-camera', position, target,
+ * fov}` — a real, handled case in `command-listener.ts`'s `handleCommand`
+ * switch that calls `EditorViewport.setPose` (moves `camera.position` +
+ * `orbitControls.target`, updates `fov`/projection matrix when given).
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_COMMAND_TIMEOUT_MS,
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const CAMERA_STATE_UNAVAILABLE_ERROR = {
+  code: 'CAMERA_STATE_UNAVAILABLE',
+  summary:
+    'A session is connected, but no browser tab has bound/reported a viewport camera pose yet ' +
+    '(e.g. immediately after page load, before ViewportPanel mounts) — not a fabricated value.',
+  data: z.object({}),
+} as const;
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed camera command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+const Vector3Schema = z.object({ x: z.number(), y: z.number(), z: z.number() });
+
+const CameraPoseSchema = z.object({
+  position: Vector3Schema,
+  target: Vector3Schema,
+  fov: z.number(),
+});
+
+// ---------------------------------------------------------------------------
+// editor.viewport.camera.get
+// ---------------------------------------------------------------------------
+
+const EditorViewportCameraGetInput = z
+  .object({})
+  .describe('No input — reads the viewport camera pose from the target editor session.');
+
+const EditorViewportCameraGetResult = CameraPoseSchema.describe('Live viewport camera pose.');
+
+export const editorViewportCameraGet = defineOperation({
+  name: 'editor.viewport.camera.get',
+  summary: 'Read the viewport camera pose (position/target/fov) from a connected editor session.',
+  description:
+    'Resolves a target session then reads its live camera pose (position, orbit target, fov) off ' +
+    'the bound Three.js viewport camera. Throws the declared CAMERA_STATE_UNAVAILABLE only in the ' +
+    'narrow window before any browser tab has bound/reported one — never a fabricated pose.',
+  input: EditorViewportCameraGetInput,
+  result: EditorViewportCameraGetResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, CAMERA_STATE_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live editor viewport camera state only.' },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const camera = await withTimeout(
+      transport.getCamera(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.viewport.camera.get',
+    ).catch(() => undefined);
+    if (!camera) {
+      throw new OperationError(
+        'CAMERA_STATE_UNAVAILABLE',
+        'No browser tab has bound/reported a viewport camera pose yet.',
+        {},
+      );
+    }
+    return camera;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// editor.viewport.camera.set
+// ---------------------------------------------------------------------------
+
+const EditorViewportCameraSetInput = z
+  .discriminatedUnion('mode', [
+    z.object({ mode: z.literal('focusEntity'), entityId: z.string() }),
+    z.object({ mode: z.literal('focusSelection') }),
+    z.object({
+      mode: z.literal('viewPreset'),
+      preset: z.enum(['top', 'front', 'right', 'perspective']),
+    }),
+    z.object({
+      mode: z.literal('pose'),
+      position: Vector3Schema,
+      target: Vector3Schema,
+      fov: z.number().optional(),
+    }),
+  ])
+  .describe(
+    'Either one of the three named relay verbs, or an arbitrary xyz position/target (+ optional fov) pose.',
+  );
+
+const EditorViewportCameraSetResult = z.object({ ok: z.literal(true) });
+
+export const editorViewportCameraSet = defineOperation({
+  name: 'editor.viewport.camera.set',
+  summary:
+    'Move the viewport camera via focus-entity, focus-selection, a view preset, or an arbitrary pose.',
+  description:
+    'Relays focus-entity/focus-selection/view-preset, or an arbitrary {position, target, fov?} ' +
+    'pose via `set-camera`, through POST /__editor/command — all four are real, handled cases in ' +
+    "the browser's command listener (EditorViewport.setPose backs the arbitrary-pose mode).",
+  input: EditorViewportCameraSetInput,
+  result: EditorViewportCameraSetResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, COMMAND_FAILED_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Moves the live editor viewport camera only (no file/document writes).',
+  },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const result = await withTimeout(
+      transport.setCamera(session, input, EDITOR_COMMAND_TIMEOUT_MS),
+      EDITOR_COMMAND_TIMEOUT_MS,
+      'editor.viewport.camera.set',
+    ).catch((err: unknown) => ({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'camera command failed', {
+        message: result.error ?? 'camera command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+export function registerCameraOperations(registry: OperationRegistry): void {
+  registry.register(editorViewportCameraGet);
+  registry.register(editorViewportCameraSet);
+}

package/src/editor/console-operations.ts

@@ -0,0 +1,87 @@
+/**
+ * `editor.console.subscribe` (B3, §8 B3 "editor console/log subscription metadata").
+ *
+ * Deliberately METADATA-ONLY, per the spec bullet's own wording — a
+ * request/response SDK operation cannot itself BE a stream. This describes
+ * the real, existing subscription mechanics: the general SSE endpoint
+ * (`GET /__editor/events`, broadcasting `editor-command`/`project-changed`/
+ * `asset-moved`/`scene-changed`) and the play-mode log persistence pair
+ * (`POST /__editor/log-session`, `GET/POST /__editor/log-entries`), plus a
+ * live count of currently-buffered log entries as a liveness signal. Editor
+ * console messages themselves (`packages/editor/src/editor-console.ts`) are
+ * in-browser, in-memory only today — not broadcast server-side — so this op
+ * cannot report live console entries, only the real subscription surface
+ * that does exist.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const CONSOLE_METADATA_UNAVAILABLE_ERROR = {
+  code: 'CONSOLE_METADATA_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the log-entries read in time.',
+  data: z.object({}),
+} as const;
+
+const EditorConsoleSubscribeInput = z
+  .object({})
+  .describe("No input — describes how to subscribe to the target editor session's events/logs.");
+
+const EditorConsoleSubscribeResult = z.object({
+  sseUrl: z.string().describe('The general editor SSE endpoint.'),
+  events: z.array(z.string()).describe('Event names broadcast on sseUrl.'),
+  logEntriesUrl: z.string().describe('GET (read) / POST (append) persisted play-mode log entries.'),
+  logSessionUrl: z
+    .string()
+    .describe('POST {action:"start"|"end"} to bracket a play-mode log-persistence session.'),
+  bufferedLogCount: z
+    .number()
+    .describe('Number of play-mode log entries currently buffered/persisted.'),
+});
+
+export const editorConsoleSubscribe = defineOperation({
+  name: 'editor.console.subscribe',
+  summary: "Describe how to subscribe to a connected editor session's events and logs.",
+  description:
+    'Metadata only (a request/response op cannot itself be a stream): reports the real SSE ' +
+    'endpoint + event names and the real play-mode log-persistence endpoints, plus a live ' +
+    'buffered-entry count. General editor console messages are in-browser/in-memory only today ' +
+    '(not broadcast server-side), so they are not part of this metadata.',
+  input: EditorConsoleSubscribeInput,
+  result: EditorConsoleSubscribeResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, CONSOLE_METADATA_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live log-entry metadata only.' },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const metadata = await withTimeout(
+      transport.getConsoleSubscriptionMetadata(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.console.subscribe',
+    ).catch(() => undefined);
+    if (!metadata) {
+      throw new OperationError(
+        'CONSOLE_METADATA_UNAVAILABLE',
+        'The connected editor session did not answer the log-entries read in time.',
+        {},
+      );
+    }
+    return metadata;
+  },
+});
+
+export function registerConsoleOperations(registry: OperationRegistry): void {
+  registry.register(editorConsoleSubscribe);
+}

package/src/editor/hierarchy-operations.ts

@@ -0,0 +1,95 @@
+/**
+ * `editor.hierarchy.inspect` (B3, §8 B3 "hierarchy inspect").
+ *
+ * B3-followup: wired to the REAL entity tree. `collectState`
+ * (`packages/editor/src/command-listener.ts`) now flattens `EditorStore.entities`
+ * — the same nested `SceneEntity[]` data model `GameHierarchy`/`hierarchy-rows.ts`
+ * render the hierarchy panel from — into `id`/`name`/`childIds` rows and reports
+ * them alongside `entityCount`/`savePath`. `HttpEditorTransport.getHierarchy`
+ * reads them off `GET /__editor/state`. `entities` is `null` only in the narrow
+ * window before any browser tab has POSTed state at least once (a session IS
+ * connected — this is a timing gap, not a fabricated tree).
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const HIERARCHY_UNAVAILABLE_ERROR = {
+  code: 'HIERARCHY_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the hierarchy-state read in time.',
+  data: z.object({}),
+} as const;
+
+const EditorHierarchyInspectInput = z
+  .object({})
+  .describe(
+    "No input — inspects the hierarchy of the target editor session's currently loaded scene.",
+  );
+
+const HierarchyNodeSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  childIds: z.array(z.string()),
+});
+
+const EditorHierarchyInspectResult = z.object({
+  savePath: z
+    .string()
+    .nullable()
+    .describe('Project-relative path of the scene currently loaded in the editor, or null.'),
+  entityCount: z.number().describe('Live entity count reported by the editor.'),
+  entities: z
+    .array(HierarchyNodeSchema)
+    .nullable()
+    .describe(
+      'Full flattened entity list (id/name/childIds), reflecting the real live scene graph. Null ' +
+        'only in the narrow window before any browser tab has POSTed state at least once — ' +
+        'savePath/entityCount are still real live data either way.',
+    ),
+});
+
+export const editorHierarchyInspect = defineOperation({
+  name: 'editor.hierarchy.inspect',
+  summary: "Inspect the entity hierarchy of the target editor session's currently loaded scene.",
+  description:
+    'Resolves a target session then reads its live state. savePath/entityCount/entities are all ' +
+    'real, live data — entities is the flattened scene graph (id/name/childIds), null only before ' +
+    'any browser tab has reported state at least once.',
+  input: EditorHierarchyInspectInput,
+  result: EditorHierarchyInspectResult,
+  errors: [EDITOR_NOT_RUNNING_ERROR, HIERARCHY_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live editor scene state only.' },
+  async impl(_input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const hierarchy = await withTimeout(
+      transport.getHierarchy(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.hierarchy.inspect',
+    ).catch(() => undefined);
+    if (!hierarchy) {
+      throw new OperationError(
+        'HIERARCHY_UNAVAILABLE',
+        'The connected editor session did not answer the hierarchy-state read in time.',
+        {},
+      );
+    }
+    return hierarchy;
+  },
+});
+
+export function registerHierarchyOperations(registry: OperationRegistry): void {
+  registry.register(editorHierarchyInspect);
+}