@volter/editor-core 0.5.57

package/src/hierarchy-menu-registry.ts

@@ -0,0 +1,67 @@
+/**
+ * Hierarchy context-menu contribution registry — the escape hatch for
+ * first-party-only row actions that are NOT contract-expressible through
+ * `StructureProvider`/`InspectorProvider`. `GameHierarchy` (the contract-only
+ * shell) calls {@link getHierarchyMenuItems} and appends whatever comes back
+ * to its own Rename/Duplicate/Show-Hide/Lock/Delete items — it never branches
+ * on WHICH registration fired, keeping Rule Zero intact: the shell still
+ * speaks only the `AuthoringAdapter` contract, and only a REGISTRATION module
+ * is allowed to reach into store internals.
+ *
+ * PERMANENT adapter-module contribution seam, the same status as
+ * `inspector-section-registry.ts`: first-party affordances that aren't
+ * (yet, or ever) contract-expressible register through here instead of the
+ * contract-only shell branching on adapter identity. If a given affordance later
+ * becomes contract-expressible, its OWN registration is removed at that point —
+ * the registry mechanism itself is not temporary. Nothing registers today, and
+ * an empty registry is a legitimate state.
+ */
+
+import type { EditorShellStore } from './editor-shell-store';
+
+export interface HierarchyMenuContext {
+  /** The row's node id (an `EditorNode.id` — format-neutral). */
+  readonly nodeId: string;
+  readonly store: EditorShellStore;
+}
+
+export interface HierarchyMenuItem {
+  readonly label: string;
+  readonly action: () => void;
+  readonly color?: string;
+}
+
+type Matcher = (ctx: HierarchyMenuContext) => boolean;
+type ItemsFactory = (ctx: HierarchyMenuContext) => HierarchyMenuItem[];
+
+interface Registration {
+  readonly match: Matcher;
+  readonly items: ItemsFactory;
+}
+
+const registrations: Registration[] = [];
+
+/**
+ * Register a set of first-party (or other non-contract) hierarchy context-menu
+ * items. `match` decides whether this registration applies to a given row;
+ * `items` builds the actual entries when it does (called only when `match`
+ * returns true). Returns an unregister function.
+ */
+export function registerHierarchyMenuItems(match: Matcher, items: ItemsFactory): () => void {
+  const reg: Registration = { match, items };
+  registrations.push(reg);
+  return () => {
+    const idx = registrations.indexOf(reg);
+    if (idx >= 0) registrations.splice(idx, 1);
+  };
+}
+
+/** Every registered item that applies to `ctx`, in registration order. */
+export function getHierarchyMenuItems(ctx: HierarchyMenuContext): HierarchyMenuItem[] {
+  return registrations.filter((r) => r.match(ctx)).flatMap((r) => r.items(ctx));
+}
+
+/** Test-only reset for module-level menu registrations. */
+export function __resetHierarchyMenuRegistryForTest(): void {
+  registrations.length = 0;
+}

package/src/hierarchy-node-rows.ts

@@ -0,0 +1,307 @@
+/**
+ * Pure row-flattening for `IngestHierarchy` (no React) — D-W4 (F14/F18),
+ * extracted the same way `hierarchy-rows.ts` extracts `SceneHierarchy`'s
+ * equivalent, so the key/collapse/cycle-guard logic is unit-testable without
+ * rendering.
+ *
+ * §0.5's ground truth: an ingested game's structural ids
+ * (`ingest:<path>:<type>:<name>`, `@volter/editor-threejs/adapter/ingest/structural-ids`'s
+ * `assignStructuralIds`) are baked ONCE at capture and are the key every
+ * editor surface addresses an object by — never touched here. But
+ * `IngestHierarchy` re-reads the LIVE `Object3D` tree every render
+ * (`adapter.hierarchy.node(id)`), and a live game can reorder or clone
+ * subtrees after capture, so the SAME baked id can legitimately show up in
+ * more than one place in a single walk — `EditorNode.id` alone is no longer
+ * a safe React key, and naively recursing `childIds` with no guard can loop
+ * forever if a stale/duplicated id ever points back at one of its own
+ * ancestors.
+ *
+ * Per-parent child cap, copied from `hierarchy-rows.ts`'s
+ * `flattenVisibleRows`/ `CHILD_CAP`/`MORE_ID_PREFIX` (same constants, no
+ * drift). Unlike first-party (which only caps in play mode), the adapter
+ * panel's tree is BY DEFINITION a live game scene graph, so `capEnabled`
+ * defaults to `false` here (matching this function's PRE-cap behavior
+ * byte-for-byte — every existing caller/test that doesn't pass the new params
+ * keeps working unchanged) and `IngestHierarchy` explicitly turns it on for
+ * the browse view. Search bypasses the cap by calling with `capEnabled=false`
+ * (D-C4) — the exact same "flatten UNCAPPED, filter flat" shape this module
+ * already used for search before the cap existed.
+ */
+
+import type { EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
+import { CHILD_CAP, MORE_ID_PREFIX } from './hierarchy-rows';
+
+/** One flattened, render-ready row over an ingested game's live hierarchy. */
+export interface HierarchyNodeRow {
+  readonly node: EditorNode;
+  readonly depth: number;
+  /**
+   * Render key material: the walk path (root index, then child index at
+   * each level) — NOT `node.id` alone. Stays unique across a render even
+   * when the id scheme collides, because it is derived from POSITION in
+   * the walk, not from the adapter's (potentially stale/duplicated) data.
+   */
+  readonly pathKey: string;
+  readonly hasChildren: boolean;
+  /** True when an ANCESTOR's `pathKey` is in the caller's collapsed-set —
+   *  i.e. this row is inside a collapsed subtree (F18). The row itself is
+   *  still included in the returned array (so a search can still find it);
+   *  the component filters it out when not searching. */
+  readonly hiddenByCollapse: boolean;
+  /** Present on a synthetic "… N more" row that reveals capped siblings
+   *  (D-C2) — `parentPathKey` is the capped parent's `pathKey`, `hidden` is
+   *  how many of its children are not shown. Never present on a real row. */
+  readonly more?: { readonly parentPathKey: string; readonly hidden: number };
+}
+
+/**
+ * Backstop against a childIds list this guard's own dedup somehow doesn't
+ * anticipate (e.g. a very deep but genuinely acyclic live tree) — ingested
+ * games are not expected to nest anywhere near this deep; this is a second,
+ * independent safety net, not the primary guard (see `visited` below).
+ */
+const MAX_DEPTH = 500;
+
+/** How many of a parent's children to walk (D-C1/D-C3) — split out of `walk`
+ *  below purely to keep that function's cognitive-complexity score down. */
+function childLimit(
+  capEnabled: boolean,
+  revealed: ReadonlyMap<string, number>,
+  parentPathKey: string,
+): number {
+  return capEnabled
+    ? Math.max(CHILD_CAP, revealed.get(parentPathKey) ?? CHILD_CAP)
+    : Number.POSITIVE_INFINITY;
+}
+
+/** The synthetic "… N more" row for a capped parent (D-C2) — a render-only
+ *  stub, never fed back to the adapter. Split out of `walk` below purely to
+ *  keep that function's cognitive-complexity score down. */
+function buildMoreRow(
+  parentPathKey: string,
+  depth: number,
+  parentId: string,
+  hiddenByCollapse: boolean,
+  hidden: number,
+): HierarchyNodeRow {
+  return {
+    node: {
+      id: `${MORE_ID_PREFIX}${parentPathKey}`,
+      label: '',
+      kind: 'object',
+      parentId,
+      childIds: [],
+    },
+    depth,
+    pathKey: `${parentPathKey}/__more__`,
+    hasChildren: false,
+    hiddenByCollapse,
+    more: { parentPathKey, hidden },
+  };
+}
+
+/**
+ * Flatten an ingest adapter's hierarchy into display rows.
+ *
+ * F14 cycle/dup guard: `visited` tracks every `node.id` already emitted in
+ * THIS walk. A live game reordering/cloning objects can make the same baked
+ * id reachable from more than one place (a real duplicate) or, in principle,
+ * from one of its own descendants (a cycle) — either way the id is stale
+ * data describing the CURRENT live scene, not a second logical node. The
+ * chosen semantics: render the first occurrence encountered (root-first,
+ * then depth-first child order) and silently skip every later one — no
+ * second row, and a cycle can never recurse forever. `collapsedKeys` is
+ * keyed by `pathKey`, not `node.id` (F18) — a walk-path is stable for "this
+ * position in the tree shape", which is what "collapsed" means to a user
+ * looking at the panel; keying by id would let a stale/reused id apply a
+ * collapse to the WRONG node after a live reorder, or fail to distinguish
+ * two positions that happen to share a duplicated id.
+ *
+ * D-C1/D-C3 cap: when `capEnabled`, each parent's children are limited to
+ * `max(CHILD_CAP, revealed.get(parentPathKey) ?? CHILD_CAP)` and a synthetic
+ * more-row is appended when some are hidden (D-C2). D-C5: children beyond
+ * the limit are never walked, so never added to `visited` — a duplicate id
+ * whose first structural occurrence was capped away still renders at its
+ * next reachable occurrence (the dedup guard's "once, not zero times"
+ * guarantee holds). D-C6: a COLLAPSED parent (its own `pathKey` is in
+ * `collapsedKeys`) contributes no child rows and no more-row at all when
+ * capped — the walk stops at the parent itself rather than descending and
+ * relying on `hiddenByCollapse` filtering, since a more-row would otherwise
+ * still need suppressing. Uncapped calls (search, D-C4) are unaffected:
+ * collapse only ever gates recursion when `capEnabled`, so a collapsed
+ * subtree's matches stay reachable when searching, exactly as before.
+ */
+export function flattenHierarchyRows(
+  hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>,
+  collapsedKeys: ReadonlySet<string>,
+  revealed: ReadonlyMap<string, number> = new Map(),
+  capEnabled = false,
+): HierarchyNodeRow[] {
+  const rows: HierarchyNodeRow[] = [];
+  const visited = new Set<string>();
+
+  const walk = (node: EditorNode, depth: number, pathKey: string, parentHidden: boolean): void => {
+    if (visited.has(node.id) || depth > MAX_DEPTH) return;
+    visited.add(node.id);
+
+    const hasChildren = node.childIds.length > 0;
+    rows.push({ node, depth, pathKey, hasChildren, hiddenByCollapse: parentHidden });
+
+    const isCollapsed = collapsedKeys.has(pathKey);
+    if (capEnabled && isCollapsed) return; // D-C6: nothing of a collapsed subtree renders.
+
+    const childHidden = parentHidden || isCollapsed;
+    const shown = Math.min(node.childIds.length, childLimit(capEnabled, revealed, pathKey));
+
+    for (let i = 0; i < shown; i++) {
+      const child = hierarchy.node(node.childIds[i]!);
+      if (child) walk(child, depth + 1, `${pathKey}.${i}`, childHidden);
+    }
+
+    if (capEnabled && node.childIds.length > shown) {
+      rows.push(
+        buildMoreRow(pathKey, depth + 1, node.id, childHidden, node.childIds.length - shown),
+      );
+    }
+  };
+
+  hierarchy.roots().forEach((root, i) => {
+    walk(root, 0, `r${i}`, false);
+  });
+  return rows;
+}
+
+/**
+ * Patch an uncapped structural snapshot after an identity-unique projection
+ * reports the parents whose direct child lists changed.
+ *
+ * Each changed parent's complete visible subtree is replaced in place. This
+ * preserves every unaffected row object and avoids asking the provider about
+ * the rest of a large world. Rebuilding the parent (not only its new child)
+ * is what preserves exact sibling order and walk-path keys after insert,
+ * remove, or reparent. `null` is the conservative answer whenever the delta
+ * cannot be related to the previous snapshot; the caller then takes the full
+ * {@link flattenHierarchyRows} path.
+ *
+ * This helper requires provider-unique ids. The live Three projector supplies
+ * that invariant when it supplies the parent delta; arbitrary hierarchy
+ * providers continue to use the full flattener and its duplicate-id guard.
+ */
+export function patchUniqueHierarchyRows(
+  hierarchy: Pick<HierarchyProvider, 'node'>,
+  previous: readonly HierarchyNodeRow[],
+  changedParentIds: ReadonlySet<string>,
+): HierarchyNodeRow[] | null {
+  if (changedParentIds.size === 0) return previous as HierarchyNodeRow[];
+
+  const rowIndexById = new Map<string, number>();
+  for (let index = 0; index < previous.length; index += 1) {
+    const row = previous[index]!;
+    if (!row.more) rowIndexById.set(row.node.id, index);
+  }
+
+  interface Replacement {
+    readonly start: number;
+    readonly end: number;
+    readonly row: HierarchyNodeRow;
+    readonly node: EditorNode;
+  }
+  const candidates: Replacement[] = [];
+  for (const id of changedParentIds) {
+    const start = rowIndexById.get(id);
+    const node = hierarchy.node(id);
+    // A removed internal parent is covered by its changed surviving ancestor.
+    // Validate that relationship below after all surviving candidates are known.
+    if (start === undefined || node === null) continue;
+    const row = previous[start]!;
+    let end = start + 1;
+    while (end < previous.length && previous[end]!.depth > row.depth) end += 1;
+    candidates.push({ start, end, row, node });
+  }
+  if (candidates.length === 0) return null;
+
+  candidates.sort((a, b) => a.start - b.start);
+  const replacements: Replacement[] = [];
+  for (const candidate of candidates) {
+    const ancestor = replacements.at(-1);
+    if (ancestor && candidate.start < ancestor.end) continue;
+    replacements.push(candidate);
+  }
+
+  // Every changed parent that existed in the previous snapshot must either be
+  // rebuilt itself or lie inside a rebuilt ancestor. Otherwise the delta is
+  // incomplete for this view (for example a decorator hid the raw parent).
+  for (const id of changedParentIds) {
+    const oldIndex = rowIndexById.get(id);
+    if (oldIndex === undefined) continue;
+    if (!replacements.some(({ start, end }) => oldIndex >= start && oldIndex < end)) return null;
+  }
+
+  const flattenSubtree = (replacement: Replacement): HierarchyNodeRow[] | null => {
+    const rows: HierarchyNodeRow[] = [];
+    const visited = new Set<string>();
+    let valid = true;
+    const walk = (node: EditorNode, depth: number, pathKey: string): void => {
+      if (!valid) return;
+      if (visited.has(node.id) || depth > MAX_DEPTH) {
+        valid = false;
+        return;
+      }
+      visited.add(node.id);
+      rows.push({
+        node,
+        depth,
+        pathKey,
+        hasChildren: node.childIds.length > 0,
+        hiddenByCollapse: false,
+      });
+      for (let childIndex = 0; childIndex < node.childIds.length; childIndex += 1) {
+        const child = hierarchy.node(node.childIds[childIndex]!);
+        if (child) walk(child, depth + 1, `${pathKey}.${String(childIndex)}`);
+      }
+    };
+    walk(replacement.node, replacement.row.depth, replacement.row.pathKey);
+    return valid ? rows : null;
+  };
+
+  const next = [...previous];
+  for (let index = replacements.length - 1; index >= 0; index -= 1) {
+    const replacement = replacements[index]!;
+    const rows = flattenSubtree(replacement);
+    if (rows === null) return null;
+    next.splice(replacement.start, replacement.end - replacement.start, ...rows);
+  }
+  return next;
+}
+
+/** Stable React key for a row — walk path + id, so it never collides even
+ *  when the underlying id scheme does (F14). */
+export function hierarchyRowKey(row: Pick<HierarchyNodeRow, 'pathKey' | 'node'>): string {
+  return `${row.pathKey}:${row.node.id}`;
+}
+
+/**
+ * The pure start/end row-index math for the hierarchy panel's
+ * scroll-windowed rendering. Kept here (not inlined in the component) for two
+ * reasons: it is unit-testable standalone with no React/jsdom involved, and a
+ * tamper test can `vi.mock` this ONE function to neutralize windowing (return
+ * the full range) and prove the render-bounding behavior actually depends on
+ * it, not on some other accidental cap.
+ *
+ * `overscan` extra rows are kept rendered on each side of the visible band
+ * so a fast scroll or keyboard nav doesn't flash empty space before the next
+ * paint catches up. `end` is clamped to `totalRows`; `start` is clamped to 0
+ * (never negative near the top of the list).
+ */
+export function hierarchyRowWindow(
+  totalRows: number,
+  scrollTop: number,
+  viewportPx: number,
+  rowH: number,
+  overscan: number,
+): { start: number; end: number } {
+  const start = Math.max(0, Math.floor(scrollTop / rowH) - overscan);
+  const visibleCount = Math.ceil(viewportPx / rowH) + overscan * 2;
+  const end = Math.min(totalRows, start + visibleCount);
+  return { start, end };
+}

package/src/hierarchy-panel-view.ts

@@ -0,0 +1,280 @@
+/**
+ * `editor.hierarchy()` — the machine door onto the hierarchy panel's ACTUAL
+ * rendered row tree.
+ *
+ * ## Why this publishes instead of re-deriving
+ *
+ * `inspection/active-subject.ts` answers "what is the inspector showing?" by
+ * calling the same composer the panel calls, with the same inputs, at the
+ * moment it is asked. That works because every one of the inspector's inputs is
+ * reachable from live state.
+ *
+ * The hierarchy panel's are not. Its final row list is a fold of the adapter's
+ * tree, the mark view, the internals reveal, the search term, the child cap,
+ * the selection scope, per-world hide flags, AND two pieces of state that live
+ * inside the component instance: the session expansion map (`useRef`) and the
+ * measured scroll window. A door that re-walked the adapter to "reconstruct"
+ * that list would be a SECOND row pipeline, free to disagree with the panel —
+ * and a door whose whole purpose is diagnosing the panel is worthless the
+ * moment it can disagree with it. That is not hypothetical: `editor.status()`'s
+ * `entities` facet (`authoring/shell-document-ops.ts`) walks the RAW adapter
+ * hierarchy with no marks, no internals folding and no document promotion, so
+ * it reports a tree the panel has never rendered — which is exactly why it
+ * could not surface a panel defect.
+ *
+ * So the panel PUBLISHES what it computed. The snapshot holds the panel's own
+ * `HierarchyNodeRow[]` and the panel's own predicates by reference — not copies, not
+ * re-derivations — and serialization happens only when the door is called, so a
+ * render that nobody reads costs one object allocation.
+ *
+ * ## What "mounted" means here
+ *
+ * The publish happens in an effect, so the snapshot describes a tree that has
+ * been COMMITTED to the DOM. With no panel mounted there is no snapshot and the
+ * door refuses by name rather than answering with an empty tree — a fabricated
+ * "the hierarchy is empty" is the anti-shim rule's failure on the one surface
+ * that exists to be believed. Because the commit is what publishes, a caller
+ * that MUTATES the panel (Expand/Collapse All) takes
+ * {@link nextHierarchyPanelSnapshot} before it acts and awaits it, so its ack
+ * means "the rows the next `hierarchy()` serializes are the rows this mutation
+ * produced" rather than "the mutation was requested".
+ */
+
+import type { HierarchyNodeRow } from './hierarchy-node-rows';
+
+/**
+ * What the panel hands over: its final rows plus the predicates it already
+ * evaluated them with. Every member is the panel's own — see this module's
+ * header for why nothing here is recomputed.
+ */
+export interface HierarchyPanelSnapshot {
+  /** The panel's final row list, in display order, AFTER search / cap /
+   *  collapse / scope / world-hide filtering — i.e. the rows a human scrolls. */
+  readonly rows: readonly HierarchyNodeRow[];
+  /** The slice actually in the DOM right now (virtualization window). */
+  readonly window: { readonly start: number; readonly end: number };
+  /** The active search term, or `null` when browsing. */
+  readonly searchTerm: string | null;
+  /** The row the panel is scoped into (double-clicked instance), or `null`. */
+  readonly scopeId: string | null;
+  /** The panel's own expansion verdict — session state, then the persisted
+   *  preference, then the shape/mark defaults. */
+  readonly isExpanded: (row: HierarchyNodeRow) => boolean;
+  /** True for a row that exists only because internals were revealed. */
+  readonly isInternal: (id: string) => boolean;
+  /** True for a row carrying `vgaiComponentRoot`. */
+  readonly isComponentRoot: (id: string) => boolean;
+  /** How many children this row's view FOLDED AWAY as implementation. */
+  readonly foldedInternalCount: (id: string) => number;
+  /** The panel's own Expand All action. Machine readers use the same mutation
+   *  as the toolbar, then read a later committed snapshot; they never bypass
+   *  collapse state by walking the adapter behind the panel. */
+  readonly expandAll: () => void;
+  /** The panel's own Collapse All action — the SAME toolbar button's other
+   *  half. It exists because Expand All alone is a one-way door: once a
+   *  machine reader expands, nothing through the product restores the tree's
+   *  rest state (the fold is written to this project's persisted preference,
+   *  and a chevron's own click is not drivable — `editor.document.click`
+   *  refuses editor chrome by name). A rest state the product cannot return
+   *  to is a rest state the product cannot certify. */
+  readonly collapseAll: () => void;
+}
+
+/** One serialized panel row. Nested, because the shape of the tree IS the
+ *  thing under diagnosis. */
+export interface SerializedHierarchyRow {
+  id: string;
+  label: string;
+  /** The dim type suffix the row prints (`Coin1 ·Coin`). */
+  typeLabel?: string;
+  role?: string;
+  depth: number;
+  /**
+   * Children the row's own view has — what opening the caret reveals. This is
+   * the PROJECTED count: implementation children folded by the mark view are
+   * not in it (they are in {@link internalChildCount}).
+   */
+  childCount: number;
+  /** Children folded away as implementation, reachable through "Reveal
+   *  Internals". Non-zero with `childCount: 0` is a row whose whole subtree is
+   *  machinery. */
+  internalChildCount: number;
+  /**
+   * Whether the panel renders a disclosure control on this row. THE
+   * load-bearing field: a row with children of any kind and
+   * `expandable: false` is a subtree the UI offers no way to reach.
+   */
+  expandable: boolean;
+  /** Only meaningful when {@link expandable}. */
+  expanded?: boolean;
+  /** Read-only, de-emphasized revealed-internal row. */
+  internal?: true;
+  /** Marked component-instance root. */
+  componentRoot?: true;
+  /** A synthetic "… N more" cap stub rather than a real node. */
+  more?: { hidden: number };
+  children?: readonly SerializedHierarchyRow[];
+}
+
+/** The whole panel, as data. */
+export interface SerializedHierarchyPanel {
+  /** Total rows in the panel's list (not just the windowed slice). */
+  rowCount: number;
+  /** The slice in the DOM; `end - start < rowCount` means scrolling reveals more. */
+  window: { start: number; end: number };
+  /** Present only while a search is filtering the tree. */
+  search?: string;
+  /** Present only while the panel is scoped into a subtree. */
+  scopeId?: string;
+  /** Which surface the rows belong to — a play-mode tree and an edit-mode tree
+   *  come from different adapters, and telling them apart is the first question
+   *  any hierarchy diagnosis asks. */
+  playState: string;
+  activeViewportTab: string;
+  roots: readonly SerializedHierarchyRow[];
+}
+
+// ------------------------------------------------------------ session state
+
+let published: HierarchyPanelSnapshot | null = null;
+
+/** Callers parked in {@link nextHierarchyPanelSnapshot}, settled by the next
+ *  publish (resolve) or by the panel going away (reject). */
+const waiters: Array<{
+  readonly resolve: (snapshot: HierarchyPanelSnapshot) => void;
+  readonly reject: (error: Error) => void;
+}> = [];
+
+/** Called by `GameHierarchy` after every commit. */
+export function publishHierarchyPanelSnapshot(snapshot: HierarchyPanelSnapshot): void {
+  published = snapshot;
+  if (waiters.length === 0) return;
+  for (const waiter of waiters.splice(0, waiters.length)) waiter.resolve(snapshot);
+}
+
+/**
+ * Resolve on the panel's NEXT published snapshot — i.e. the next React commit.
+ *
+ * A mutation through the snapshot's own actions (`expandAll`/`collapseAll`)
+ * only mutates a ref and schedules a re-render; the rows the door serializes
+ * are republished from the panel's effect. Take this promise BEFORE calling the
+ * action and await it after, and the mutation's ack lands on the committed
+ * tree. No timeout: the actions force a render unconditionally
+ * (`useReducer` increment — never a bail-out, even when the expansion map is
+ * unchanged), so a publish always follows, and a caller that would otherwise
+ * hang is instead rejected by {@link clearHierarchyPanelSnapshot}.
+ */
+export function nextHierarchyPanelSnapshot(): Promise<HierarchyPanelSnapshot> {
+  return new Promise<HierarchyPanelSnapshot>((resolve, reject) => {
+    waiters.push({ resolve, reject });
+  });
+}
+
+/** Called on unmount. Guarded so a remount's publish is never clobbered by the
+ *  outgoing instance's cleanup (effect cleanup runs after the next mount's
+ *  effect in a React remount). */
+export function clearHierarchyPanelSnapshot(snapshot: HierarchyPanelSnapshot): void {
+  if (published !== snapshot) return;
+  published = null;
+  if (waiters.length === 0) return;
+  // This cleanup is NOT unmount-only: the panel's publish effect depends on the
+  // snapshot object, which is fresh every render, so an ordinary update runs
+  // this clear and then the new publish back-to-back inside one commit. Only a
+  // real unmount leaves `published` null once that commit has drained, so the
+  // rejection is deferred one microtask and skipped if a publish arrived.
+  queueMicrotask(() => {
+    if (published !== null || waiters.length === 0) return;
+    for (const waiter of waiters.splice(0, waiters.length)) {
+      waiter.reject(
+        new Error(
+          'the hierarchy panel (GameHierarchy) unmounted before it published the mutated row tree, so the mutation cannot be acknowledged against a rendered tree. Open the Hierarchy panel in the workspace dock and retry.',
+        ),
+      );
+    }
+  });
+}
+
+/** `null` when no hierarchy panel is mounted. */
+export function hierarchyPanelSnapshot(): HierarchyPanelSnapshot | null {
+  return published;
+}
+
+/** Test-only reset for the module-level singleton. */
+export function __resetHierarchyPanelSnapshotForTest(): void {
+  published = null;
+  waiters.length = 0;
+}
+
+// -------------------------------------------------------------- serialization
+
+/**
+ * Turn the panel's flat, depth-tagged rows back into the nesting a reader sees.
+ *
+ * The flattener emits rows in display order with a `depth`, so a depth stack
+ * rebuilds the parenting exactly — including a search result set, whose depths
+ * jump (an ancestor may be filtered out), which the stack handles by popping to
+ * the nearest shallower row rather than inventing a parent.
+ */
+export function serializeHierarchyPanel(
+  snapshot: HierarchyPanelSnapshot,
+  mode: { readonly playState: string; readonly activeViewportTab: string },
+): SerializedHierarchyPanel {
+  const roots: SerializedHierarchyRow[] = [];
+  /** The open ancestor chain: `stack[i]` is the last row emitted at depth `i`. */
+  const stack: SerializedHierarchyRow[] = [];
+
+  for (const row of snapshot.rows) {
+    const serialized = serializeRow(row, snapshot);
+    while (stack.length > row.depth) stack.pop();
+    const parent = stack.length > 0 ? stack[stack.length - 1] : undefined;
+    if (parent === undefined) {
+      roots.push(serialized);
+    } else {
+      const children = parent.children as SerializedHierarchyRow[] | undefined;
+      if (children === undefined) parent.children = [serialized];
+      else children.push(serialized);
+    }
+    stack.push(serialized);
+  }
+
+  return {
+    rowCount: snapshot.rows.length,
+    window: { start: snapshot.window.start, end: snapshot.window.end },
+    ...(snapshot.searchTerm ? { search: snapshot.searchTerm } : {}),
+    ...(snapshot.scopeId ? { scopeId: snapshot.scopeId } : {}),
+    playState: mode.playState,
+    activeViewportTab: mode.activeViewportTab,
+    roots,
+  };
+}
+
+function serializeRow(
+  row: HierarchyNodeRow,
+  snapshot: HierarchyPanelSnapshot,
+): SerializedHierarchyRow {
+  const { node } = row;
+  if (row.more) {
+    return {
+      id: node.id,
+      label: `… ${row.more.hidden} more`,
+      depth: row.depth,
+      childCount: 0,
+      internalChildCount: 0,
+      expandable: false,
+      more: { hidden: row.more.hidden },
+    };
+  }
+  return {
+    id: node.id,
+    label: node.label,
+    ...(node.typeLabel === undefined ? {} : { typeLabel: node.typeLabel }),
+    ...(node.role === undefined ? {} : { role: node.role }),
+    depth: row.depth,
+    childCount: node.childIds.length,
+    internalChildCount: snapshot.foldedInternalCount(node.id),
+    expandable: row.hasChildren,
+    ...(row.hasChildren ? { expanded: snapshot.isExpanded(row) } : {}),
+    ...(snapshot.isInternal(node.id) ? { internal: true as const } : {}),
+    ...(snapshot.isComponentRoot(node.id) ? { componentRoot: true as const } : {}),
+  };
+}