@vgai/editor-sdk 0.5.11 → 0.5.13

package/README.md

@@ -42,8 +42,9 @@ One export, `EditorClient`, plus its types (`EditorState`, `ProjectInfo`,
 - Panels: `showViewport('scene'|'game')`, `showInspector`, `openAsset`,
   `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
+- Display: `setGrid`, `setHelpers`, `setStats`, `setShadingMode` (`solid` for
+  authored materials, `clay` for neutral flat shading, `unlit`, `wireframe`,
+  `normals`, or `overdraw`), `setHelperType` (including
   the independent `bounds` category). Shading targets the active Scene/Game
   viewport and remains render-only, session-local state.
 - Transform tools: `setTransformMode`, `setTransformSpace`, `setSnap`
@@ -99,7 +100,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 —
-three surfaces, one degradation ladder (`ExtensionContributionTier`:
+three surfaces, one outcome vocabulary (`ExtensionContributionState`:
 `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

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,13 +18,15 @@
   "exports": {
     ".": "./src/index.ts",
     "./contributions": "./src/contributions.ts",
+    "./document-probe": "./src/document-probe.ts",
     "./extension": "./src/extension.ts"
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.11"
+    "@vgai/sdk": "0.5.13"
   },
   "peerDependencies": {
+    "@vgai/engine": "*",
     "react": "^19.0.0",
     "three": "^0.180.0"
   }

package/src/client.ts

@@ -1,4 +1,5 @@
 import type { GenerationJobsDocument } from '@vgai/sdk/generations';
+import type { DocumentProbeResult, DocumentProbeStep } from './document-probe.js';
 import type {
   ActiveDocumentCapture,
   AssetCompareCapture,
@@ -12,6 +13,7 @@ import type {
   EditorView,
   GameCapture,
   HelperVisibility,
+  InspectedHierarchy,
   InspectedInspection,
   LabeledShotSetCapture,
   PresentedEditorView,
@@ -113,6 +115,16 @@ const COMMAND_DEADLINE_MS = 150_000;
  * `code: 'DEBUG_COMMAND_NOT_REGISTERED'`. A panel decides what to show for
  * those; the client never invents one.
  */
+/** What one undo/redo step reports back — `moved` is false when there was
+ *  nothing left in that direction, which is an answer, not an error. */
+export interface HistoryStep {
+  readonly moved: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel: string | null;
+  readonly redoLabel: string | null;
+}
+
 export interface GameDebugDoor {
   /**
    * Read ONE registered state provider by name (`'bot.tester'`). `undefined`
@@ -533,6 +545,55 @@ export class EditorClient {
     return data.subject;
   }
 
+  /**
+   * The HIERARCHY PANEL's actual rendered row tree, as data.
+   *
+   * The same rows a human is looking at: the adapter's tree after the component
+   * marks fold implementation subtrees, after the internals reveal, after the
+   * document promotion, the child cap, the collapse state, the search filter
+   * and the selection scope. Works in play mode and edit mode alike — the
+   * answer reports which (`playState`, `activeViewportTab`), because a
+   * play-mode tree and an edit-mode tree come from different adapters.
+   *
+   * Deliberately NOT `status().entities`, which walks the raw adapter tree and
+   * therefore answers a different question: a panel defect is invisible in it.
+   *
+   * Each row carries `childCount` (what its caret opens), `internalChildCount`
+   * (what is folded behind "Reveal Internals") and `expandable` (whether the
+   * panel draws a caret at all) — so "this subtree exists but the UI offers no
+   * way to open it" is a readable fact rather than something only a human
+   * squinting at the panel can notice.
+   *
+   * Rejects, naming the panel, when no hierarchy panel is mounted: an empty
+   * tree would be a fabricated answer about a surface nobody is being shown.
+   */
+  async hierarchy(): Promise<InspectedHierarchy> {
+    const data = await this.command<{ hierarchy: InspectedHierarchy }>({ type: 'hierarchy' });
+    return data.hierarchy;
+  }
+
+  /** Write one editable path through the active Inspector's own IO. */
+  async setInspectionField(path: string, value: unknown): Promise<InspectedInspection> {
+    const data = await this.command<{ subject: InspectedInspection }>({
+      type: 'set-inspection-field',
+      path,
+      value,
+    });
+    return data.subject;
+  }
+
+  /**
+   * Undo / redo one project transaction — the same queue the keyboard shortcut
+   * drives. `moved` is false when there was nothing left in that direction.
+   */
+  async undo(): Promise<HistoryStep> {
+    return this.command<HistoryStep>({ type: 'undo' });
+  }
+
+  async redo(): Promise<HistoryStep> {
+    return this.command<HistoryStep>({ type: 'redo' });
+  }
+
   /** Read the editor's actual current durable projection. */
   async currentView(): Promise<EditorView> {
     const data = await this.command<{ view: EditorView }>({ type: 'current-view' });
@@ -547,8 +608,35 @@ export class EditorClient {
     });
   }
 
+  /**
+   * Read or drive the ACTIVE center document's own DOM — the scoped
+   * editor-chrome door, and the read/gesture half of the same subject
+   * {@link captureActiveDocument} photographs. NOT play-mode gated, and NOT
+   * page automation: a target outside the active document's container is
+   * refused by name. Design and scope contract:
+   * `packages/editor/src/editor-document-probe.ts`.
+   */
+  async documentProbe(step: DocumentProbeStep): Promise<DocumentProbeResult> {
+    return this.command<DocumentProbeResult>({ type: 'document-probe', step });
+  }
+
   // --- Display (set semantics) ---
 
+  /**
+   * The Game document's "Persist to game source" consent, over the relay —
+   * the same session-scoped switch the checkbox flips, refused for the same
+   * reasons (it answers with the server's own words when the base cannot be
+   * written). `recorder` names who accounts for the diff a write produces.
+   */
+  async setSourcePersistConsent(
+    enabled: boolean,
+  ): Promise<{ enabled: boolean; recorder: string | null }> {
+    return this.command<{ enabled: boolean; recorder: string | null }>({
+      type: 'set-source-persist-consent',
+      enabled,
+    });
+  }
+
   async setGrid(enabled: boolean): Promise<void> {
     await this.command({ type: 'set-grid', enabled });
   }

package/src/contributions.ts

@@ -4,13 +4,17 @@
  * metadata names a module and the editor renders its default export.
  */
 
+import type { AuthoringAdapter } from '@vgai/engine/adapter';
 import type { GenerationAccountProjection } from '@vgai/sdk/account';
 import type { GenerationJob } from '@vgai/sdk/generations';
 import type {
   AnimationClip,
   Camera,
   ColorRepresentation,
+  Group,
+  Intersection,
   Object3D,
+  Ray,
   Scene,
   WebGLRenderer,
 } from 'three';
@@ -128,9 +132,142 @@ export interface ToolObject3DAuthoringProps {
    * Without this binding the animation workspace remains honestly read-only.
    */
   readonly animationSource?: ToolAnimationSourceBinding;
+  /**
+   * Project-owned serialization for this authored document. Each serializer
+   * returns the exact bytes of one ordinary project file; the host writes all
+   * resources as one checksum-guarded, failure-atomic history transaction.
+   * The project owns the format and the host never interprets its contents.
+   */
+  readonly persistence?: ToolObject3DDocumentPersistence;
+  /** Replace the default native-tree projection with a semantic adapter. The
+   * default adapter is provided for delegation, so a project can add terrain
+   * layers, bones, or mesh elements without rebuilding Object3D projection. */
+  readonly authoring?: ToolObject3DDocumentAuthoringFactory;
+  /** Project-owned direct manipulation hosted by the editor's input and
+   * transient-overlay lifecycle. Completed gestures commit `persistence`; an
+   * Escape, unmount, thrown callback, or failed write calls `cancel`. */
+  readonly interaction?: ToolObject3DDocumentInteraction;
   readonly active?: boolean;
 }
 
+/** The native document state handed back to project-owned serializers. */
+export interface ToolObject3DDocumentState {
+  readonly root: Object3D;
+  readonly animations: readonly AnimationClip[];
+}
+
+/** One project-owned artifact participating in an Asset Lab commit. */
+export interface ToolObject3DDocumentResource {
+  /** Project-root-relative destination. */
+  readonly path: string;
+  /** MIME type recorded in canonical history. */
+  readonly contentType?: string;
+  /** `null` removes the file in the same atomic transaction. */
+  readonly serialize: (
+    document: ToolObject3DDocumentState,
+  ) => string | Uint8Array | null | Promise<string | Uint8Array | null>;
+}
+
+export interface ToolObject3DDocumentPersistence {
+  /** Default undo/redo label. A completed gesture may supply a narrower one. */
+  readonly label?: string;
+  /**
+   * True only when these resources serialize mutations to `document.animations`.
+   * Sidecar-only bindings still make direct manipulation writable, but must
+   * leave animation keys read-only rather than pretending to save them.
+   */
+  readonly persistsAnimations?: boolean;
+  /** Non-empty, path-unique set of files owned by this document. */
+  readonly resources: readonly ToolObject3DDocumentResource[];
+}
+
+export interface ToolObject3DDocumentAuthoringContext extends ToolObject3DDocumentState {
+  readonly documentId: string;
+  readonly sourcePath: string;
+  readonly scene: Scene;
+  readonly defaultAdapter: AuthoringAdapter;
+  /**
+   * Serialize this project-owned document through its declared persistence
+   * resources and record the change in canonical history. Rejects when the
+   * document is read-only or the atomic write fails.
+   */
+  readonly commit: (label?: string) => Promise<boolean>;
+}
+
+export interface ToolObject3DDocumentAuthoring {
+  readonly adapter: AuthoringAdapter;
+  dispose?(): void;
+}
+
+export type ToolObject3DDocumentAuthoringFactory = (
+  context: ToolObject3DDocumentAuthoringContext,
+) => ToolObject3DDocumentAuthoring;
+
+/** Adapter-native hit data for a project-owned Asset Lab gesture. */
+export interface ToolObject3DPointerEvent {
+  readonly pointerId: number;
+  readonly button: number;
+  readonly buttons: number;
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly altKey: boolean;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly shiftKey: boolean;
+  readonly ray: Ray;
+  readonly hits: readonly Intersection<Object3D>[];
+}
+
+/** One gesture owns exact rollback to its pre-begin document state. */
+export interface ToolObject3DGesture {
+  readonly label?: string;
+  update(event: ToolObject3DPointerEvent): void;
+  /** Finalize the project-owned native state before the host serializes it. */
+  commit(event: ToolObject3DPointerEvent): void | Promise<void>;
+  /** Restore exact pre-begin native state. Must be safe after partial commit. */
+  cancel(): void | Promise<void>;
+}
+
+export interface ToolObject3DInteractionContext {
+  readonly root: Object3D;
+  readonly scene: Scene;
+  readonly renderer: WebGLRenderer;
+  /** Host-owned group removed on document teardown. Project code owns GPU
+   * resources it adds and releases them from the extension's `dispose`. */
+  readonly overlay: Group;
+  /** Live camera getter; projection can change while the document is open. */
+  readonly camera: () => Camera;
+  /** False means gestures will not begin because no persistence binding exists. */
+  readonly writable: boolean;
+}
+
+export interface ToolObject3DInteractionExtension {
+  /** Return null to yield this pointer to the ordinary viewport controls. */
+  begin(event: ToolObject3DPointerEvent): ToolObject3DGesture | null;
+  /**
+   * Optional pre-sample phase. Restore any transforms changed by the previous
+   * frame's refinement here; the host samples animation after this call and
+   * invokes {@link update} with the resulting native pose.
+   */
+  prepareFrame?(deltaSeconds: number, context: ToolObject3DFrameContext): void;
+  /**
+   * Optional per-frame refinement after the host samples the active animation
+   * clip. Use this for project-owned constraints and overlay presentation.
+   */
+  update?(deltaSeconds: number, context: ToolObject3DFrameContext): void;
+  dispose(): void;
+}
+
+export interface ToolObject3DFrameContext {
+  /** For `prepareFrame`, true when the host will sample animation next. For
+   * `update`, true when it sampled an animation clip immediately beforehand. */
+  readonly animationSampled: boolean;
+}
+
+export interface ToolObject3DDocumentInteraction {
+  setup(context: ToolObject3DInteractionContext): ToolObject3DInteractionExtension;
+}
+
 export interface ToolAnimationSourceBinding {
   /** Project-relative TypeScript file below src/. */
   readonly path: string;

package/src/document-probe.ts

@@ -0,0 +1,80 @@
+/**
+ * The wire vocabulary of the ACTIVE-DOCUMENT probe — the scoped editor-chrome
+ * door (`packages/editor/src/editor-document-probe.ts` implements it,
+ * `@vgai/live`'s `editor.document` binds it, and that module's header carries
+ * the design decision and the scope contract).
+ *
+ * Deliberately NOT a page-automation vocabulary: there is no navigation, no
+ * waiting, no frame/window addressing and no selector rooted anywhere but the
+ * active document's own container. Four actions, each one a gesture or a read
+ * an agent cannot otherwise perform through the product.
+ */
+
+/** One element as the probe reports it — everything a caller needs to assert
+ *  on, and nothing that requires a second round trip. */
+export interface ProbedElement {
+  /** Position within the match list this element came from. */
+  index: number;
+  tag: string;
+  /** `innerText`, trimmed and capped. */
+  text: string;
+  attributes: Record<string, string>;
+  rect: { x: number; y: number; width: number; height: number };
+  /** Present for form controls. */
+  value?: string;
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+export interface DocumentProbeResult {
+  /** The scope the step ran in — echoed so a transcript proves WHICH document
+   *  was driven, not merely that something was. */
+  document: { id: string; title: string };
+  /** Total matches inside the scope, before any `limit`. */
+  matched: number;
+  elements: ProbedElement[];
+}
+
+/** Read what the active document rendered. */
+export interface DocumentQueryStep {
+  action: 'query';
+  selector: string;
+  /** Cap on returned elements (default 25); `matched` still reports the total. */
+  limit?: number;
+}
+
+/** A real pointer gesture on one matched element. */
+export interface DocumentClickStep {
+  action: 'click';
+  selector: string;
+  /** Which match (default 0). */
+  index?: number;
+}
+
+/** A real key on the explicit target, else whatever inside the document has focus. */
+export interface DocumentKeyStep {
+  action: 'key';
+  key: string;
+  code?: string;
+  selector?: string;
+  index?: number;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+}
+
+/** A real `ClipboardEvent` carrying `text/plain` — the only way to exercise a
+ *  paste handler, and the gesture the Sheets build could not verify. */
+export interface DocumentPasteStep {
+  action: 'paste';
+  text: string;
+  selector?: string;
+  index?: number;
+}
+
+export type DocumentProbeStep =
+  | DocumentQueryStep
+  | DocumentClickStep
+  | DocumentKeyStep
+  | DocumentPasteStep;

package/src/editor-view.ts

@@ -8,9 +8,9 @@ const ASSET_KINDS = new Set<AssetKind>([
   'audio',
   'animation',
   'json',
-  'scene',
   'prefab',
   'material',
+  'source',
 ]);
 const CAMERAS = new Set<ViewPreset | 'isometric'>([
   'top',
@@ -32,7 +32,12 @@ const DIAGNOSTICS = new Set<EditorViewDiagnostic>([
   'bounds',
   'skeleton',
 ]);
-const UTILITIES = new Set<EditorViewUtility>(['profiler', 'console', 'animation']);
+const UTILITIES = new Set<EditorViewUtility>([
+  'profiler',
+  'console',
+  'animation',
+  'light-explorer',
+]);
 
 function nonEmpty(value: string | null): string | null {
   const trimmed = value?.trim();
@@ -47,7 +52,7 @@ function writeDocument(params: URLSearchParams, document: EditorView['document']
     params.set(`${PREFIX}assetSource`, 'entity');
   } else if (document.kind === 'asset') {
     params.set(`${PREFIX}doc`, document.path!);
-  } else if (document.kind === 'scene' || document.kind === 'data') {
+  } else if (document.kind === 'scene') {
     params.set(`${PREFIX}doc`, document.path);
   } else if (document.kind === 'story') {
     params.set(`${PREFIX}doc`, document.modulePath);
@@ -139,7 +144,6 @@ function parseDocument(params: URLSearchParams): EditorView['document'] {
   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);
@@ -148,7 +152,6 @@ function parseDocument(params: URLSearchParams): EditorView['document'] {
     [
       'workspace:scene',
       'workspace:game',
-      'workspace:data-assets',
       'workspace:build-profiles',
       'account',
       'project-tools',

package/src/extension.ts

@@ -19,8 +19,8 @@
  *     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} —
+ * Outcomes (the anti-shim rule, as API): every contribution resolves to an
+ * {@link ExtensionContributionState} —
  *
  * - `'active'` — the contribution loaded and produced its surface.
  * - `'absent'` — nothing was contributed. The editor HIDES the surface
@@ -33,7 +33,8 @@
  */
 
 /**
- * Capability tier of a single extension contribution — the degradation
- * ladder made API (see the module doc above for the exact semantics).
+ * The terminal state of a single extension contribution (see the module doc
+ * above for the exact semantics). Not a grade and not an ordering: `absent`
+ * and `failed` both hide the surface, and `failed` is reported loudly.
  */
-export type ExtensionContributionTier = 'active' | 'absent' | 'failed';
+export type ExtensionContributionState = 'active' | 'absent' | 'failed';

package/src/index.ts

@@ -4,7 +4,7 @@ export type {
   GenerationJobStatus,
   GenerationJobsDocument,
 } from '@vgai/sdk/generations';
-export type { GameDebugDoor } from './client.js';
+export type { GameDebugDoor, HistoryStep } from './client.js';
 export { EditorClient, EditorCommandError } from './client.js';
 export type {
   ToolAssetInspectorContributionMatch,
@@ -16,8 +16,17 @@ export type {
   ToolInspectorContributionMatch,
   ToolInspectorContributionProps,
 } from './contributions.js';
+export type {
+  DocumentClickStep,
+  DocumentKeyStep,
+  DocumentPasteStep,
+  DocumentProbeResult,
+  DocumentProbeStep,
+  DocumentQueryStep,
+  ProbedElement,
+} from './document-probe.js';
 export { editorViewFromUrl, editorViewUrl } from './editor-view.js';
-export type { ExtensionContributionTier } from './extension.js';
+export type { ExtensionContributionState } from './extension.js';
 export type {
   ActiveDocumentCapture,
   AssetCompareCapture,
@@ -41,6 +50,8 @@ export type {
   HelperVisibility,
   InspectedAction,
   InspectedField,
+  InspectedHierarchy,
+  InspectedHierarchyRow,
   InspectedInspection,
   InspectedNothing,
   InspectedSection,

package/src/types.ts

@@ -15,9 +15,9 @@ export type AssetKind =
   | 'audio'
   | 'animation'
   | 'json'
-  | 'scene'
   | 'prefab'
-  | 'material';
+  | 'material'
+  | 'source';
 
 export interface HelperVisibility {
   bounds: boolean;
@@ -29,6 +29,8 @@ export interface HelperVisibility {
   audio: boolean;
   splines: boolean;
   navmesh: boolean;
+  constraints: boolean;
+  reflectionProbes: boolean;
   skeletons: boolean;
 }
 
@@ -397,7 +399,9 @@ export interface EditorState {
    * would otherwise leave unexplained. `heapUsedMB`/`heapLimitMB` are null off
    * Chromium (`performance.memory` is non-standard); the renderer counts are
    * absent, never zero, when no game has registered a render-debug adapter.
-   * `censusAgeMs` says how stale the profile is — a hidden tab is not sampled.
+   * `mountEpochs` counts the project module generations accumulated in this
+   * document; it is absent against an older server. `censusAgeMs` says how
+   * stale the profile is — a hidden tab is not sampled.
    */
   tabs?: Array<{
     tabId8: string;
@@ -413,6 +417,7 @@ export interface EditorState {
     census?: {
       heapUsedMB: number | null;
       heapLimitMB: number | null;
+      mountEpochs?: number;
       canvases: number;
       canvasMB: number;
       textures?: number;
@@ -513,7 +518,7 @@ export interface EditorState {
 }
 
 export type ViewPreset = 'top' | 'front' | 'right' | 'perspective';
-export type ShadingMode = 'solid' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
 export type TransformMode = 'translate' | 'rotate' | 'scale';
 export type TransformSpace = 'world' | 'local';
 
@@ -529,7 +534,6 @@ export type EditorViewDocument =
   | { 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 }
   | {
@@ -537,7 +541,6 @@ export type EditorViewDocument =
       id:
         | 'workspace:scene'
         | 'workspace:game'
-        | 'workspace:data-assets'
         | 'workspace:build-profiles'
         | 'account'
         | 'project-tools';
@@ -553,7 +556,7 @@ export interface EditorView {
     frame?: 'document' | 'selection';
     grid?: boolean;
   };
-  utility?: 'profiler' | 'console' | 'animation';
+  utility?: 'profiler' | 'console' | 'animation' | 'light-explorer';
 }
 
 export interface PresentedEditorView {
@@ -687,6 +690,11 @@ export interface InspectedAction {
   disabled?: boolean;
 }
 
+export interface InspectedSubjectLink {
+  id: string;
+  title: string;
+}
+
 /** The whole inspection subject, as data — what a human sees in the
  *  inspector, for an agent (`vgai eval 'editor.inspect()'`). */
 export interface InspectedSubject {
@@ -701,6 +709,8 @@ export interface InspectedSubject {
     surface?: InspectionSurface;
   };
   quickActions: readonly InspectedAction[];
+  /** Agent-visible counterparts of the inspector's related-document buttons. */
+  related: readonly InspectedSubjectLink[];
   /** Already in display order. */
   sections: readonly InspectedSection[];
 }
@@ -716,3 +726,52 @@ export interface InspectedNothing {
 /** What `editor.inspect()` answers: the subject showing, or nothing at all.
  *  Narrow with `'none' in result`. */
 export type InspectedInspection = InspectedSubject | InspectedNothing;
+
+// ---------------------------------------------------------------- hierarchy
+//
+// The wire mirror of the editor's own `SerializedHierarchyPanel`
+// (`packages/editor/src/hierarchy-panel-view.ts`, which owns the contract and
+// carries the reasoning). `command-listener.ts` annotates its `hierarchy`
+// payload with this type, so `tsc` checks the two sides against each other on
+// every build.
+//
+// This is NOT `EditorState.entities`: that facet is the raw adapter tree, with
+// no marks, no internals folding and no document promotion. This one is what
+// the hierarchy PANEL rendered — the rows a human is looking at.
+
+/** One row of the hierarchy panel, as data. */
+export interface InspectedHierarchyRow {
+  id: string;
+  label: string;
+  /** The dim type suffix the row prints (`Coin1 ·Coin`). */
+  typeLabel?: string;
+  role?: string;
+  depth: number;
+  /** Children the row's view has — what opening the caret reveals. Folded
+   *  implementation children are NOT counted here. */
+  childCount: number;
+  /** Children folded away as implementation, behind "Reveal Internals". */
+  internalChildCount: number;
+  /** Whether the panel renders a disclosure control. A row with children of
+   *  any kind and `expandable: false` is a subtree the UI cannot reach. */
+  expandable: boolean;
+  expanded?: boolean;
+  internal?: true;
+  componentRoot?: true;
+  /** A synthetic "… N more" cap stub rather than a real node. */
+  more?: { hidden: number };
+  children?: readonly InspectedHierarchyRow[];
+}
+
+/** What `editor.hierarchy()` answers. */
+export interface InspectedHierarchy {
+  rowCount: number;
+  /** The slice in the DOM; a smaller span than `rowCount` means the rest is
+   *  scrolled out, not absent. */
+  window: { start: number; end: number };
+  search?: string;
+  scopeId?: string;
+  playState: string;
+  activeViewportTab: string;
+  roots: readonly InspectedHierarchyRow[];
+}