@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/hierarchy-component-marks.ts

@@ -0,0 +1,298 @@
+/**
+ * The panel's half of the hierarchy-presentation convention
+ * (`@volter/editor-threejs/adapter/hierarchy-marks`): a game classifies its
+ * component-instance roots and its implementation subtrees on the LIVE nodes,
+ * and this turns that classification into rows.
+ *
+ * CLASSIFICATION ONLY — NEVER FABRICATED STRUCTURE. Nothing here invents a
+ * parent. Where a node belongs is the TREE's answer, and a world whose tree
+ * disagrees with its own ownership is fixed in the world (three's
+ * `matrixWorldAutoUpdate = false` keeps a transform-independent object parented
+ * where it belongs), not papered over here. What this module decides is
+ * narrower and entirely presentational: which rows are the game and which are
+ * the implementation underneath it, and — since an implementation node may sit
+ * BETWEEN two things that are the game — where a row's nearest visible ancestor
+ * is. See {@link componentMarkView} point 5, promotion.
+ *
+ * WHY THIS IS A DECORATOR AND NOT A SECOND ROW PIPELINE. Exactly the reason
+ * `hierarchy-internals.ts` gives for reveal: the panel's cap, collapse, search,
+ * selection-reveal and virtualization all layer on ONE flatten of ONE
+ * `HierarchyProvider`. A marked tree composes by handing that flattener a
+ * richer provider — never by forking the walk. And it composes with reveal
+ * specifically by producing an {@link InternalsSource}: built-internals become
+ * internals of exactly the kind "Reveal Internals" already shows, so the
+ * read-only rule, the search exclusion and the drag refusal that already govern
+ * a revealed row govern these with no second policy.
+ *
+ * THE NO-MARKS FALLBACK IS IDENTITY, BY CONSTRUCTION. Every projection below
+ * short-circuits when a node carries no mark and no child carries one, and
+ * {@link componentMarkView} returns the source's own `hierarchy` object when the
+ * tree cannot carry marks at all (an adapter with no `Object3D` seam — React,
+ * Pixi, DOM). A world that adopts nothing renders exactly as it did.
+ *
+ * PURE ON PURPOSE: the marks arrive through the injected {@link NodeMarkReader},
+ * never by importing three or touching `userData` here, so the whole row
+ * decision is unit-testable with plain objects.
+ */
+
+import type { EditorNode, HierarchyProvider } from '@volter/project/adapter';
+import type { InternalsSource } from '@volter/sdk/kit/hierarchy-internals';
+import type { HierarchyNodeRow } from './hierarchy-node-rows';
+
+/** What the marks say about ONE node. Both absent is the ordinary node. */
+export interface NodeMarks {
+  /** `volterComponentRoot` — the component name this node is one instance of. */
+  readonly componentRoot?: string | undefined;
+  /** A native authoring entity constructor. It stays an ordinary entity row, but like a
+   *  component root it is authored content even when a host implementation node wraps it. */
+  readonly authoredEntity?: boolean | undefined;
+  /** `volterBuiltInternal` — this node is the root of an implementation subtree. */
+  readonly builtInternal?: boolean | undefined;
+}
+
+/** Reads the marks off one node id. `undefined` for an id the source has no
+ *  live object for — indistinguishable from an unmarked node, deliberately. */
+export type NodeMarkReader = (id: string) => NodeMarks | undefined;
+
+/** The hierarchy half of an adapter, plus whatever internals capability it
+ *  already had. Structurally satisfied by `AuthoringAdapter` /
+ *  `CompositeAuthoringAdapter` without importing either — the same contract-only
+ *  probe shape `hierarchy-internals.ts` and `hierarchy-row-model.ts` use. */
+export interface MarkedTreeSource {
+  readonly hierarchy: Pick<HierarchyProvider, 'roots' | 'node'>;
+  readonly hasInternals?: ((id: string) => boolean) | undefined;
+  readonly internalChildren?: ((id: string) => EditorNode[] | undefined) | undefined;
+}
+
+export interface MarkedTreeView extends InternalsSource {
+  /** True for a node whose live object carries `volterComponentRoot`. */
+  isComponentRoot(id: string): boolean;
+  /** True for a node that is, or descends from, a `volterBuiltInternal` root.
+   *  Exposed for tests and for {@link componentMarkView}'s own reuse; the panel
+   *  reads internal-ness off the reveal projection, which is the union of these
+   *  and the adapter's own hidden children. */
+  isBuiltInternal(id: string): boolean;
+}
+
+/** Depth backstop for a pathological live tree — the same belt-and-braces
+ *  constant `hierarchy-internals.ts`/`hierarchy-node-rows.ts` keep. */
+const MAX_DEPTH = 500;
+
+/** The reader for a surface that has no node to read marks off. Identity-checked
+ *  by {@link componentMarkView}, which is why it is a shared constant rather
+ *  than a fresh closure per call. */
+export const NO_MARKS: NodeMarkReader = () => undefined;
+
+/**
+ * Decorate `source` so the marks become rows.
+ *
+ * Five things change, and nothing else:
+ *
+ * 1. A marked component root reports `role: 'component'` and
+ *    `typeLabel: <mark name>`. That is all the panel needs — `rowIdentity`
+ *    already prints `Coin1 ·Coin` for exactly this pair, and `ROLE_ICON`
+ *    already has the component glyph. NO new presentation vocabulary: a second
+ *    way to render "this is an instance" is how two of them drift.
+ *    The mark REPLACES any `typeLabel` the adapter had, because a three
+ *    projection reports the native class there (`Object3D`), and
+ *    `Coin1 ·Object3D` is worse than no suffix at all.
+ * 2. Built-internal children disappear from every `childIds`, so what a
+ *    collapsed tree shows is the game and not its implementation.
+ * 3. A built-internal ROOT disappears from `roots()` for the same reason, but
+ *    meaningful content beneath it is promoted to roots in place. A root has
+ *    no parent row to reveal it under, so the implementation wrapper itself
+ *    stays unreachable while spawned content remains visible.
+ * 4. Both come back through `internalChildren`/`hasInternals` — unioned with
+ *    whatever the adapter already hid — so "Reveal Internals" shows them,
+ *    read-only, under their real parent, in the true chain.
+ * 5. PROMOTION. A component instance does not lose its row because
+ *    implementation nodes sit between it and its owner. A weapon prefab
+ *    attached to a hand bone, a nameplate on a head bone: content the author
+ *    placed, inside a subtree a rig builder marked. `volterComponentRoot` beats
+ *    `volterBuiltInternal` (see `isBuiltInternal`'s climb), and this lists such a
+ *    row under its nearest VISIBLE ancestor — so a prefab reads as the parent
+ *    of everything meaningful beneath it, however many bones the rig hangs in
+ *    between. A subtree with no instance inside it still folds away whole,
+ *    because there is nothing in it to promote. This is the elision half of the
+ *    same classification: (2) removes an implementation row, (5) keeps what was
+ *    under it from going with it.
+ *
+ * Built-internal is SUBTREE-scoped (see the engine module's header): a node
+ * whose ANCESTOR is marked is internal too, which is what lets a rig cost one
+ * mark. {@link MarkedTreeView.isBuiltInternal} memoizes that climb, so a
+ * repeated walk over the same tree pays once per node.
+ */
+export function componentMarkView(
+  source: MarkedTreeSource,
+  marksOf: NodeMarkReader,
+): MarkedTreeView {
+  if (marksOf === NO_MARKS) {
+    // A surface with no `Object3D` seam (React, Pixi, DOM) cannot carry these
+    // marks at all. Hand back the source itself so the panel's provider is
+    // IDENTICAL, not merely equivalent.
+    return {
+      hierarchy: source.hierarchy,
+      isComponentRoot: () => false,
+      isBuiltInternal: () => false,
+      ...(source.hasInternals ? { hasInternals: (id: string) => source.hasInternals!(id) } : {}),
+      ...(source.internalChildren
+        ? { internalChildren: (id: string) => source.internalChildren!(id) }
+        : {}),
+    };
+  }
+
+  /** id -> "this node is inside a built subtree", memoized across the walk. */
+  const internalCache = new Map<string, boolean>();
+
+  const isBuiltInternal = (id: string): boolean => {
+    const cached = internalCache.get(id);
+    if (cached !== undefined) return cached;
+    // Climb to the first answer we already have (or to a root), then fill the
+    // whole chain in one pass — an ancestor walk per node would be O(depth²).
+    const chain: string[] = [];
+    let cursor: string | null = id;
+    let inherited = false;
+    let guard = 0;
+    while (cursor !== null && guard++ < MAX_DEPTH) {
+      const known = internalCache.get(cursor);
+      if (known !== undefined) {
+        inherited = known;
+        break;
+      }
+      chain.push(cursor);
+      // PRECEDENCE: an explicit component root is content even inside an
+      // implementation subtree. Otherwise an explicit implementation mark on
+      // THIS node wins over the automatic authored-entity stamp: generated
+      // native machinery is still source-addressable JSX, but its attach seam
+      // knows that it is implementation. An authored entity with no such mark
+      // remains content inside an implementation ancestor — a weapon attached
+      // to a rig bone, for example — which is what makes promotion (see
+      // `visibleChildIds`) reachable at all.
+      const marks = marksOf(cursor);
+      if (marks?.componentRoot !== undefined) break;
+      if (marks?.builtInternal === true) {
+        inherited = true;
+        break;
+      }
+      if (marks?.authoredEntity === true) break;
+      cursor = source.hierarchy.node(cursor)?.parentId ?? null;
+    }
+    // `chain` is innermost-first and every entry shares the verdict of the node
+    // that stopped the climb — either an already-known ancestor, or the marked
+    // node itself (which is the last entry pushed).
+    for (const entry of chain) internalCache.set(entry, inherited);
+    return inherited;
+  };
+
+  const isComponentRoot = (id: string): boolean => marksOf(id)?.componentRoot !== undefined;
+
+  /**
+   * The rows that belong directly under `node` — its own visible children,
+   * plus (point 5) the visible descendants that implementation children stand
+   * between. Recursive: an implementation node contributes ITS promoted rows in
+   * its own place, so a two-deep chain of them elides just as one does, and a
+   * subtree with nothing visible in it contributes nothing at all.
+   */
+  const visibleChildIds = (node: EditorNode, depth = 0): string[] => {
+    if (depth > MAX_DEPTH) return [];
+    const out: string[] = [];
+    for (const childId of node.childIds) {
+      if (!isBuiltInternal(childId)) {
+        out.push(childId);
+        continue;
+      }
+      const child = source.hierarchy.node(childId);
+      if (child) out.push(...visibleChildIds(child, depth + 1));
+    }
+    return out;
+  };
+
+  /** The children of `id` this view hides — its DIRECT implementation children,
+   *  which is what "Reveal Internals" puts back and where the true chain lives. */
+  const hiddenChildIds = (node: EditorNode): string[] =>
+    node.childIds.filter((childId) => isBuiltInternal(childId));
+
+  const project = (node: EditorNode | null): EditorNode | null => {
+    if (!node) return null;
+    const componentRoot = marksOf(node.id)?.componentRoot;
+    const childIds = visibleChildIds(node);
+    const sameChildren =
+      childIds.length === node.childIds.length &&
+      childIds.every((childId, index) => childId === node.childIds[index]);
+    if (componentRoot === undefined && sameChildren) return node;
+    return {
+      ...node,
+      ...(componentRoot === undefined
+        ? {}
+        : { role: 'component' as const, typeLabel: componentRoot }),
+      ...(sameChildren ? {} : { childIds }),
+    };
+  };
+
+  const hierarchy: Pick<HierarchyProvider, 'roots' | 'node'> = {
+    roots: () =>
+      source.hierarchy.roots().flatMap((root) => {
+        if (!isBuiltInternal(root.id)) return [project(root)!];
+        return visibleChildIds(root).flatMap((childId) => {
+          const child = project(source.hierarchy.node(childId));
+          return child ? [{ ...child, parentId: root.parentId }] : [];
+        });
+      }),
+    node: (id) => project(source.hierarchy.node(id)),
+  };
+
+  return {
+    hierarchy,
+    isComponentRoot,
+    isBuiltInternal,
+    hasInternals: (id) => {
+      if (source.hasInternals?.(id) === true) return true;
+      const node = source.hierarchy.node(id);
+      return node ? hiddenChildIds(node).length > 0 : false;
+    },
+    internalChildren: (id) => {
+      const own = source.internalChildren?.(id);
+      const node = source.hierarchy.node(id);
+      const hidden = node
+        ? hiddenChildIds(node).flatMap((childId) => {
+            // PROJECTED, not raw: this node's own implementation children are
+            // hidden from its `childIds` here too, and the reveal walk appends
+            // them back itself. Handing back the raw node would list every
+            // sub-bone twice. Reveal therefore shows the TRUE chain of
+            // implementation nodes — each under its real parent, one level per
+            // walk step — which is what the action is for.
+            const child = project(source.hierarchy.node(childId));
+            // Re-parented to `id` — a revealed subtree is displayed as the tree
+            // it literally is, the same rule `internalChildren` states on the
+            // source adapter.
+            return child ? [{ ...child, parentId: id }] : [];
+          })
+        : [];
+      if (own === undefined) return hidden.length > 0 ? hidden : undefined;
+      return [...own, ...hidden];
+    },
+  };
+}
+
+/**
+ * A marked component instance opens CLOSED. This is a default, applied on top
+ * of `defaultExpansionByNode`'s shape rule and under the author's own session /
+ * persisted preference — so "expandable on demand" is the panel's existing
+ * expansion state doing its existing job, and an instance the author opened
+ * stays open across renders.
+ *
+ * Takes the already-flattened structural rows rather than walking the tree
+ * again: the panel has them, and a second walk over a live graph is the cost
+ * this whole cycle exists to remove.
+ */
+export function applyComponentRootExpansionDefaults(
+  defaults: Map<string, boolean>,
+  rows: readonly HierarchyNodeRow[],
+  isComponentRoot: (id: string) => boolean,
+): Map<string, boolean> {
+  for (const row of rows) {
+    if (row.more) continue;
+    if (isComponentRoot(row.node.id)) defaults.set(row.node.id, false);
+  }
+  return defaults;
+}

package/src/kit/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/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;
+}