@vgai/engine 0.5.10 → 0.5.12

package/schemas/vgai-project.schema.json

@@ -100,18 +100,12 @@
                   "ingest": {
                     "type": "object",
                     "properties": {
-                      "strategy": {
-                        "type": "string",
-                        "enum": [
-                          "shared",
-                          "deduped",
-                          "iframe-reachable",
-                          "opaque-embed"
-                        ],
-                        "description": "Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier"
+                      "contractShim": {
+                        "description": "Project-relative path to a HOST-ADDED ES module that declares this game's `window.vgaiGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a vendored byte — the pristine-copy door. The host imports it immediately BEFORE the game's own entry module, in the editor's realm. TIMING CONTRACT, which a shim author must obey: because it runs before the game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level. Anything that needs the game`s own modules must be LAZY: a dynamic `import()` INSIDE each verb/provider closure, resolved at call time. Importing a game module eagerly from the shim would evaluate it ahead of the game`s own entry and reorder its module side effects. Every such `import()` MUST take a STRING LITERAL, never a variable/table lookup. A variable specifier is not statically analyzable, so the dev server leaves it alone and it resolves at runtime against the shim`s own `/@fs/` url — while the game`s entry has had ITS relative imports rewritten to whatever url the server considers canonical for those files. Module identity is per-url, so the shim silently binds a SECOND, freshly-evaluated copy of the whole game and every provider reports a game that never started. Measured on three-descent: 285 segments through the game`s graph, 0 through the shim`s, and no error anywhere.",
+                        "type": "string"
                       },
-                      "entryHtml": {
-                        "description": "Entry HTML path, project-relative. WIRED for opaque-embed (D-W2): the file`s bytes are read verbatim through the project-static route and hosted in a sandboxed iframe (embed-only, no scene introspection), for both canvas and three roots. Legal but NOT wired to a mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` instead, the wired reachable route).",
+                      "dataWriter": {
+                        "description": "Project-relative path to a HOST-ADDED ES module that writes this game's own DATA file back — the sibling of a source write for a game whose authorable truth is not source. Descent places its robots, powerups and hostages in binary records inside `descent.hog`, reaching no source literal, so an authored move of one is an edit to that file and nothing else can write it. The module declares two exports and the host knows nothing else about it: `dataFile` (a project-relative string — the ONE file this writer edits) and `planDataEdit(bytes, {record, property, baseline, next})`, which returns `{changed: true, bytes}` or `{changed: false, reason}` and may be async. It is loaded in the editor realm beside the game, so it may `import()` the game's own modules to resolve what only a running game knows (Descent's writer asks the game`s own `find_point_seg` which segment a moved object landed in, and refuses \"outside the mine\" rather than writing data the game would read back wrong). It NEVER fabricates: a record it cannot address, or a property it does not model, is a named refusal. An object is anchored to a record by carrying `userData.vgaiRecordIndex` — the game declares that identity itself (a recorded patch or a shim); the host never infers one.",
                         "type": "string"
                       },
                       "assets": {
@@ -132,40 +126,11 @@
                         }
                       },
                       "captureTimeoutMs": {
-                        "description": "How long to wait for capture before REPORTING the degrade loudly — not how long to keep listening. On the self-hosted-three route the devtools subscription is permanent, so a renderer appearing later still upgrades a reported-embed-only mount in place; the host clamps this value so a long one cannot block the editor on a question the upgrade path answers anyway.",
+                        "description": "How long the host waits for this game's first captured frame before the mount FAILS by name. A game that needs a long boot (streamed world assets, a menu the player must clear) raises it; the default is 10s.",
                         "type": "number"
-                      },
-                      "bundleUrl": {
-                        "description": "Absolute URL of the externalized built game bundle — the WIRED iframe-reachable mount route (iframe-reachable only), for BOTH canvas (Track P, ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and three (D-W1, ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). PRECONDITION: the bundle must externalize its root`s own runtime as a bare, un-rewritten import (`pixi.js` for canvas, `three` for three — `vgai bundle` does this for you) so it resolves through the iframe importmap to the HOST instance the capture trap is installed on; a bundle with an inlined runtime is unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/entryHtml is required when strategy is iframe-reachable.",
-                        "type": "string"
-                      },
-                      "baseHref": {
-                        "description": "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
-                        "type": "string"
-                      },
-                      "assetBaseUrl": {
-                        "description": "Host-side basePath forced onto the trapped runtime's own asset resolution — pixi's `Assets.init` for a canvas root, three's `DefaultLoadingManager.setURLModifier` for a three root (D-W1) — absolute, or root-relative (resolved against the editor page's own origin at mount time, ingest-mode.ts, so a static manifest never has to know the dev-server port) (iframe-reachable only — a document.write iframe keeps the parent window.location).",
-                        "type": "string"
-                      },
-                      "extraDeps": {
-                        "description": "Bare specifiers of this root's externalized deps beyond its own runtime (pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's host-namespace registry into module namespaces when known (D-P1 — the manifest carries data, not code); an unregistered specifier falls back to the open project's own node_modules (D-Z3), served as a verbatim iframe importmap URL. Throws a named error if neither resolves it (iframe-reachable only).",
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        }
-                      },
-                      "pixiModuleUrl": {
-                        "description": "PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for version skew) (iframe-reachable only). Declaring this on a `kind: \"three\"` root is schema-legal (this field is kind-agnostic here) but throws a NAMED not-supported error at resolve — three has no version-skew mount this wave (D-W7: a hypothetical `threeModuleUrl` is explicitly parked, no consumer exists).",
-                        "type": "string"
-                      },
-                      "bodyHtml": {
-                        "description": "HTML injected into the iframe body before the game script boots (e.g. a `<div id=\"game-root\">` the game expects to find) (iframe-reachable only).",
-                        "type": "string"
                       }
                     },
-                    "required": [
-                      "strategy"
-                    ],
+                    "additionalProperties": false,
                     "description": "Ingest adapter configuration for an unmodified game (a repo-vendored game or your own external folder)"
                   }
                 },
@@ -200,42 +165,12 @@
           },
           "loop": {
             "default": "gated",
-            "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (the \"composited, unsynchronized\" tier) — an axis independent of capability tier",
+            "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (composited, unsynchronized)",
             "type": "string",
             "enum": [
               "gated",
               "self-driven"
             ]
-          },
-          "capabilities": {
-            "description": "Per-delivery-context capability tier declarations (§4). Declaring above the adapter's ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.",
-            "type": "object",
-            "properties": {
-              "local": {
-                "description": "Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)",
-                "type": "string",
-                "enum": [
-                  "first-party",
-                  "shared",
-                  "deduped",
-                  "iframe-reachable",
-                  "opaque-embed",
-                  "unsupported"
-                ]
-              },
-              "hosted": {
-                "description": "Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)",
-                "type": "string",
-                "enum": [
-                  "first-party",
-                  "shared",
-                  "deduped",
-                  "iframe-reachable",
-                  "opaque-embed",
-                  "unsupported"
-                ]
-              }
-            }
           }
         },
         "required": [
@@ -356,6 +291,20 @@
         "height"
       ]
     },
+    "rendering": {
+      "description": "Construction-time renderer properties, which no world can declare after the fact. Everything a world CAN declare (tone mapping, output colour space, clear colour, shadow filter) lives on the world's own renderer config instead.",
+      "type": "object",
+      "properties": {
+        "antialias": {
+          "type": "boolean",
+          "description": "Whether every three root is built with a multisampled drawing buffer. This is the ONE render property a world cannot declare for itself (world3d-react/renderer-config.ts): a WebGL context fixes its sample count at CREATION from this boolean, long before a world mounts, so it belongs to the PROJECT. The runtime reader is mount-manifest.ts, which threads it into createHostRenderer for each three root. WebGL exposes no sample COUNT — the implementation picks one (4x on every desktop browser measured), so a source engine that authored 8x/16x gets multisampling but not its exact count."
+        }
+      },
+      "required": [
+        "antialias"
+      ],
+      "additionalProperties": false
+    },
     "debug": {
       "description": "Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs window.__vgai outside dev builds.",
       "type": "object",

package/src/adapter/authoring.ts

@@ -238,7 +238,7 @@ export interface InspectorProvider {
   /** Schema-driven — NOT fixed to `SceneEntity`. */
   properties(id: string): PropertyDescriptor[];
   get(id: string, path: string): unknown;
-  set(id: string, path: string, value: unknown): void;
+  set(id: string, path: string, value: unknown): void | Promise<void>;
   /**
    * Optional — REMOVE a property's authored override entirely (not "set to a
    * value"), letting whatever governs it in its absence take over. The one
@@ -281,6 +281,19 @@ export interface AssetSubjectProvider {
   entries?(): ReadonlyArray<{ id: string; subject: AuthoringAssetSubject }>;
 }
 
+/** A semantic jump from one authored subject to another document/subject.
+ * The adapter owns resolution and opening; the inspector only presents the
+ * title and exposes the same verb to human and serialized projections. */
+export interface RelatedSubjectLink {
+  readonly id: string;
+  readonly title: string;
+  open(): void;
+}
+
+export interface RelatedSubjectsProvider {
+  links(id: string): readonly RelatedSubjectLink[];
+}
+
 export interface StructureProvider {
   create(kind: string, parentId?: string): string;
   /**
@@ -384,26 +397,6 @@ export interface PersistenceProvider {
   applyExternal?(content: unknown, rawContent?: string): void;
 }
 
-/** D8 — mutually-exclusive root groups (radio roots): e.g. a "Scenes" group whose
- *  members are the game's scene roots, only one of which is loaded/active at a
- *  time (unlike ordinary sibling roots, which all coexist). */
-export interface RootGroup {
-  id: string; // stable, e.g. 'scenes'
-  label: string; // 'Scenes'
-  memberRootIds: string[]; // EditorNode ids; each is a hierarchy root
-  activeRootId: string | null;
-}
-export interface RootGroupsProvider {
-  groups(): RootGroup[];
-  activate(groupId: string, rootId: string): Promise<void> | void;
-}
-
-/** D8 — data-file → root mapping ("opening a file" = activating its root). */
-export interface FileMapProvider {
-  /** project-relative path → node id this adapter maps it to, else null. */
-  rootForFile(path: string): string | null;
-}
-
 /** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
 export interface PickProvider {
   pick(clientX: number, clientY: number): string | null;
@@ -510,9 +503,11 @@ export interface BoxEditProvider {
   referencePoint?(id: string): BoxEditReferencePoint | null;
 }
 
-/** Text-content editing — currently OFF-contract (the react adapter has an `editText(id)`
- *  method, react-world-authoring-adapter.ts:728, not reachable via the contract). Bring it
- *  on so the overlay's double-click-to-edit-text (D3) is contract-driven. */
+/** Text-content editing, ON the contract: the react-world adapter implements this
+ *  provider (`react-world-authoring-adapter.ts`'s `readonly text: TextProvider`),
+ *  bringing its own `editText(id)` write path onto the seam, so the overlay's
+ *  double-click-to-edit-text (D3) is contract-driven rather than reaching for a
+ *  concrete adapter's method. */
 export interface TextProvider {
   /** the element's editable pure-text, or null if the body is dynamic/has child elements */
   get(id: string): string | null;
@@ -539,15 +534,46 @@ export interface ColorSampleProvider {
 }
 
 /**
- * WO-IDX1 — where a node's live object was CREATED in the game's own source.
+ * WO-IDX1 — where a node's live object CAME FROM in the game's own truth.
  *
- * `display` is the `file:line` the editor shows verbatim. The unanchored shape
+ * `display` is the string the editor shows verbatim. The unanchored shape
  * carries a `reason` rather than a blank, because "we don't know" and "a
  * library built it" are different facts and neither may present as silence
  * (the honest-floor rule).
+ *
+ * TWO ANCHORED KINDS, because a game has two kinds of truth and only one of
+ * them is source.
+ *
+ *  - `source` is the original: a `new` expression at a `file:line:col` in the
+ *    game's own code, which is where an edit to a constructor literal has to be
+ *    written.
+ *  - `data` is the sibling a level-based game needs. Descent's placed cargo —
+ *    the robots, the powerups, the hostages — reaches no source literal at all;
+ *    it is binary records inside `descent.hog` that the game parses at load. An
+ *    authored move of a robot is therefore an edit to THE GAME'S OWN DATA, and
+ *    the honest anchor is the data file plus the index of the record that
+ *    addresses the object inside it.
+ *
+ * `kind` is an explicit discriminant rather than an inferred one, so a consumer
+ * that only understands source anchors fails to compile against a data anchor
+ * instead of silently reading `line` off something that has none.
+ *
+ * A data record is EXACTLY ONE object by construction — an index addresses one
+ * record — so the "how many objects did this site construct?" question that
+ * governs a source write has no data-side analogue and must not be invented
+ * for one.
  */
 export type NodeCreationSite =
-  | { anchored: true; file: string; line: number; col: number; display: string }
+  | { anchored: true; kind: 'source'; file: string; line: number; col: number; display: string }
+  | {
+      anchored: true;
+      kind: 'data';
+      /** Project-relative path of the game's own data file, POSIX separators. */
+      file: string;
+      /** Index of the record inside that file which addresses this object. */
+      record: number;
+      display: string;
+    }
   | { anchored: false; reason: string };
 
 /**
@@ -571,12 +597,9 @@ export interface AuthoringAdapter {
   readonly inspector?: InspectorProvider;
   /** The selected node is an atomic asset that can open in the Asset Editor. */
   readonly assetSubject?: AssetSubjectProvider;
+  readonly related?: RelatedSubjectsProvider;
   readonly structure?: StructureProvider;
   readonly persistence?: PersistenceProvider;
-  /** D8 — mutually-exclusive root groups (radio roots). Absent ⇒ no grouped roots. */
-  readonly rootGroups?: RootGroupsProvider;
-  /** D8 — data-file → root mapping. Absent ⇒ this adapter maps no files to roots. */
-  readonly files?: FileMapProvider;
   /** D12 — per-layer viewport picking. Absent ⇒ this adapter is not pickable. */
   readonly pickable?: PickProvider;
   /** T0 (spec 27 §2) — per-node screen geometry for a DOM visual editor's overlay/

package/src/adapter/body-marks.ts

@@ -0,0 +1,69 @@
+/**
+ * The transform-AUTHORITY convention: how a game tells the host which of its
+ * nodes have their pose written by a rigid body rather than by the node itself.
+ *
+ * Sibling of `hierarchy-marks.ts`, and the same shape of idea. That module's
+ * marks answer "what IS this node" for the panel; this one answers "who WRITES
+ * this node's pose" for an edit. Both are written by GAME code at the seam that
+ * knows the answer, read generically by the host, and namespaced `vgai*` because
+ * they are the host's namespace on a node the game owns.
+ *
+ * ## Why it exists
+ *
+ * A world that simulates writes `node.position/quaternion` FROM its bodies every
+ * step. Setting the node is therefore not an edit — it is a value that survives
+ * until the next step and then vanishes, which is what "the gizmo does nothing"
+ * looks like from the outside. The edit has to reach the body.
+ *
+ * The host cannot find the body on its own. Three.js has no body concept, the
+ * body is usually not in the scene graph at all, and the mapping from node to
+ * body is private to whichever code built the pair. So the code that ATTACHES a
+ * body to a node draws the link in the same breath — one call, at the one place
+ * the answer is known — exactly as `markBuiltInternal` is called at the attach
+ * seam and never by a later sweep of the tree.
+ *
+ * ## Prefer the system adapter when you have one
+ *
+ * A game that already registers `SystemAdapters.physics` needs none of this: the
+ * adapter's `ownerOf`/`freeze`/`commit`/`unfreeze` is the richer answer, and the
+ * editor asks it first. This mark is for the case that seam cannot cover — a
+ * world whose bodies are built by ordinary per-scene code with no central
+ * registry to hand a `bodyFor(nodeId)` resolver (every translated import lane),
+ * where the only place node and body meet is the constructor that made both.
+ * Marked nodes reach the SAME four verbs through
+ * {@link createRapierBodyEditing}; this is a second SOURCE for one mechanism,
+ * not a second mechanism.
+ *
+ * ## What to mark
+ *
+ * The node whose pose the body writes — normally the body's own root node. Not
+ * subtree-scoped (unlike `vgaiBuiltInternal`): a child of a body-driven node
+ * inherits its parent's motion through the transform chain, and its own local
+ * pose is still the node's to keep. Mark exactly the node the sync writes.
+ */
+
+import type * as THREE from 'three';
+import { getUserData, setUserData } from '../ecs/user-data';
+import type { RapierEditableBody } from './rapier-physics-adapter';
+
+/**
+ * Declare that `body` owns `node`'s pose: a transform edit on `node` is applied
+ * to `body`, and the next step is what puts the result back on the node.
+ *
+ * Call it where the pair is created. `body` is the game's OWN Rapier body,
+ * passed through unchanged — the parameter type names five of Rapier's own
+ * methods structurally (see {@link RapierEditableBody}) because this repo
+ * legitimately resolves two copies of `@dimforge/rapier3d-compat` whose
+ * `RigidBody` classes are unrelated nominal types.
+ */
+export function markBodyOwnedNode(node: THREE.Object3D, body: RapierEditableBody): void {
+  setUserData(node, 'vgaiBodyOwner', body);
+}
+
+/** The body that owns `node`'s pose, or `undefined` for a node that owns its own. */
+export function bodyOwningNode(
+  node: THREE.Object3D | null | undefined,
+): RapierEditableBody | undefined {
+  const body = getUserData(node, 'vgaiBodyOwner');
+  return body ?? undefined;
+}

package/src/adapter/constraint.ts

@@ -0,0 +1,71 @@
+/**
+ * Format-neutral live mark for source-owned spatial constraints.
+ *
+ * The project capability that performs a solve attaches one or more marks to
+ * the Object3D that owns the constrained pose. The editor reads the marks to
+ * render an ordinary constraint stack and transient viewport handles. This is
+ * observation, not authored data: the owning TS/TSX and its ordinary target /
+ * pole Object3Ds remain the only source of truth.
+ */
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+export type ConstraintStatus = 'ready' | 'disabled' | 'unresolved' | 'error';
+
+export interface ConstraintConfig {
+  /** Stable only within this mounted owner. */
+  readonly id: string;
+  readonly type: 'two-bone-ik' | 'ccd-ik' | (string & {});
+  readonly label: string;
+  readonly enabled: boolean;
+  readonly weight: number;
+  /** Evaluation order among constraints attached to this owner. */
+  readonly order: number;
+}
+
+export interface ConstraintSnapshot {
+  readonly status: ConstraintStatus;
+  readonly message?: string;
+  /** Root → effector, using the real bones from the live skeleton. */
+  readonly chain: readonly THREE.Object3D[];
+  readonly target: THREE.Object3D | null;
+  readonly pole: THREE.Object3D | null;
+  /** Effector-to-target distance after the latest solve, in world units. */
+  readonly error: number | null;
+}
+
+export interface ConstraintMark {
+  readonly config: ConstraintConfig;
+  getSnapshot(): ConstraintSnapshot;
+}
+
+export function constraintsOf(
+  object: THREE.Object3D | null | undefined,
+): readonly ConstraintMark[] {
+  const candidate = getUserData(object, 'constraints');
+  if (!Array.isArray(candidate)) return [];
+  return candidate.filter(
+    (entry): entry is ConstraintMark =>
+      Boolean(entry) &&
+      typeof entry === 'object' &&
+      typeof (entry as Partial<ConstraintMark>).getSnapshot === 'function' &&
+      Boolean((entry as Partial<ConstraintMark>).config),
+  );
+}
+
+/** Add or replace one constraint mark without disturbing sibling constraints. */
+export function setConstraintMark(object: THREE.Object3D, mark: ConstraintMark): void {
+  const next = constraintsOf(object).filter((entry) => entry.config.id !== mark.config.id);
+  setUserData(object, 'constraints', [...next, mark]);
+}
+
+/** Remove one mark, or the whole live projection when no id is supplied. */
+export function clearConstraintMark(object: THREE.Object3D, id?: string): void {
+  if (id === undefined) {
+    deleteUserData(object, 'constraints');
+    return;
+  }
+  const next = constraintsOf(object).filter((entry) => entry.config.id !== id);
+  if (next.length === 0) deleteUserData(object, 'constraints');
+  else setUserData(object, 'constraints', next);
+}

package/src/adapter/hierarchy-marks.ts

@@ -0,0 +1,155 @@
+/**
+ * The hierarchy-presentation convention: how a game tells the editor which
+ * parts of its LIVE scene graph are one component instance, and which parts are
+ * implementation rather than content.
+ *
+ * ## Why marks and not a second tree
+ *
+ * The live tree IS the display surface. A hierarchy derived from source would
+ * be a mirror layer — a second model of the world that drifts from the one on
+ * screen — so the boundaries a reader needs have to live ON the nodes. That is
+ * what these marks are, and it is the whole mechanism: a component WRAPS its
+ * functionality and MARKS its root; the editor supports the convention
+ * generically and never learns which library, importer or lane produced the
+ * node.
+ *
+ * ## STRUCTURE IS THE TREE'S JOB. MARKS ONLY CLASSIFY.
+ *
+ * There is deliberately no mark that says "show this row somewhere else". A
+ * group owns its children by CONTAINING them; a prefab owns its parts by
+ * CONTAINING them. If an object reads as belonging under something it is not
+ * parented to, the tree is wrong and the tree is what to fix — because the
+ * panel is not the only reader. `getWorldPosition`, raycasting, disposal,
+ * `traverse`, every physics or gameplay walk and every person reading the
+ * source all follow real parenthood, and a presentation-only "logical parent"
+ * would be true for exactly one of them.
+ *
+ * The usual reason a world gets this wrong is that three's parent chain is a
+ * TRANSFORM chain: `matrixWorld` is unconditionally `parent × local`, so an
+ * object that must not inherit its owner's pose — a physics-driven body writing
+ * a world transform every step, a world-space trail or decal, a follow camera
+ * that must escape its target's rotation — gets mounted at the scene root, and
+ * ownership is lost as a side effect. **That trade is not necessary.** Set
+ * `object.matrixWorldAutoUpdate = false` (three r144+) and the parent's
+ * propagation skips it: the object stays parented where it belongs and its
+ * `matrixWorld` becomes yours to write. Keep it parented, own the matrix, and
+ * the hierarchy needs no help.
+ *
+ * These two marks then have exactly one job left, which is CLASSIFICATION:
+ * which of the objects that really are here is the game, and which is the
+ * machinery underneath it.
+ *
+ * ## What the hierarchy is FOR
+ *
+ * It shows YOUR GAME: the structure you authored, plus the objects your game
+ * makes while it runs. Nothing else. Three consequences, and every rule below
+ * follows from them:
+ *
+ *  - **A spawned object is content.** A bullet you fired, a wave of enemies, a
+ *    prop pulled out of a pool and parented into the level — these are rows.
+ *    They exist, you can select them, and they are usually the exact things you
+ *    opened the panel to look at. An object your game frees stops being a row,
+ *    because it stopped existing.
+ *  - **An implementation artifact is not.** The bones behind a rig, the batched
+ *    renderer behind a particle system, the instanced-mesh pools behind a tile
+ *    field, the `target` object three needs in order to aim a directional
+ *    light: machinery a library or a helper builds so one thing you DID author
+ *    can work. It belongs UNDER that thing, folded, not beside it.
+ *  - **"Not in the source file" is the wrong test for either.** Half of a
+ *    running world is not in the source file — that is what running means.
+ *    Folding spawned gameplay because a document does not name it is the same
+ *    defect as listing bones, in the more damaging direction: the rows it loses
+ *    are the ones you were looking for.
+ *
+ * ## The two marks
+ *
+ * - {@link markComponentRoot} — "this subtree is one instance of `<name>`."
+ *   The editor renders it as ONE row, closed, expandable on demand. Put it on
+ *   the EARLIEST point the node exists: the constructor that makes it, or the
+ *   ref callback that receives it. A component whose root is a plain `<mesh>`
+ *   marks that mesh.
+ * - {@link markBuiltInternal} — "this is IMPLEMENTATION, not content." It is
+ *   **subtree-scoped**: marking the root of a built subtree marks everything
+ *   under it, so a 60-bone rig costs one call and folding is transitive. The
+ *   editor hides these rows and offers them behind the same "Reveal Internals"
+ *   action a source-backed instance's internals already use — revealed rows
+ *   are read-only, because there is no authored source for a rename or a
+ *   reparent to write to.
+ *
+ * An instance therefore reads as the parent of everything meaningful beneath
+ * it: content nested inside an implementation node is listed under the instance
+ * rather than lost with it (the editor's `hierarchy-component-marks.ts` calls
+ * that promotion), so marking a rig does not hide the mesh skinned to it.
+ *
+ * ## Mark it where the subtree is ATTACHED, by whoever attaches it
+ *
+ * A mark belongs at the attach seam: the code that puts an implementation
+ * subtree into the world marks it in the same breath, because that code is the
+ * only thing that knows the subtree is implementation. Not a later sweep of the
+ * tree — "everything present at time T that the source did not name" is the
+ * wrong predicate twice over. It arrives too early for anything attached
+ * asynchronously (a model clone landing after its bytes resolve, a node gated
+ * on an audio decode) and too late in principle for anything attached
+ * afterwards (every spawn) — and were it re-run to catch those, it would
+ * classify each spawned object as implementation, which is the second bullet
+ * above inverted. Attach-seam marking has neither failure: it fires once, at
+ * the moment the answer is known, and an unmarked node is content by default.
+ *
+ * The subtree scope is what keeps this cheap — one call per attached root, not
+ * one per node, so a rig or a pool costs one line at the one place that builds
+ * it.
+ *
+ * ## What is NOT built-internal
+ *
+ * A node your game means as content — even one a class rather than JSX
+ * constructs — is content. `vgaiBuiltInternal` is not "the editor cannot write
+ * this"; that question is `TransformProvider.editability`'s, answered per
+ * channel with a sentence. This mark answers "is this implementation", and
+ * getting it wrong hides real content.
+ *
+ * Both keys live in the typed `userData` registry (`../ecs/user-data.ts`) so
+ * their literal strings are spelled exactly once; this module is the only
+ * reader/writer, which is why the helpers below exist at all rather than
+ * `setUserData` calls scattered through emitters and prefabs.
+ */
+
+import type * as THREE from 'three';
+import { getUserData, setUserData } from '../ecs/user-data';
+
+/**
+ * Declare `node` the root of one component instance, displayed under `name`.
+ *
+ * `name` is the COMPONENT's name (`'Coin'`, `'HeroBox'`), not the instance's —
+ * the instance is already named by `node.name`, and the editor prints both.
+ */
+export function markComponentRoot(node: THREE.Object3D, name: string): void {
+  setUserData(node, 'vgaiComponentRoot', name);
+}
+
+/** The component name `node` is the root of, or `undefined` for an ordinary node. */
+export function componentRootName(node: THREE.Object3D | null | undefined): string | undefined {
+  const name = getUserData(node, 'vgaiComponentRoot');
+  return typeof name === 'string' && name ? name : undefined;
+}
+
+/** Whether `node` is a marked component-instance root. */
+export function isComponentRoot(node: THREE.Object3D | null | undefined): boolean {
+  return componentRootName(node) !== undefined;
+}
+
+/**
+ * Declare `node` (and everything under it) IMPLEMENTATION of whatever node it
+ * sits under, rather than content of its own. Call it on the ROOT of the built
+ * subtree only, at the seam that attaches it — see this module's header for why
+ * the seam and not a sweep.
+ */
+export function markBuiltInternal(node: THREE.Object3D): void {
+  setUserData(node, 'vgaiBuiltInternal', true);
+}
+
+/** Whether `node` itself carries the implementation mark. Ancestry is the
+ *  CALLER's walk — see this module's header for why the mark is subtree-scoped
+ *  but not restamped onto descendants. */
+export function isBuiltInternal(node: THREE.Object3D | null | undefined): boolean {
+  return getUserData(node, 'vgaiBuiltInternal') === true;
+}

package/src/adapter/index.ts

@@ -39,7 +39,6 @@ export type {
   DOMRectLike,
   EditorNode,
   EditorNodeRole,
-  FileMapProvider,
   HierarchyProvider,
   InspectorProvider,
   NodeCreationSite,
@@ -47,8 +46,8 @@ export type {
   PickProvider,
   PropertyDescriptor,
   RectProvider,
-  RootGroup,
-  RootGroupsProvider,
+  RelatedSubjectLink,
+  RelatedSubjectsProvider,
   SelectionProvider,
   SelectionResolution,
   StoriesProvider,