@volter/editor-core 0.5.57

package/src/hierarchy-projection.ts

@@ -0,0 +1,76 @@
+/**
+ * Project-authored hierarchy projection (D20).
+ *
+ * This is editor metadata, not runtime composition. `vgai.project.json.roots`
+ * declares adapter mounts; `vgai.project.json.authoring.hierarchy` only
+ * chooses how those roots are labelled and grouped in the authoring tree.
+ */
+
+export interface HierarchyProjectionGroup {
+  readonly id: string;
+  readonly label: string;
+  readonly roots: readonly string[];
+}
+
+export interface HierarchyProjection {
+  readonly rootLabels?: Readonly<Record<string, string>>;
+  readonly groups?: readonly HierarchyProjectionGroup[];
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Leniently read authoring metadata. Invalid entries are omitted so a typo in
+ * an optional projection can never make the game itself unopenable.
+ */
+export function parseHierarchyProjection(value: unknown): HierarchyProjection | undefined {
+  const source = record(value);
+  if (!source) return undefined;
+
+  const labelsSource = record(source['rootLabels']);
+  const labelEntries = labelsSource
+    ? Object.entries(labelsSource).flatMap(([id, label]): Array<[string, string]> => {
+        const normalizedId = id.trim();
+        const normalizedLabel = typeof label === 'string' ? label.trim() : '';
+        return normalizedId && normalizedLabel ? [[normalizedId, normalizedLabel]] : [];
+      })
+    : [];
+  const rootLabels = labelEntries.length > 0 ? Object.fromEntries(labelEntries) : undefined;
+
+  const groupIds = new Set<string>();
+  const groupEntries = Array.isArray(source['groups'])
+    ? source['groups'].flatMap((candidate): HierarchyProjectionGroup[] => {
+        const group = record(candidate);
+        const id = typeof group?.['id'] === 'string' ? group['id'].trim() : '';
+        const label = typeof group?.['label'] === 'string' ? group['label'].trim() : '';
+        const roots = Array.isArray(group?.['roots'])
+          ? group['roots'].flatMap((root): string[] => {
+              const normalized = typeof root === 'string' ? root.trim() : '';
+              return normalized ? [normalized] : [];
+            })
+          : [];
+        if (!id || !label || roots.length === 0 || groupIds.has(id)) return [];
+        groupIds.add(id);
+        return [{ id, label, roots: [...new Set(roots)] }];
+      })
+    : [];
+  const groups = groupEntries.length > 0 ? groupEntries : undefined;
+
+  if (!rootLabels && !groups) return undefined;
+  return {
+    ...(rootLabels ? { rootLabels } : {}),
+    ...(groups ? { groups } : {}),
+  };
+}
+
+/** Read the projection from a raw `vgai.project.json` config object. */
+export function hierarchyProjectionFromProjectConfig(
+  config: unknown,
+): HierarchyProjection | undefined {
+  const authoring = record(record(config)?.['authoring']);
+  return parseHierarchyProjection(authoring?.['hierarchy']);
+}

package/src/hierarchy-row-cache.ts

@@ -0,0 +1,243 @@
+/**
+ * What the hierarchy panel is allowed to REUSE between two renders, and the
+ * row index that makes a selection change cost `O(selection × depth)` instead
+ * of `O(nodes)`.
+ *
+ * THE DEFECT THIS EXISTS FOR (scale-speed baseline, 2026-08-19, 22 of 43
+ * offender rows): `GameHierarchySurface` re-renders on every store notify — it
+ * has to, because the highlight moves — and its render body rebuilds the whole
+ * row pipeline from `adapter.hierarchy`: one uncapped flatten of every node,
+ * the per-node first-open policy, a second capped flatten, and a per-row
+ * ancestor climb. On a 20 000-node world that is 100-430ms of main-thread
+ * block AFTER a `select` whose reply already went out in 3ms, and it is paid
+ * for a change that touched nothing the walk reads.
+ *
+ * The two slots below split that pipeline where its inputs actually split:
+ *
+ *   - {@link HierarchyRowCache.structural} holds everything derived from the
+ *     TREE alone. Its key carries the store's `contentVersion` and the
+ *     adapter's structural notification epoch. The store version stands
+ *     still for a selection-only notify and moves for every other mutation
+ *     (see `EditorShellStore.contentVersion`) — including the adapter's own
+ *     `notifyIngestEdit` on a live structural change, which is what makes a
+ *     late-arriving subtree invalidate this on the tick it lands.
+ *   - {@link HierarchyRowCache.collapsed} holds the FOLD projected onto the
+ *     tree — the set of row paths that are collapsed right now. Deriving it
+ *     scans every structural row, so it is `O(nodes)`; its inputs are the tree
+ *     and the fold, and SELECTION IS NOT ONE OF THEM. It has its own slot
+ *     because the browse view below keys on the reveal a selection opens, and
+ *     folding that `O(nodes)` scan into the same slot made every click pay it.
+ *   - {@link HierarchyRowCache.browse} holds the capped/collapsed/searched
+ *     view. It keys on the structural value BY IDENTITY plus the fold, scope,
+ *     search and reveal state — so a selection that reveals nothing new reuses
+ *     it, and one that does reveal something rebuilds it.
+ *
+ * Each slot holds ONE entry. The panel renders one tree at a time, and a
+ * one-entry memo cannot leak: the moment the key moves, the old value is
+ * dropped. Keys are compared element-wise with `Object.is`, so every entry
+ * must be a primitive or a stable reference — never a freshly built object
+ * (a `Set`/`Map` built per render would never compare equal and would make
+ * the cache a pure cost). Signatures are the way to put a collection in a key.
+ */
+
+import type { HierarchyNodeRow } from './hierarchy-node-rows';
+
+/** Element-wise `Object.is` over two key tuples. */
+function sameKey(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (!Object.is(a[i], b[i])) return false;
+  return true;
+}
+
+/** One memo slot: the last key it computed for, and the value it produced. */
+class Slot<V> {
+  #key: readonly unknown[] | null = null;
+  #value: V | undefined;
+  /** How many times `compute` actually ran. Read by tests; never by product code. */
+  computeCount = 0;
+
+  get current(): V | undefined {
+    return this.#value;
+  }
+
+  read(key: readonly unknown[], compute: (previous: V | undefined) => V): V {
+    if (this.#key !== null && sameKey(this.#key, key)) return this.#value as V;
+    const value = compute(this.#value);
+    this.#key = key;
+    this.#value = value;
+    this.computeCount += 1;
+    return value;
+  }
+}
+
+/**
+ * The panel's two memo slots. Held in a `useRef` (never module state, so it
+ * cannot leak between editor sessions — the same stance `TransformLockCache`
+ * takes).
+ */
+export class HierarchyRowCache<Structural, Browse, Collapsed = unknown> {
+  readonly #structural = new Slot<Structural>();
+  readonly #collapsed = new Slot<Collapsed>();
+  readonly #browse = new Slot<Browse>();
+  /**
+   * `useDeferredValue` can render 11, then speculatively render 10, then catch
+   * up to 12. A render-time one-slot memo must not let that backward key
+   * replace 11 as the predecessor for 12's exact structural delta.
+   */
+  #structuralAdapter: unknown;
+  #structuralVersion = Number.NEGATIVE_INFINITY;
+
+  /**
+   * The tree-only half. `key` must name the adapter identity, the store's
+   * `contentVersion`, and any adapter-owned structural notification epoch;
+   * nothing in it may move for a selection change.
+   */
+  structural(
+    key: readonly unknown[],
+    compute: (previous: Structural | undefined) => Structural,
+  ): Structural {
+    const [adapter, version] = key;
+    if (
+      adapter === this.#structuralAdapter &&
+      typeof version === 'number' &&
+      version < this.#structuralVersion &&
+      this.#structural.current !== undefined
+    ) {
+      return this.#structural.current;
+    }
+    const value = this.#structural.read(key, compute);
+    if (adapter !== this.#structuralAdapter) {
+      this.#structuralAdapter = adapter;
+      this.#structuralVersion = Number.NEGATIVE_INFINITY;
+    }
+    if (typeof version === 'number') {
+      this.#structuralVersion = Math.max(this.#structuralVersion, version);
+    }
+    return value;
+  }
+
+  /**
+   * The fold-only half. `key` must START with the structural value itself and
+   * carry the fold generation/scope — and, like {@link structural}, nothing a
+   * selection moves.
+   */
+  collapsed(
+    key: readonly unknown[],
+    compute: (previous: Collapsed | undefined) => Collapsed,
+  ): Collapsed {
+    return this.#collapsed.read(key, compute);
+  }
+
+  /**
+   * The capped/collapsed/searched half. `key` must START with the structural
+   * value itself, so a rebuilt tree can never be viewed through a stale
+   * browse result.
+   */
+  browse(key: readonly unknown[], compute: (previous: Browse | undefined) => Browse): Browse {
+    return this.#browse.read(key, compute);
+  }
+
+  /** How many times each slot re-derived. Test/instrumentation only. */
+  get counts(): { structural: number; collapsed: number; browse: number } {
+    return {
+      structural: this.#structural.computeCount,
+      collapsed: this.#collapsed.computeCount,
+      browse: this.#browse.computeCount,
+    };
+  }
+}
+
+// --------------------------------------------------------------- row index
+
+/**
+ * Where every row sits, indexed both ways.
+ *
+ * Built once per structural walk and cached with it. Both selection-driven
+ * derivations below used to SCAN every row (and `selectedAncestorNodeIds`
+ * additionally built an N-entry `Map` of its own) on every render, which is
+ * `O(nodes)` work whose answer is about a handful of selected ids.
+ */
+export interface RowPathIndex {
+  /** `pathKey` → node id, for every real (non-`more`) row. */
+  readonly nodeIdByPathKey: ReadonlyMap<string, string>;
+  /** node id → every `pathKey` that node is rendered at. A live tree can reach
+   *  one id from more than one place; the flattener keeps the first, but the
+   *  index keeps them all so nothing depends on which walk order found it. */
+  readonly pathKeysByNodeId: ReadonlyMap<string, readonly string[]>;
+}
+
+export function indexRowPaths(rows: readonly HierarchyNodeRow[]): RowPathIndex {
+  const nodeIdByPathKey = new Map<string, string>();
+  const pathKeysByNodeId = new Map<string, string[]>();
+  for (const row of rows) {
+    if (row.more) continue;
+    nodeIdByPathKey.set(row.pathKey, row.node.id);
+    const existing = pathKeysByNodeId.get(row.node.id);
+    if (existing) existing.push(row.pathKey);
+    else pathKeysByNodeId.set(row.node.id, [row.pathKey]);
+  }
+  return { nodeIdByPathKey, pathKeysByNodeId };
+}
+
+/** Every strict-ancestor path of `pathKey`, outermost first. */
+export function ancestorPathKeys(pathKey: string): string[] {
+  const parts = pathKey.split('.');
+  const ancestors: string[] = [];
+  for (let i = 1; i < parts.length; i++) ancestors.push(parts.slice(0, i).join('.'));
+  return ancestors;
+}
+
+/** The node ids of every ancestor of every selected row — the branch selection
+ *  reveal opens. `O(selection × depth)`. */
+export function selectedAncestorNodeIds(
+  index: RowPathIndex,
+  selectedIds: ReadonlySet<string>,
+): Set<string> {
+  const ids = new Set<string>();
+  for (const selected of selectedIds) {
+    for (const pathKey of index.pathKeysByNodeId.get(selected) ?? []) {
+      for (const ancestor of ancestorPathKeys(pathKey)) {
+        const id = index.nodeIdByPathKey.get(ancestor);
+        if (id) ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+/** How many children each ancestor of a selected row must show for that row to
+ *  survive the browse-view child cap. `O(selection × depth)`. */
+export function selectedRevealCounts(
+  index: RowPathIndex,
+  selectedIds: ReadonlySet<string>,
+): Map<string, number> {
+  const revealed = new Map<string, number>();
+  for (const selected of selectedIds) {
+    for (const pathKey of index.pathKeysByNodeId.get(selected) ?? []) {
+      const parts = pathKey.split('.');
+      let parent = parts[0]!;
+      for (let i = 1; i < parts.length; i++) {
+        const childIndex = Number(parts[i]);
+        if (Number.isFinite(childIndex)) {
+          revealed.set(parent, Math.max(revealed.get(parent) ?? 0, childIndex + 1));
+        }
+        parent = `${parent}.${parts[i]}`;
+      }
+    }
+  }
+  return revealed;
+}
+
+/**
+ * A stable, order-independent string for a reveal map, so it can sit in a memo
+ * key that is compared with `Object.is`. Reveal maps are small (one entry per
+ * ancestor of a selected/expanded row), which is what makes a signature the
+ * right shape here rather than a version counter.
+ */
+export function revealSignature(revealed: ReadonlyMap<string, number>): string {
+  if (revealed.size === 0) return '';
+  return [...revealed]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([pathKey, count]) => `${pathKey}=${String(count)}`)
+    .join(',');
+}

package/src/hierarchy-row-model.ts

@@ -0,0 +1,308 @@
+/**
+ * Pure row-model math for the hierarchy panel.
+ *
+ * Four questions a row needs answered, all extracted here so they are unit
+ * testable without a DOM, an adapter session, or a live source tree:
+ *
+ * 1. **Is this row a component instance, and what is its type?** The
+ *    adapter already computes `EditorNode.typeLabel`; the row just needs to
+ *    know when to print it. Detached `#n` pockets deliberately carry no
+ *    `typeLabel` — a pocket must not impersonate the `<Enemy>` that
+ *    rendered it — so "has a typeLabel AND is a component row" is the whole
+ *    rule and no special-casing of pockets is needed here.
+ * 2. **Is every transform channel refused, and with what sentence?**
+ *    The adapter's `reason` is the ONE canonical text (doctrine rule 2): the
+ *    hierarchy tooltip, the inspector field, and the gizmo-denial hint all
+ *    show this exact string, never a paraphrase. So this module NEVER writes
+ *    a reason of its own — it only forwards the adapter's.
+ * 3. **Does this row have authorability warnings, and what do they say?**
+ *    Same rule as H2, one step stronger: the diagnostic message is written by
+ *    the analyzer that found the problem and is shown VERBATIM. This module
+ *    picks no wording, adds no severity of its own and truncates nothing — it
+ *    counts and newline-joins.
+ * 4. **What may this row DO?** One predicate ({@link rowAffordances}) that
+ *    every gate in the panel consults, instead of five copies of
+ *    `!isStructural && !isInternal` drifting apart.
+ *
+ * Cost note: `R3fSourceAuthoringAdapter.editability` re-analyzes JSX
+ * attributes from cached source text on every call (string scan + parse). It
+ * is NOT free per render, which is why {@link transformLockSummary}
+ * short-circuits on the first WRITABLE channel (the overwhelmingly common
+ * case costs exactly one probe, not three) and why {@link TransformLockCache}
+ * exists at all.
+ */
+
+import type { EditorNode, TransformChannel, TransformEditability } from '@volter/editor-project/adapter';
+
+/** The three channels a lock glyph summarizes, in probe order. */
+const CHANNELS: readonly TransformChannel[] = ['position', 'rotation', 'scale'];
+
+// ------------------------------------------------------------------ H1
+
+export interface RowIdentity {
+  /** The row's own name — unchanged, and still the ONLY thing search matches. */
+  readonly label: string;
+  /** The component type to print as a dim suffix, or null for a plain row. */
+  readonly typeSuffix: string | null;
+}
+
+/**
+ * H1 — `EnemyBravo ·Enemy`. A row earns the type suffix (and the instance
+ * accent tint that travels with it) only when it BOTH represents a component
+ * instance (`role: 'component'`) and the adapter told us its type.
+ */
+export function rowIdentity(node: Pick<EditorNode, 'label' | 'role' | 'typeLabel'>): RowIdentity {
+  const isInstance = node.role === 'component' && !!node.typeLabel;
+  return { label: node.label, typeSuffix: isInstance ? node.typeLabel! : null };
+}
+
+// ------------------------------------------------------------------ H2
+
+export interface TransformLockSummary {
+  /** True only when position, rotation AND scale are all refused. */
+  readonly locked: boolean;
+  /** The position channel's verbatim adapter reason (never rewritten here). */
+  readonly reason?: string;
+}
+
+/** Shared immutable "nothing to say" result — avoids per-row allocation. */
+export const UNLOCKED: TransformLockSummary = { locked: false };
+
+/** One channel probe. `undefined` means the adapter declares no editability
+ *  opinion at all, which every consumer in this editor reads as writable
+ *  (`editability?.(…)?.writable ?? true`). */
+export type EditabilityProbe = (channel: TransformChannel) => TransformEditability | undefined;
+
+/**
+ * H2 — collapse the three channels into one row-level verdict. Short-circuits
+ * on the first writable channel, so an ordinary movable row pays for ONE
+ * `editability` call.
+ *
+ * The surfaced reason is the POSITION channel's, matching the design record:
+ * per-channel detail stays inspector-only, and the row shows one sentence.
+ */
+export function transformLockSummary(probe: EditabilityProbe): TransformLockSummary {
+  let positionReason: string | undefined;
+  for (const channel of CHANNELS) {
+    const verdict = probe(channel);
+    if (!verdict || verdict.writable) return UNLOCKED;
+    if (channel === 'position') positionReason = verdict.reason;
+  }
+  return positionReason === undefined ? { locked: true } : { locked: true, reason: positionReason };
+}
+
+/** The minimal adapter surface {@link TransformLockCache} needs — structurally
+ *  satisfied by `AuthoringAdapter` without importing it. */
+export interface EditabilitySource {
+  readonly transforms?:
+    | {
+        readonly editability?:
+          | ((id: string, channel: TransformChannel) => TransformEditability)
+          | undefined;
+      }
+    | undefined;
+}
+
+/**
+ * Memoized {@link transformLockSummary} per row id.
+ *
+ * INVALIDATION KEY: `(source identity, version)`. `version` is supplied by the
+ * caller and must be a monotonically increasing counter that advances whenever
+ * anything the adapter's `editability` reads could have changed. `GameHierarchy`
+ * passes `store.getSnapshot() + adapterVersion` — the shell store's `_version`
+ * (bumped by `_notify()`, which EVERY source-write path funnels through via
+ * `notifyIngestEdit()`) plus its own adapter-subscription counter. Both are
+ * monotone, so their sum is monotone, and a stale entry therefore cannot
+ * survive a source edit: the edit bumps `_version` before the re-render that
+ * would read the cache.
+ *
+ * The cache also clears on ADAPTER SWITCH (the `source !== this.source`
+ * check), so ids minted by one adapter can never answer for another's.
+ */
+export class TransformLockCache {
+  private entries = new Map<string, TransformLockSummary>();
+  private source: EditabilitySource | null = null;
+  private version = Number.NaN;
+  /** Test-visible: how many times the adapter was actually probed. */
+  private computed = 0;
+
+  get computeCount(): number {
+    return this.computed;
+  }
+
+  summaryFor(source: EditabilitySource, version: number, id: string): TransformLockSummary {
+    if (this.source !== source || this.version !== version) {
+      this.entries.clear();
+      this.source = source;
+      this.version = version;
+    }
+    const cached = this.entries.get(id);
+    if (cached) return cached;
+    this.computed++;
+    const editability = source.transforms?.editability;
+    const summary = editability
+      ? transformLockSummary((channel) => editability(id, channel))
+      : UNLOCKED;
+    this.entries.set(id, summary);
+    return summary;
+  }
+}
+
+// ------------------------------------------------------------------ H6
+
+/** What a row is allowed to do. Every field is a REFUSAL gate, never a
+ *  capability claim: `true` means "this row model does not stand in the way",
+ *  and the adapter's own provider/value probes still decide whether the
+ *  affordance renders at all (a `document` row has no `name` path, so it never
+ *  renames regardless of what this says). */
+export interface RowAffordances {
+  /** Reparent-by-drag. */
+  readonly draggable: boolean;
+  /** Inline rename (double-click) and the Rename menu item. */
+  readonly renamable: boolean;
+  /** ANY write: create/duplicate/delete/group, the visibility eye, the lock
+   *  toggle, the entity-asset save. One flag, because H6's rule is not
+   *  per-operation — a revealed internal has no writable surface at all. */
+  readonly writable: boolean;
+  /** Whether the row's label participates in hierarchy search. */
+  readonly searchable: boolean;
+}
+
+const ORDINARY_ROW: RowAffordances = {
+  draggable: true,
+  renamable: true,
+  writable: true,
+  searchable: true,
+};
+const STRUCTURAL_ROW: RowAffordances = {
+  draggable: false,
+  renamable: false,
+  writable: true,
+  searchable: true,
+};
+/**
+ * H6 — a revealed internal. Non-writable BY CONSTRUCTION, not by policy: it is
+ * a rendered part of a component's output with no authored source identity, so
+ * there is nothing for a rename/reparent/delete to write to. Selection stays
+ * open (the id resolves, the inspector shows what it honestly can, and H2's
+ * lock-with-reason sentence explains the refusal); search is closed, because a
+ * `mixamorig:Spine` match across four enemies buries every real row.
+ */
+const INTERNAL_ROW: RowAffordances = {
+  draggable: false,
+  renamable: false,
+  writable: false,
+  searchable: false,
+};
+
+/**
+ * The ONE gate for "may this row be written to / dragged / found by search".
+ *
+ * `structural` keeps its pre-H6 meaning exactly (world groups, organization
+ * rows, root-group members, and the `STRUCTURAL_ROLES` set): non-draggable,
+ * with its write items gated by the adapter probes the panel already runs.
+ * `internal` is the new, stronger state and it wins over everything.
+ */
+export function rowAffordances(row: {
+  readonly structural: boolean;
+  readonly internal: boolean;
+}): RowAffordances {
+  if (row.internal) return INTERNAL_ROW;
+  return row.structural ? STRUCTURAL_ROW : ORDINARY_ROW;
+}
+
+// ------------------------------------------------------------------ H5
+
+/**
+ * The two fields a row badge needs from one diagnostic. Structurally satisfied
+ * by `R3fAuthoringDiagnostic` — declared narrowly here so the hierarchy never
+ * imports an R3F/ui-source type (the same contract-only rule H2's
+ * {@link EditabilitySource} and H3's `InstanceSourceLocator` follow).
+ */
+export interface RowDiagnostic {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface RowWarningBadge {
+  /** How many diagnostics this row carries — always ≥ 1 when a badge exists. */
+  readonly count: number;
+  /** Every message, VERBATIM and newline-joined, in the order the adapter
+   *  returned them. The badge's tooltip is this string and nothing else. */
+  readonly tooltip: string;
+  /** The codes, for the badge's `data-` attribute (a test can name the exact
+   *  finding without matching on prose that is allowed to be reworded). */
+  readonly codes: readonly string[];
+}
+
+/**
+ * H5 — collapse a row's diagnostics into its badge, or `null` for the
+ * overwhelmingly common "nothing to warn about" row.
+ *
+ * The verbatim rule is the point: doctrine rule 2 says the analyzer's sentence
+ * is the ONE canonical text, so multiple findings are STACKED (newline-joined),
+ * never summarized into "3 problems" and never truncated. A row with two
+ * warnings shows both sentences.
+ */
+export function rowWarningBadge(
+  diagnostics: readonly RowDiagnostic[] | undefined | null,
+): RowWarningBadge | null {
+  if (!diagnostics || diagnostics.length === 0) return null;
+  return {
+    count: diagnostics.length,
+    tooltip: diagnostics.map((diagnostic) => diagnostic.message).join('\n'),
+    codes: diagnostics.map((diagnostic) => diagnostic.code),
+  };
+}
+
+/** The minimal adapter surface {@link RowWarningCache} needs — structurally
+ *  satisfied by `CompositeAuthoringAdapter`/`R3fSourceAuthoringAdapter` without
+ *  importing either, and honestly absent on every adapter that runs no source
+ *  analyzer (which then shows no badges, rather than fabricated ones). */
+export interface RowDiagnosticsSource {
+  readonly diagnosticsFor?: ((id: string) => readonly RowDiagnostic[] | undefined) | undefined;
+}
+
+/**
+ * Memoized {@link rowWarningBadge} per row id, with the SAME invalidation
+ * contract as {@link TransformLockCache} — `(source identity, version)`, where
+ * `GameHierarchy` passes the same `store.getSnapshot() + adapterVersion` key to
+ * both.
+ *
+ * That key is exactly right for H5 and not by coincidence: diagnostics arrive
+ * on the OID index, and the R3F adapter's `refreshSourceState()` calls
+ * `store.notifyIngestEdit()` the moment a new index lands — which bumps the
+ * store `_version` that is half this key. So a fresh index invalidates these
+ * badges by construction, on the same tick, through the path every source-write
+ * and HMR remount already funnels through.
+ *
+ * Worth caching even though the adapter's own lookup is two map reads: on a
+ * composite it is a `route(id)` ownership walk, and the badge object plus its
+ * joined tooltip string would otherwise be reallocated for every row on every
+ * render.
+ */
+export class RowWarningCache {
+  private entries = new Map<string, RowWarningBadge | null>();
+  private source: RowDiagnosticsSource | null = null;
+  private version = Number.NaN;
+  /** Test-visible: how many times the adapter was actually probed. */
+  private computed = 0;
+
+  get computeCount(): number {
+    return this.computed;
+  }
+
+  badgeFor(source: RowDiagnosticsSource, version: number, id: string): RowWarningBadge | null {
+    if (this.source !== source || this.version !== version) {
+      this.entries.clear();
+      this.source = source;
+      this.version = version;
+    }
+    const cached = this.entries.get(id);
+    if (cached !== undefined) return cached;
+    this.computed++;
+    const badge = source.diagnosticsFor ? rowWarningBadge(source.diagnosticsFor(id)) : null;
+    this.entries.set(id, badge);
+    return badge;
+  }
+}

package/src/hierarchy-rows.ts

@@ -0,0 +1,11 @@
+/**
+ * Hierarchy child-cap constants.
+ *
+ * The hierarchy panel flattens the ADAPTER's `EditorNode` tree through
+ * `hierarchy-node-rows.ts`. This module holds only the two row-cap
+ * constants, shared with that flattener so every consumer caps identically.
+ */
+
+/** Max children shown per parent before a "… N more" row (when capping is on). */
+export const CHILD_CAP = 20;
+export const MORE_ID_PREFIX = '__more__:';