@volter/editor-core 0.5.57

package/src/hierarchy-expansion-state.ts

@@ -0,0 +1,80 @@
+/**
+ * Project-scoped hierarchy expansion preferences.
+ *
+ * Expansion belongs to an authored node's stable adapter id, not to its
+ * current row index. That lets the same preference survive an edit/live
+ * adapter replacement (Play/Stop) and ordinary React remounts. The project
+ * scope prevents common ids such as `game` or `root` leaking between games.
+ *
+ * Only explicit user choices are stored. A node with no entry follows the
+ * hierarchy's current shallow-open default, so changing the projection does
+ * not require a migration of a fully materialized tree state.
+ */
+
+/** The section of the project-local document this module owns. */
+const SECTION = 'hierarchyExpansion';
+
+import {
+  projectLocalSection,
+  projectLocalStateReady,
+  writeProjectLocalSection,
+} from './project-local-state';
+
+type ProjectPreferences = Map<string, boolean>;
+
+const preferences = new Map<string, ProjectPreferences>();
+let hydrated = false;
+
+function hydrate(): void {
+  if (hydrated) return;
+  if (!projectLocalStateReady()) return;
+  hydrated = true;
+  const parsed = projectLocalSection<Record<string, Record<string, boolean>>>(SECTION) ?? {};
+  for (const [projectId, nodes] of Object.entries(parsed)) {
+    preferences.set(projectId, new Map(Object.entries(nodes)));
+  }
+}
+
+function persist(): void {
+  const serialized: Record<string, Record<string, boolean>> = {};
+  for (const [projectId, nodes] of preferences) {
+    serialized[projectId] = Object.fromEntries(nodes);
+  }
+  writeProjectLocalSection(SECTION, serialized);
+}
+
+export function hierarchyExpansionPreference(
+  projectId: string,
+  nodeId: string,
+): boolean | undefined {
+  hydrate();
+  return preferences.get(projectId)?.get(nodeId);
+}
+
+/** Apply a whole branch/view operation with one storage write. */
+export function setHierarchyExpansionPreferences(
+  projectId: string,
+  entries: Iterable<readonly [nodeId: string, expanded: boolean]>,
+): void {
+  hydrate();
+  let project = preferences.get(projectId);
+  if (!project) {
+    project = new Map();
+    preferences.set(projectId, project);
+  }
+  for (const [nodeId, expanded] of entries) project.set(nodeId, expanded);
+  persist();
+}
+
+/** Return every node in one project to the shallow first-open policy. */
+export function clearHierarchyExpansionPreferences(projectId: string): void {
+  hydrate();
+  preferences.delete(projectId);
+  persist();
+}
+
+/** Test-only reset for this process (the in-memory map; the document is untouched). */
+export function _resetHierarchyExpansionPreferencesForTest(): void {
+  preferences.clear();
+  hydrated = true;
+}

package/src/hierarchy-header-slot.ts

@@ -0,0 +1,52 @@
+/**
+ * The Hierarchy panel's controls do not belong to a row of their own.
+ *
+ * Blender's Outliner header is ONE row: the editor-type selector, the
+ * display-mode selector, the search field, the filter popover and the
+ * new-collection button all sit on the same strip, and the tree starts
+ * directly under it. Ours had grown three rows — the dock group's tab strip
+ * (Content · Hierarchy · Library, which IS Blender's editor-type selector),
+ * a provenance breadcrumb, and a search row — for one panel's header.
+ *
+ * The tab strip is the row that stays, so the controls move ONTO it: this
+ * module is the seam. The dock's `rightHeaderActionsComponent` publishes the
+ * element it renders for the group whose ACTIVE panel is the Hierarchy
+ * (`frame/bridge.tsx`'s outliner part), and `components/GameHierarchy.tsx`
+ * portals its controls into it.
+ *
+ * It is a SLOT, not a control registry: the panel keeps owning its search
+ * term, its expansion verbs and its Create menu, and nothing about them is
+ * republished through module state. A host that renders the panel without a
+ * dock — the design-system stories, a bounded host — publishes no element,
+ * and the panel falls back to rendering its own toolbar row inline. That
+ * fallback is the reason this is a DOM slot and not a props channel: there is
+ * exactly one implementation of the controls either way.
+ */
+
+let slot: HTMLElement | null = null;
+const listeners = new Set<() => void>();
+
+export function hierarchyHeaderSlot(): HTMLElement | null {
+  return slot;
+}
+
+export function subscribeHierarchyHeaderSlot(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setHierarchyHeaderSlot(element: HTMLElement | null): void {
+  if (slot === element) return;
+  slot = element;
+  for (const listener of listeners) listener();
+}
+
+/** Clear only if THIS element is still the published one — a dock group that
+ *  unmounts after its successor has already claimed the slot would otherwise
+ *  blank a live header. */
+export function clearHierarchyHeaderSlot(element: HTMLElement | null): void {
+  if (slot !== element) return;
+  setHierarchyHeaderSlot(null);
+}

package/src/hierarchy-internals.ts

@@ -0,0 +1,197 @@
+/**
+ * "reveal internals, read-only". Godot's Editable Children, minus the editing.
+ *
+ * WHAT THIS IS. `R3fSourceAuthoringAdapter.projectedChildren` surfaces only
+ * CROSS-BOUNDARY children: an instance's own host nodes and its unstamped model
+ * internals (bones, GLTF meshes) are "traversed but not surfaced", so an
+ * `<Enemy>` reads as a leaf even though it rendered a 60-bone rig. Everything
+ * needed to show that rig already exists — `indexGraph` mints a path-keyed id
+ * for every non-helper object and `hierarchy.node(id)` describes it — so this
+ * module adds no identity machinery. It adds a VIEW: a decorator over the
+ * adapter's `HierarchyProvider` that appends the hidden children of the ids the
+ * author revealed, and answers which ids it minted rows for.
+ *
+ * WHY A DECORATOR AND NOT A NEW FLATTENER. `flattenHierarchyRows` walks
+ * `roots()`/`node(id).childIds`; virtualization, the child cap, collapse,
+ * selection-reveal and the search filter are all layered on TOP of that one
+ * walk. Injecting internals INTO the provider means every one of those keeps
+ * working untouched — a revealed skeleton is windowed, capped and collapsed by
+ * the same code as everything else, and no second row pipeline exists to drift.
+ *
+ * WHY THE STATE IS SESSION-ONLY. Reveal is deliberately NOT written to
+ * `hierarchy-expansion-state.ts` (which persists per project in localStorage):
+ * a skeleton that reappears on every project open is noise in the panel the
+ * author needs most, and unlike a normal fold it is not a statement about the
+ * authored tree at all — it is a temporary "let me look inside this". It lives
+ * in a module-level Set for the life of the tab, cleared on project switch by
+ * nothing at all, because ids are project-scoped (`r3f:<worldId>:<oid>`) and a
+ * stale id simply never matches.
+ *
+ * READ-ONLY IS ENFORCED ELSEWHERE, ON PURPOSE: this module only says WHICH rows
+ * are internal; `hierarchy-row-model.ts`'s `rowAffordances` is the single
+ * predicate that turns that into "no drag, no rename, no write, no search".
+ */
+
+import type { EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
+
+/** The (optional, structural) adapter capability H6 needs — the same
+ *  contract-free probe shape H3's `InstanceSourceLocator` and H5's
+ *  `RowDiagnosticsSource` use, so no adapter is forced to implement it and no
+ *  editor module imports an R3F type to read it. */
+export interface InternalsSource {
+  readonly hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>;
+  /** Cheap "would revealing this row show anything?" — used to decide whether
+   *  the menu item appears at all. */
+  readonly hasInternals?: ((id: string) => boolean) | undefined;
+  /** The RAW live children of `id` that the adapter's own projection hides,
+   *  each described exactly as `hierarchy.node` would describe it, but
+   *  re-parented to its RAW parent so a revealed subtree reads as the tree it
+   *  actually is. `undefined` for an id the adapter does not own. */
+  readonly internalChildren?: ((id: string) => EditorNode[] | undefined) | undefined;
+}
+
+export interface InternalsProjection {
+  /** The provider to flatten. Identity-equal to the source's own when nothing
+   *  is revealed, so the common case costs nothing. */
+  readonly hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>;
+  /** True for a row that exists ONLY because of a reveal. */
+  isInternal(id: string): boolean;
+  /** The revealed ids that actually produced rows (a revealed id whose object
+   *  is gone after an HMR remount is silently inert, not an error). */
+  readonly revealRootIds: ReadonlySet<string>;
+  /** Every id this projection minted a row for, transitively. */
+  readonly internalIds: ReadonlySet<string>;
+}
+
+/** Depth backstop for a pathological live tree — the same belt-and-braces
+ *  constant `hierarchy-node-rows.ts` keeps for the same reason. */
+const MAX_DEPTH = 500;
+
+const EMPTY: ReadonlySet<string> = new Set();
+
+// ------------------------------------------------------------ session state
+
+/**
+ * Ids whose internals are currently revealed. Module-level and NOT persisted —
+ * see this file's header for why a revealed skeleton must not survive a reload.
+ */
+const revealed = new Set<string>();
+
+export function isInternalsRevealed(id: string): boolean {
+  return revealed.has(id);
+}
+
+/** Returns the new state, so a caller can report what it did. */
+export function toggleInternalsRevealed(id: string): boolean {
+  if (revealed.delete(id)) return false;
+  revealed.add(id);
+  return true;
+}
+
+export function revealedInternalsIds(): ReadonlySet<string> {
+  return revealed;
+}
+
+/** Test-only reset for the module-level session set. */
+export function __resetRevealedInternalsForTest(): void {
+  revealed.clear();
+}
+
+// -------------------------------------------------------------- projection
+
+/**
+ * Build the revealing view of `source.hierarchy`.
+ *
+ * The walk is EAGER (every revealed subtree is expanded to its leaves up
+ * front) rather than lazy inside `node()`, because "is this row internal?" must
+ * be answerable in any order — the panel asks it while rendering a row, long
+ * after the flatten that produced it, and a lazily-populated set would make the
+ * answer depend on call order. It costs one `internalChildren` call per
+ * revealed node, which the R3F adapter answers in O(children × depth) with no
+ * subtree walk.
+ *
+ * A revealed node's internals are appended AFTER its projected children, which
+ * is what keeps a nested instance's row in its authored place: the flattener
+ * dedupes by id on first occurrence, so the instance is emitted as the real
+ * child it is, and the internal path that also reaches it is skipped.
+ */
+export function internalsProjection(
+  source: InternalsSource,
+  revealedIds: ReadonlySet<string> = revealed,
+): InternalsProjection {
+  // Called THROUGH `source` below, never as a detached reference: every real
+  // implementer is a class method that needs its own `this`.
+  if (typeof source.internalChildren !== 'function' || revealedIds.size === 0) {
+    return {
+      hierarchy: source.hierarchy,
+      isInternal: () => false,
+      revealRootIds: EMPTY,
+      internalIds: EMPTY,
+    };
+  }
+
+  /** id -> the internal child ids appended to it. */
+  const appended = new Map<string, string[]>();
+  /** id -> the node an internal row renders (never re-asked of the adapter,
+   *  whose own `node()` would answer with the PROJECTED parent). */
+  const internalNodes = new Map<string, EditorNode>();
+  const revealRootIds = new Set<string>();
+
+  const walk = (id: string, depth: number): void => {
+    if (depth > MAX_DEPTH || appended.has(id)) return;
+    const children = source.internalChildren!(id) ?? [];
+    if (children.length === 0) return;
+    appended.set(
+      id,
+      children.map((child) => child.id),
+    );
+    for (const child of children) {
+      if (internalNodes.has(child.id)) continue;
+      internalNodes.set(child.id, child);
+      walk(child.id, depth + 1);
+    }
+  };
+
+  for (const id of revealedIds) {
+    walk(id, 0);
+    if (appended.has(id)) revealRootIds.add(id);
+  }
+
+  const decorate = (node: EditorNode | null): EditorNode | null => {
+    if (!node) return null;
+    const extra = appended.get(node.id);
+    return extra ? { ...node, childIds: [...node.childIds, ...extra] } : node;
+  };
+
+  return {
+    hierarchy: {
+      roots: () => source.hierarchy.roots().map((root) => decorate(root)!),
+      node: (id) => decorate(internalNodes.get(id) ?? source.hierarchy.node(id)),
+    },
+    isInternal: (id) => internalNodes.has(id),
+    revealRootIds,
+    internalIds: new Set(internalNodes.keys()),
+  };
+}
+
+/**
+ * H6's first-open policy, applied ON TOP of the panel's own
+ * `defaultExpansionByNode` result: **the reveal root's direct children are
+ * visible, everything deeper starts folded.**
+ *
+ * Two overrides express exactly that. The revealed row itself opens (otherwise
+ * "Reveal Internals" would appear to do nothing on an instance that happened to
+ * be folded), and every internal row starts closed — a rig is 60 rows deep and
+ * dumping all of it into the panel is the opposite of the "look inside this one
+ * thing" the action is for. Both are DEFAULTS: an explicit fold the author
+ * performs afterwards still wins, because the panel consults session and
+ * persisted preferences before this map.
+ */
+export function applyRevealExpansionDefaults(
+  defaults: Map<string, boolean>,
+  projection: Pick<InternalsProjection, 'revealRootIds' | 'internalIds'>,
+): Map<string, boolean> {
+  for (const id of projection.internalIds) defaults.set(id, false);
+  for (const id of projection.revealRootIds) defaults.set(id, true);
+  return defaults;
+}

package/src/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/hierarchy-mark-reader.ts

@@ -0,0 +1,73 @@
+/**
+ * The one place the hierarchy panel's mark convention meets a real `Object3D`.
+ *
+ * `hierarchy-component-marks.ts` is deliberately pure — it takes a
+ * {@link NodeMarkReader} and never learns what a node is made of — and
+ * `GameHierarchy` is deliberately contract-only (rule zero: no 3D-library value
+ * import). This module is the seam between them: it asks the adapter's OPTIONAL
+ * `object3D` capability for the node and reads
+ * `@volter/editor-threejs/adapter/hierarchy-marks`' two marks off it.
+ *
+ * An adapter with no `Object3D` seam (React, Pixi, DOM) yields {@link NO_MARKS},
+ * which `componentMarkView` recognizes by identity and short-circuits on — so a
+ * non-three surface pays nothing and renders byte-identically.
+ */
+
+import type { HierarchyProvider } from '@volter/editor-project/adapter';
+import { componentRootName, isBuiltInternal } from '@volter/editor-threejs/adapter/hierarchy-marks';
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import { isComponentInstanceRoot } from './authoring/component-instance-root';
+import { NO_MARKS, type NodeMarkReader, type NodeMarks } from './hierarchy-component-marks';
+
+/** Project-local R3F source already carries its component ownership on the
+ * native node. Read that existing stamp as the automatic equivalent of an
+ * imperative `markComponentRoot`; explicit marks still win. */
+function componentName(object: Parameters<typeof componentRootName>[0]): string | undefined {
+  const explicit = componentRootName(object);
+  // Some project-local components are the native authoring ENTITY constructor rather than a
+  // reusable component boundary. Importers are the canonical case: `<UnityNode>` creates the
+  // GameObject itself, while a generated `<Player>` prefab remains a component instance around
+  // that node. `authoringRoot` is the existing generic declaration for exactly that distinction.
+  // An explicit component mark still wins, so a prefab root can be both its own authoring object
+  // and the boundary of the reusable prefab instance. A built-internal mark suppresses only the
+  // automatic component classification: a React helper that renders implementation machinery is
+  // still implementation, not a prefab merely because Fiber recorded its component boundary.
+  if (
+    explicit ||
+    isBuiltInternal(object) ||
+    getUserData(object, 'authoringRoot') === true ||
+    !isComponentInstanceRoot(object)
+  ) {
+    return explicit;
+  }
+  const authored = getUserData(object, 'authoringComponent');
+  return typeof authored === 'string' && authored ? authored : undefined;
+}
+
+/**
+ * A memoized reader over `hierarchy.object3D`.
+ *
+ * The cache lives for the reader's lifetime — one render pass — because the
+ * live graph it reads is re-walked every render anyway (`hierarchy.roots()` IS
+ * the refresh point on a live adapter). Within one pass the marks cannot move,
+ * and the walk asks for the same id many times: once per `node()` projection,
+ * again per internals probe.
+ */
+export function markReaderFor(hierarchy: Pick<HierarchyProvider, 'object3D'>): NodeMarkReader {
+  const object3D = hierarchy.object3D;
+  if (typeof object3D !== 'function') return NO_MARKS;
+  const cache = new Map<string, NodeMarks | undefined>();
+  return (id) => {
+    if (cache.has(id)) return cache.get(id);
+    const object = object3D.call(hierarchy, id);
+    const marks: NodeMarks | undefined = object
+      ? {
+          componentRoot: componentName(object),
+          authoredEntity: getUserData(object, 'authoringRoot') === true,
+          builtInternal: isBuiltInternal(object),
+        }
+      : undefined;
+    cache.set(id, marks);
+    return marks;
+  };
+}