@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/hierarchy-kind-icon.ts

@@ -0,0 +1,217 @@
+/**
+ * Hierarchy row glyphs. Canvas kinds used to fall through to a circle because
+ * KIND_ICON only named three-lane kinds — every Sprite/Text/Container looked
+ * the same.
+ *
+ * THE THREE OBJECT KINDS OWN THEIR NAMES, for the same reason
+ * `editorIcons.modeling` does (`components/primitives/editor-icons.ts` — read
+ * its docblock) and here the reason is COLOUR rather than shape. An icon set
+ * keys a glyph by `icon.iconName` and may give it a category TONE, so a tone
+ * on `cube` would tint EVERY site that asks for a cube — and measured in the
+ * live editor, the Blender set's `object` orange landed on the viewport
+ * header's Perspective/Orthographic dropdown (`Object3DDocumentToolbar.tsx`
+ * draws it with `faCube`) and on the transform-space toggle, neither of which
+ * is an object. `faLightbulb` and `faCamera` reuse the same way (the viewport
+ * lighting overlay, the camera view menu).
+ *
+ * Blender's evidence for the colour is the OUTLINER specifically — a row's
+ * type glyph — so the tone belongs to a name only the outliner asks for.
+ * The `icon` tuple stays Font Awesome's, so a set that does not carry these
+ * names paints exactly what it painted before.
+ */
+import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import {
+  faBookOpen,
+  faCamera,
+  faCircle,
+  faCircleDot,
+  faCirclePlay,
+  faCode,
+  faCube,
+  faDrawPolygon,
+  faFont,
+  faImage,
+  faLayerGroup,
+  faLightbulb,
+  faLink,
+  faList,
+  faObjectGroup,
+  faPuzzlePiece,
+  faSquare,
+  faSquareCheck,
+  faVideoSlash,
+  faVolumeHigh,
+} from '@fortawesome/free-solid-svg-icons';
+
+/** A definition under a name of OURS carrying Font Awesome's drawing until an
+ *  icon set supplies its own — the same three lines as `editor-icons.ts`'s
+ *  `meshGlyph`, kept local so this module's import closure stays FA-only. */
+function outlinerGlyph(iconName: string, source: IconDefinition): IconDefinition {
+  return { ...source, iconName: iconName as IconDefinition['iconName'] };
+}
+
+const OUTLINER_OBJECT = outlinerGlyph('outliner-object', faCube);
+const OUTLINER_LIGHT = outlinerGlyph('outliner-light', faLightbulb);
+const OUTLINER_CAMERA = outlinerGlyph('outliner-camera', faCamera);
+// The speaker is the header's mute button too (`HeaderTelemetry.tsx`), which is
+// exactly the reuse this module's docblock names: an outliner tone on the bare
+// `volume-high` would tint that control as well.
+const OUTLINER_AUDIO = outlinerGlyph('outliner-audio', faVolumeHigh);
+/**
+ * A DATABLOCK row, not an object row — the geometry a mesh carries
+ * (ARCHITECTURE-CORE §A model is
+ * data). Blender's Outliner draws it in the DATA green where the object above
+ * it is orange, which is the whole reason it gets a name of its own rather
+ * than reusing the rail's `properties-data`: the two are the same drawing but
+ * the two sites' STATES differ: the outliner composites its glyphs at α 0.80
+ * over the row, and so does the Properties rail's CLOSED tab, while its open
+ * tab paints the ink full. One ink, three states — the palette carries the
+ * ink and each site declares its own alpha (`theme.ts`'s category docblock
+ * carries the solve and the frames it was measured in).
+ */
+const OUTLINER_DATA = outlinerGlyph('outliner-data', faDrawPolygon);
+/**
+ * A MESH object's own mark. Blender's Outliner does not draw a cube for one:
+ * measured on `outliner.png`, the Cube row carries an apex-down triangle — the
+ * object-type sibling of the datablock's mark, in the object orange — while
+ * `outliner-object`'s cube stays for a generic three-object row that names no
+ * mesh. A set without the name draws Font Awesome's cube, exactly as before.
+ */
+const OUTLINER_MESH = outlinerGlyph('outliner-mesh', faCube);
+
+const KIND_ICON: Record<string, IconDefinition> = {
+  three: OUTLINER_OBJECT,
+  react: faCode,
+  canvas: faLayerGroup,
+  scene: faBookOpen,
+  mesh: OUTLINER_MESH,
+  'skinned-mesh': OUTLINER_MESH,
+  'mesh-data': OUTLINER_DATA,
+  // A MODEL DOCUMENT'S ROOT is the datablock, not an object carrying one
+  // (ARCHITECTURE-CORE §A model is data) — which is why `@volter/editor-blender` hangs a
+  // `mesh-data` row off it in the first place. These are the two kind names
+  // `source-object3d-authoring-adapter.ts` mints for that root, and they read
+  // the DATA glyph for the same reason `mesh-data` does. This is the "one
+  // line here and nothing else moves" the note below describes; the consumer
+  // that needed it is the Properties breadcrumb, whose glyph Blender takes
+  // from the datablock and never from the open tab.
+  'three-source': OUTLINER_DATA,
+  'model-asset': OUTLINER_DATA,
+  light: OUTLINER_LIGHT,
+  camera: OUTLINER_CAMERA,
+  audio: OUTLINER_AUDIO,
+  'reflection-probe': faCircleDot,
+  group: faObjectGroup,
+  object: faCircle,
+  component: faPuzzlePiece,
+  img: faImage,
+  a: faLink,
+  ul: faList,
+  ol: faList,
+  li: faList,
+  button: faSquare,
+  sprite: faImage,
+  animatedsprite: faCirclePlay,
+  nineslicesprite: faImage,
+  tilingsprite: faImage,
+  text: faFont,
+  graphics: faSquare,
+  container: faObjectGroup,
+};
+
+/**
+ * THE TWO RESTRICTION-COLUMN GLYPHS THAT ARE NOT THE EYE — Blender's Disable
+ * in Renders column (`outliner_draw.cc:1363-1384`). Names of OURS for the same
+ * reason the outliner marks above have them: the bare `camera` name is the
+ * viewport header's camera menu, and a skin that drew Blender's
+ * `restrict_render_*` mark under it would repaint that menu too.
+ */
+export const OUTLINER_RENDER_ON = outlinerGlyph('outliner-render-on', faCamera);
+export const OUTLINER_RENDER_OFF = outlinerGlyph('outliner-render-off', faVideoSlash);
+
+/**
+ * THE EXCLUDE COLUMN's pair — Blender's leftmost restriction column, drawn for
+ * `LayerCollection` rows (`outliner_draw.cc:1634-1653`). It asks for
+ * `ICON_NONE` on an icon toggle, which is how a boolean draws the WIDGET's own
+ * checkbox, so the marks are `checkbox_hlt` / `checkbox_dehlt` — named here the
+ * way the render pair is, because a bare `checkbox` name would repaint every
+ * checkbox in the editor.
+ */
+export const OUTLINER_EXCLUDE_ON = outlinerGlyph('outliner-exclude-on', faSquareCheck);
+export const OUTLINER_EXCLUDE_OFF = outlinerGlyph('outliner-exclude-off', faSquare);
+
+/**
+ * A `blender-` KIND NAMES ITS OWN GLYPH, and that is the whole rule.
+ *
+ * `@volter/editor-blender`'s Outliner rows carry Blender's own `ICON_*` per row
+ * (`tree_element_get_icon`, `outliner_draw.cc:2619-2945`) — 70-odd marks across
+ * the object types, the data types, the modifier and constraint families. A
+ * table here with one line per mark would be a transcription of Blender's
+ * switch maintained in a second place; the adapter already knows the name, so
+ * the kind IS the name (`blender-outliner-ob-mesh`, `blender-mod-subsurf`) and
+ * the icon SET decides whether it draws it. A set that does not carry the name
+ * falls through to Font Awesome's circle, exactly as any unknown kind does.
+ */
+const BLENDER_KIND = /^blender-[a-z0-9-]+$/;
+
+export function hierarchyKindIcon(
+  kind: string,
+  fallback: IconDefinition = faCircle,
+): IconDefinition {
+  const known = KIND_ICON[kind];
+  if (known) return known;
+  if (BLENDER_KIND.test(kind)) return outlinerGlyph(kind, fallback);
+  return fallback;
+}
+
+/**
+ * THE DATABLOCK KINDS — the rows Blender's Outliner hangs OFF an object rather
+ * than under it, and the one place this editor decides which those are.
+ *
+ * Measured on `outliner.png`: at rest every object row is COLLAPSED and carries
+ * its datablock as an inline glyph after the label, one cell to the right
+ * (Camera's at src x 288-327, Cube's at 263-302, Light's at 266-291 — the label
+ * ink ends at 246/222/218, so the gap is 40-41 device px, one 20-point cell
+ * every time). Expanding is what produces the child row.
+ *
+ * WHY A KIND LIST AND NOT A ROLE. The datablock row is `role: 'element'`
+ * and so is every ordinary JSX
+ * child in the DOM and React lanes — a rule keyed on the role would collapse
+ * those trees by default, which is a regression, not a transcription. The KIND
+ * is the adapter's own vocabulary and this module is already where the host
+ * reads it: `KIND_ICON` above gives `mesh-data` the DATA glyph because it is a
+ * datablock. A future `light-data`/`camera-data` adds one line here and
+ * nothing else moves.
+ *
+ * `EditorNode` gains no field for this. The kind is open by construction (the
+ * previous unit's ruling), so a new noun on the kernel object would buy
+ * nothing that the name the adapter already sends does not.
+ */
+const DATABLOCK_KINDS: ReadonlySet<string> = new Set([
+  'mesh-data',
+  // Blender's own DATA marks, which is exactly what
+  // `tree_element_get_icon_from_id` (`outliner_draw.cc:2479-2610`) answers for
+  // a non-object ID: the mark a Model document's rows carry for an object's
+  // data, its materials and its shape keys. The object marks
+  // (`blender-outliner-ob-*`) are deliberately NOT here — those are the row
+  // itself, not something hung off it.
+  'blender-material-data',
+  'blender-shapekey-data',
+  'blender-texture-data',
+  'blender-image-data',
+]);
+
+/** The prefixes of the same set that are keyed by a VALUE rather than a struct
+ *  — a light's lamp type and a probe's (`outliner_draw.cc:2508-2521`,
+ *  `:2578-2589`) — plus the `OUTLINER_DATA_*` family. */
+const DATABLOCK_KIND_PREFIXES: readonly string[] = [
+  'blender-outliner-data-',
+  'blender-light-',
+  'blender-lightprobe-',
+];
+
+export function isDatablockKind(kind: string | undefined): boolean {
+  if (kind === undefined) return false;
+  if (DATABLOCK_KINDS.has(kind)) return true;
+  return DATABLOCK_KIND_PREFIXES.some((prefix) => kind.startsWith(prefix));
+}

package/src/kit/hierarchy-menu-registry.ts

@@ -0,0 +1,67 @@
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+/**
+ * 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.
+ */
+
+
+export interface HierarchyMenuContext {
+  /** The row's node id (an `EditorNode.id` — format-neutral). */
+  readonly nodeId: string;
+  readonly store: ShellStore;
+}
+
+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/kit/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/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 };
+}