@vgai/engine 0.5.11 → 0.5.13

package/dist/adapter/hierarchy-marks.js

@@ -0,0 +1,148 @@
+/**
+ * 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 { 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, name) {
+    setUserData(node, 'vgaiComponentRoot', name);
+}
+/** The component name `node` is the root of, or `undefined` for an ordinary node. */
+export function componentRootName(node) {
+    const name = getUserData(node, 'vgaiComponentRoot');
+    return typeof name === 'string' && name ? name : undefined;
+}
+/** Whether `node` is a marked component-instance root. */
+export function isComponentRoot(node) {
+    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) {
+    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) {
+    return getUserData(node, 'vgaiBuiltInternal') === true;
+}

package/dist/adapter/index.d.ts

@@ -23,7 +23,7 @@
  *   `@engine/adapter/first-party-systems`       createNavigationAdapter
  */
 export type { AdapterSurface } from './adapter-surface';
-export type { AssetDropContext, AssetDropProvider, AssetSubjectProvider, AuthoringAdapter, AuthoringAssetSubject, AuthoringCapabilities, AuthoringProvenance, BoxEditProvider, BoxEditReferencePoint, ColorSampleProvider, CreationSiteProvider, DOMRectLike, EditorNode, EditorNodeRole, FileMapProvider, HierarchyProvider, InspectorProvider, NodeCreationSite, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RootGroup, RootGroupsProvider, SelectionProvider, SelectionResolution, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformChannel, TransformEditability, TransformObservation, TransformProvider, } from './authoring';
+export type { AssetDropContext, AssetDropProvider, AssetSubjectProvider, AuthoringAdapter, AuthoringAssetSubject, AuthoringCapabilities, AuthoringProvenance, BoxEditProvider, BoxEditReferencePoint, ColorSampleProvider, CreationSiteProvider, DOMRectLike, EditorNode, EditorNodeRole, HierarchyProvider, InspectorProvider, NodeCreationSite, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RelatedSubjectLink, RelatedSubjectsProvider, SelectionProvider, SelectionResolution, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformChannel, TransformEditability, TransformObservation, TransformProvider, } from './authoring';
 export type { ColyseusNetworkingConfig } from './colyseus-networking-adapter';
 export type { CanvasHostContext, DomHostContext, HostContextBase, HostContextFor, HostSurface, ThreeHostContext, } from './host-context';
 export type { MountedPixiRoot, MountedReactRoot, MountedRoot, MountedRootBase, MountedThreeRoot, RootAdapter, RootStateObserver, SurfaceAdapter, SurfaceAdapterFor, } from './root-adapter';

package/dist/adapter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapter/ingest/contract-system-adapters.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Projects a game's declared {@link VgaiGameSystemAdapters}
+ * (`window.vgaiGame.systems.systemAdapters`) onto the host's ordinary
+ * {@link SystemAdapters} bag — the ingest-realm counterpart of a first-party
+ * world's `ctx.registerSystemAdapter`, and the sibling of
+ * `contract-debug-adapter.ts` (which owns the `debug` slot).
+ *
+ * ## Why a projection with a verdict per slot
+ *
+ * The ingestion bar (docs/BRINGING-AN-EXISTING-GAME.md §The ingestion
+ * checklist) admits exactly two terminal states per slot: IMPLEMENTED or
+ * IMPLEMENTED-EMPTY. `SystemAdapters` alone cannot express the second — an
+ * omitted key means "unsupported", which is the same shape as "nobody looked".
+ * So this returns THREE lists, and the caller hands the non-`bound` ones to the
+ * coverage report, where a positively-answered absence prints as terminal and an
+ * unanswered slot prints as a work order.
+ *
+ * ## Why the shape check
+ *
+ * A slot that declares `{}` would otherwise register as "implemented" and light
+ * up an editor panel over an object with no methods. Each slot therefore names
+ * the members its interface makes REQUIRED, and a declaration missing any of
+ * them is `malformed` — reported by name, never silently bound and never
+ * silently dropped. This is the same honesty the anti-shim rule asks of the
+ * other direction: a wrong "present" claim is as much a defect as a wrong
+ * "empty" one.
+ *
+ * Nothing here calls a declared method. Presence and shape only.
+ */
+import type { SystemAdapters } from '../system-adapter';
+import type { VgaiGameSystemAdapters, VgaiGameSystems } from './game-contract';
+/** The slots a game may declare through the contract (`debug` is projected from
+ *  `commands`/`state` instead — see {@link VgaiGameSystemAdapters}). */
+export type ContractSystemSlot = keyof VgaiGameSystemAdapters;
+/** Fixed slot order, so two reports of the same mount are diffable line for
+ *  line (the same rule the coverage report's row order follows). */
+export declare const CONTRACT_SYSTEM_SLOTS: readonly ContractSystemSlot[];
+/** One slot the game positively answered as having nothing behind it. */
+export interface ContractSystemEmptySlot {
+    readonly slot: ContractSystemSlot;
+    /** The game's own source-level evidence, verbatim. */
+    readonly evidence: string;
+}
+/** One slot whose declaration could not be honoured, and why. */
+export interface ContractSystemMalformedSlot {
+    readonly slot: ContractSystemSlot;
+    readonly reason: string;
+}
+export interface ContractSystemAdapterProjection {
+    /** Real adapters, ready to spread onto a `MountedRoot`'s `systems`. */
+    readonly bound: Partial<Pick<SystemAdapters, ContractSystemSlot>>;
+    /** Slots answered IMPLEMENTED-EMPTY, with the evidence. */
+    readonly empty: readonly ContractSystemEmptySlot[];
+    /** Slots declared but unusable — bound to nothing, reported by name. */
+    readonly malformed: readonly ContractSystemMalformedSlot[];
+}
+/**
+ * Read the declared slots and sort each into exactly one verdict. A game that
+ * declared no `systemAdapters` at all projects to three empty lists — which is
+ * the "nobody answered" case, and is deliberately NOT the same as declaring
+ * every slot empty.
+ */
+export declare function projectContractSystemAdapters(systems: VgaiGameSystems | undefined | null): ContractSystemAdapterProjection;
+//# sourceMappingURL=contract-system-adapters.d.ts.map

package/dist/adapter/ingest/contract-system-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-system-adapters.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/contract-system-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAuB,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEpG;wEACwE;AACxE,MAAM,MAAM,kBAAkB,GAAG,MAAM,sBAAsB,CAAC;AA8B9D;oEACoE;AACpE,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAM9D,CAAC;AAEF,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,+BAA+B;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAClE,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,2BAA2B,EAAE,CAAC;CAC5D;AAsBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,GAC1C,+BAA+B,CAgDjC"}

package/dist/adapter/ingest/contract-system-adapters.js

@@ -0,0 +1,134 @@
+/**
+ * Projects a game's declared {@link VgaiGameSystemAdapters}
+ * (`window.vgaiGame.systems.systemAdapters`) onto the host's ordinary
+ * {@link SystemAdapters} bag — the ingest-realm counterpart of a first-party
+ * world's `ctx.registerSystemAdapter`, and the sibling of
+ * `contract-debug-adapter.ts` (which owns the `debug` slot).
+ *
+ * ## Why a projection with a verdict per slot
+ *
+ * The ingestion bar (docs/BRINGING-AN-EXISTING-GAME.md §The ingestion
+ * checklist) admits exactly two terminal states per slot: IMPLEMENTED or
+ * IMPLEMENTED-EMPTY. `SystemAdapters` alone cannot express the second — an
+ * omitted key means "unsupported", which is the same shape as "nobody looked".
+ * So this returns THREE lists, and the caller hands the non-`bound` ones to the
+ * coverage report, where a positively-answered absence prints as terminal and an
+ * unanswered slot prints as a work order.
+ *
+ * ## Why the shape check
+ *
+ * A slot that declares `{}` would otherwise register as "implemented" and light
+ * up an editor panel over an object with no methods. Each slot therefore names
+ * the members its interface makes REQUIRED, and a declaration missing any of
+ * them is `malformed` — reported by name, never silently bound and never
+ * silently dropped. This is the same honesty the anti-shim rule asks of the
+ * other direction: a wrong "present" claim is as much a defect as a wrong
+ * "empty" one.
+ *
+ * Nothing here calls a declared method. Presence and shape only.
+ */
+/**
+ * The members each slot's interface makes NON-optional. A declaration missing
+ * one of these cannot honour the interface, whatever else it carries.
+ *
+ * This table is the single place the required surface is spelled; it is checked
+ * against the interfaces by the compiler at the point of use below (each list
+ * is typed as keys of its own adapter), so it cannot drift into naming a member
+ * that does not exist.
+ */
+const REQUIRED_MEMBERS = {
+    physics: ['ownerOf', 'freeze', 'commit', 'unfreeze'],
+    networking: [
+        'peers',
+        'networkId',
+        'authority',
+        'editable',
+        'getConnectionState',
+        'getRoomInfo',
+        'getReplicationStats',
+        'subscribe',
+    ],
+    navigation: ['hasNavMesh', 'findPath', 'debugMesh'],
+    audio: ['setMuted', 'isMuted'],
+    renderDebug: ['captureFrame'],
+};
+/** Fixed slot order, so two reports of the same mount are diffable line for
+ *  line (the same rule the coverage report's row order follows). */
+export const CONTRACT_SYSTEM_SLOTS = [
+    'physics',
+    'networking',
+    'navigation',
+    'audio',
+    'renderDebug',
+];
+const EMPTY_PROJECTION = {
+    bound: {},
+    empty: [],
+    malformed: [],
+};
+function isEmptyRecord(value) {
+    return value.present === false;
+}
+function missingMembers(slot, value) {
+    const missing = [];
+    for (const member of REQUIRED_MEMBERS[slot]) {
+        if (typeof value[member] !== 'function') {
+            missing.push(member);
+        }
+    }
+    return missing;
+}
+/**
+ * Read the declared slots and sort each into exactly one verdict. A game that
+ * declared no `systemAdapters` at all projects to three empty lists — which is
+ * the "nobody answered" case, and is deliberately NOT the same as declaring
+ * every slot empty.
+ */
+export function projectContractSystemAdapters(systems) {
+    const declared = systems?.systemAdapters;
+    if (!declared)
+        return EMPTY_PROJECTION;
+    const bound = {};
+    const empty = [];
+    const malformed = [];
+    for (const slot of CONTRACT_SYSTEM_SLOTS) {
+        const value = declared[slot];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== 'object') {
+            malformed.push({
+                slot,
+                reason: `declared as ${typeof value}; expected an adapter object or { present: false, evidence }`,
+            });
+            continue;
+        }
+        if (isEmptyRecord(value)) {
+            const evidence = value.evidence;
+            if (typeof evidence !== 'string' || evidence.trim() === '') {
+                // An empty claim with no evidence is exactly the "wrong empty claim"
+                // the bar calls a defect — it asserts an absence nobody can re-check.
+                malformed.push({
+                    slot,
+                    reason: 'declared `present: false` with no `evidence` string to back the absence',
+                });
+                continue;
+            }
+            empty.push({ slot, evidence });
+            continue;
+        }
+        const missing = missingMembers(slot, value);
+        if (missing.length > 0) {
+            malformed.push({
+                slot,
+                reason: `declared an adapter missing required member(s): ${missing.join(', ')}`,
+            });
+            continue;
+        }
+        bound[slot] = value;
+    }
+    return {
+        bound: bound,
+        empty,
+        malformed,
+    };
+}

package/dist/adapter/ingest/game-contract.d.ts

@@ -15,8 +15,10 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
+ * (`systems.systemAdapters`).
  */
+import type { AudioAdapter, NavigationAdapter, NetworkingAdapter, PhysicsAdapter, RenderDebugAdapter } from '../system-adapter';
 /**
  * Session lifecycle endpoints. Declaring `start` means "I support cold
  * mount": when the host sets `window.__vgaiMountCold` before the game's entry
@@ -62,6 +64,27 @@ export interface VgaiGameStateProvider {
     tier?: 'observable' | 'assisted';
     read(): unknown;
 }
+/**
+ * One top-level semantic hierarchy group from the game's OWN model. `count`
+ * is recomputed by the game when the host reads the hierarchy; it is not
+ * inferred from render objects. The editor presents these rows beside the
+ * captured render tree, so a system-driven game can say what its content is
+ * without pretending its scene graph is authored truth.
+ */
+export interface VgaiGameHierarchyGroup {
+    id: string;
+    label: string;
+    count: number;
+}
+/**
+ * Synchronous read plus an optional game-owned invalidation signal. The
+ * editor never polls or guesses when a game's model changed; a dynamic game
+ * subscribes its ordinary authoring hierarchy to the same truth it reads.
+ */
+export interface VgaiGameHierarchyProvider {
+    (): VgaiGameHierarchyGroup[];
+    subscribe?(listener: () => void): () => void;
+}
 /**
  * The game's SYSTEM surface: what its content actually IS, as opposed to how
  * it renders. An ingested game's content is not always its scene graph — in a
@@ -69,9 +92,10 @@ export interface VgaiGameStateProvider {
  * is reached through the game's own verbs, which `root`/`lifecycle` could not
  * express.
  *
- * Both members are read by exactly one consumer,
- * `adapter/ingest/contract-debug-adapter.ts`, which projects them onto the
- * host's ordinary `DebugAdapter` (`adapter/system-adapter.ts`) — so
+ * Every member is read by a concrete consumer: commands/state are projected
+ * by `adapter/ingest/contract-debug-adapter.ts` onto the host's ordinary
+ * `DebugAdapter` (`adapter/system-adapter.ts`), while `hierarchy` is projected
+ * by the editor onto the ordinary `AuthoringAdapter.hierarchy` surface. Thus
  * `game.commands()`/`game.state()` reach an ingested game through the same
  * bridge first-party content uses, with no second vocabulary for agents to
  * learn. That is deliberate scope: this
@@ -84,6 +108,60 @@ export interface VgaiGameSystems {
     commands?: VgaiGameCommand[];
     /** State reads, enumerated by `game.providers()` and read by `game.state(...)`. */
     state?: VgaiGameStateProvider[];
+    /** Semantic hierarchy groups from the game's own model, recomputed on read. */
+    hierarchy?: VgaiGameHierarchyProvider;
+    /**
+     * The game's own {@link SystemAdapters} slots — the ingest-realm equivalent
+     * of a first-party world's `ctx.registerSystemAdapter`. Read and projected by
+     * `contract-system-adapters.ts` onto the mounted root's `systems` bag, so an
+     * ingested game's physics/audio/navigation/networking reach the editor's
+     * ordinary panels through the SAME registry a native world publishes to.
+     */
+    systemAdapters?: VgaiGameSystemAdapters;
+}
+/**
+ * A slot's IMPLEMENTED-EMPTY answer: "this game genuinely has no X", carried
+ * with the source-level evidence that establishes it.
+ *
+ * This exists because `SystemAdapters` is capability-by-PRESENCE, and presence
+ * has only two values while the ingestion bar (docs/BRINGING-AN-EXISTING-GAME.md
+ * §The ingestion checklist) has three inputs: bound, positively-absent, and
+ * not-yet-answered. Omitting a slot cannot tell the last two apart — an editor
+ * reading a bare absence cannot know whether anyone ever looked. Declaring this
+ * record says someone looked, says what they found, and turns a work-order row
+ * into a terminal one.
+ *
+ * It is deliberately NOT an adapter whose methods return zeros: a
+ * `getConnectionState()` of `'disconnected'` on a game with no transport at all
+ * is a fabrication (it implies a connection that could exist), which the
+ * anti-shim rule forbids. The absence is stated, never simulated.
+ */
+export interface VgaiGameSystemEmpty {
+    /** Always `false` — the discriminant that separates this from an adapter. */
+    present: false;
+    /**
+     * Why the slot is empty, in SOURCE terms: what was searched and what was
+     * found. "no netcode anywhere in `src/`" is a finished answer; "not
+     * implemented yet" is not one, and a reviewer reading this field is meant to
+     * be able to re-run the search.
+     */
+    evidence: string;
+}
+/**
+ * The declarable `SystemAdapters` slots, each either a real implementation or a
+ * positively-answered {@link VgaiGameSystemEmpty}.
+ *
+ * `debug` is deliberately NOT here: it is already the projection of
+ * `commands`/`state` above (`contract-debug-adapter.ts`), and a second door onto
+ * the same slot would let a game declare two different debug planes with no rule
+ * for which wins.
+ */
+export interface VgaiGameSystemAdapters {
+    physics?: PhysicsAdapter | VgaiGameSystemEmpty;
+    networking?: NetworkingAdapter | VgaiGameSystemEmpty;
+    navigation?: NavigationAdapter | VgaiGameSystemEmpty;
+    audio?: AudioAdapter | VgaiGameSystemEmpty;
+    renderDebug?: RenderDebugAdapter | VgaiGameSystemEmpty;
 }
 export interface VgaiGameContract {
     /** Bump only on breaking shape changes; additive endpoints keep version 1. */
@@ -108,11 +186,11 @@ export interface VgaiGameContract {
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
  *
- * `scope` is the REALM to read from, and defaults to this module's own `window`
- * — correct for a same-realm mount, where the game's modules and the host share
- * one global. An iframe-hosted game declares on ITS realm's window, so the host
- * passes `iframe.contentWindow`: the contract is a property of the realm the
- * game runs in, never of the realm that happens to be asking.
+ * `scope` is the REALM to read from, and defaults to this module's own
+ * `window` — the realm every ingest mount runs the game's modules in, where the
+ * game and the host share one global. It is a parameter at all because the
+ * contract is a property of the realm the game runs in, never of the realm that
+ * happens to be asking.
  */
 export declare function readGameContract(scope?: Window | null | undefined): VgaiGameContract | null;
 //# sourceMappingURL=game-contract.d.ts.map

package/dist/adapter/ingest/game-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,IAAI,IAAI,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,eAAe,EAAE,CAAC,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,GAAG,IAAI,GAAG,SAAyD,GAC/E,gBAAgB,GAAG,IAAI,CAKzB"}
+{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,IAAI,IAAI,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,sBAAsB,EAAE,CAAC;IAC7B,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAChC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,OAAO,EAAE,KAAK,CAAC;IACf;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,cAAc,GAAG,mBAAmB,CAAC;IAC/C,UAAU,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;IACrD,UAAU,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;IACrD,KAAK,CAAC,EAAE,YAAY,GAAG,mBAAmB,CAAC;IAC3C,WAAW,CAAC,EAAE,kBAAkB,GAAG,mBAAmB,CAAC;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,eAAe,EAAE,CAAC,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,GAAG,IAAI,GAAG,SAAyD,GAC/E,gBAAgB,GAAG,IAAI,CAKzB"}

package/dist/adapter/ingest/game-contract.js

@@ -15,18 +15,19 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
+ * (`systems.systemAdapters`).
  */
 /**
  * Read the declared contract, if any. The `contractVersion` gate is the
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
  *
- * `scope` is the REALM to read from, and defaults to this module's own `window`
- * — correct for a same-realm mount, where the game's modules and the host share
- * one global. An iframe-hosted game declares on ITS realm's window, so the host
- * passes `iframe.contentWindow`: the contract is a property of the realm the
- * game runs in, never of the realm that happens to be asking.
+ * `scope` is the REALM to read from, and defaults to this module's own
+ * `window` — the realm every ingest mount runs the game's modules in, where the
+ * game and the host share one global. It is a parameter at all because the
+ * contract is a property of the realm the game runs in, never of the realm that
+ * happens to be asking.
  */
 export function readGameContract(scope = typeof window === 'undefined' ? null : window) {
     const declared = scope

package/dist/adapter/ingest/scene-capture.d.ts

@@ -67,11 +67,11 @@ export interface SceneCaptureOptions {
      * each with its own offscreen renderer and its own little light rig) is a
      * candidate to be captured AS THE GAME.
      *
-     * That is what made `cov-mismatched-three` — the spec for "a game bundling
-     * its own three is DETECTED and degrades to embed-only, never silently" —
+     * That is what made the "a game bundling its own three is DETECTED, never
+     * silently mistaken for a capture" spec
      * pass or fail on timing alone: whether a thumbnail happened to bake inside
-     * the game's 2.5s capture window. When it did, the editor adopted its own
-     * preview scene as the game and `captureFailed` never fired.
+     * the game's capture window. When it did, the editor adopted its own
+     * preview scene as the game and the mount reported success.
      *
      * Identity, not shape, is the discriminator: a host renderer and a game
      * renderer are the same class, both built after install, both drawing real
@@ -80,10 +80,37 @@ export interface SceneCaptureOptions {
      */
     isHostRenderer?: (renderer: unknown) => boolean;
 }
+/**
+ * Brackets ONE `render()` call the captured renderer makes.
+ *
+ * The trap already stands between an ingested game and its own
+ * `WebGLRenderer.render`, which is the only place a host can see the game's
+ * render pass begin and end — the game owns its loop, so nothing else in the
+ * editor gets a `finally` around it. That is exactly the bracket
+ * `dev/render-debug-adapter.ts`'s `beforeRender`/`afterRender` need, so the
+ * first-party `RenderDebugAdapter` works for an ingested game with no per-game
+ * shimming and no second capture mechanism.
+ *
+ * Neither hook may throw: they run inside the game's own render call, so an
+ * exception here would break the game's frame. The trap calls them in a
+ * `try`/`finally` for `after`, but a throwing `before` is the hook author's bug.
+ */
+export interface RenderPassHooks {
+    before(): void;
+    after(): void;
+}
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
     /** The captured runtime, or null until the game renders its first frame. */
     readonly captured: CapturedRuntime | null;
+    /**
+     * Install (or clear, with `null`) hooks bracketing every `render()` the
+     * CAPTURED renderer makes. Set AFTER capture, because the consumer
+     * (`RenderDebugAdapter`) is built from the captured scene and context. Only
+     * the captured renderer's renders are bracketed — the editor's own viewport
+     * renders come through the same trap and are not the game's frame.
+     */
+    setRenderPassHooks(hooks: RenderPassHooks | null): void;
     /** Resolve once a scene+camera is captured (rejects on timeout). */
     waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
     /** Total `render()` calls observed through the trap (a liveness signal). */

package/dist/adapter/ingest/scene-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;CAC/B;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACjD;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C,oEAAoE;IACpE,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,YAAY,IAAI,MAAM,CAAC;IACvB;gFAC4E;IAC5E,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAAC;CACnB;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,OAAO,EACvB,kBAAkB,CAAC,EAAE,OAAO,EAC5B,IAAI,CAAC,EAAE,mBAAmB,GACzB,kBAAkB,CA8MpB"}
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;CAC/B;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACjD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IACxD,oEAAoE;IACpE,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,YAAY,IAAI,MAAM,CAAC;IACvB;gFAC4E;IAC5E,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAAC;CACnB;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,OAAO,EACvB,kBAAkB,CAAC,EAAE,OAAO,EAC5B,IAAI,CAAC,EAAE,mBAAmB,GACzB,kBAAkB,CAoOpB"}