@vgai/engine 0.5.13 → 0.5.15

package/dist/adapter/index.d.ts

@@ -3,7 +3,7 @@
  *
  *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
  *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
- *   game    → SystemAdapters (physics/networking/navigation/audio/debug)
+ *   game    → SystemAdapters (physics/networking/navigation/audio/camera/debug)
  *
  * The first-party Rapier/Colyseus stack is ONE implementer of these
  * interfaces, not the engine's vocabulary..
@@ -23,11 +23,15 @@
  *   `@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, HierarchyProvider, InspectorProvider, NodeCreationSite, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RelatedSubjectLink, RelatedSubjectsProvider, SelectionProvider, SelectionResolution, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformChannel, TransformEditability, TransformObservation, TransformProvider, } from './authoring';
+export type { AssetDropContext, AssetDropProvider, AssetSubjectProvider, AuthoringAdapter, AuthoringAssetSubject, AuthoringCapabilities, AuthoringProvenance, AuthoringProviderKey, BoxEditProvider, BoxEditReferencePoint, ColorSampleProvider, ComponentInstanceApplyResult, ComponentInstanceDescription, ComponentInstanceOverride, ComponentInstancesProvider, CreationSiteProvider, DOMRectLike, EditorNode, EditorNodeRole, HierarchyProvider, InspectorProvider, NodeCreationSite, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RelatedSubjectLink, RelatedSubjectsProvider, SelectionProvider, SelectionResolution, SpatialDragHandle, SpatialHandleGuide, SpatialHandleLayer, SpatialHandlesProvider, SpatialPoint3, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformChannel, TransformEditability, TransformObservation, TransformProvider, WriteAck, WriteAnchorKind, } from './authoring';
+export { AUTHORING_PROVIDER_KEYS, emptyWriteAnchorKindCounts, measureAuthoringProviders, WRITE_ANCHOR_KINDS, } 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';
 export type { MountedSetupThreeRoot, SetupThreeRootConfig } from './setup-three-root-adapter';
-export type { AudioAdapter, AudioDebugEvent, AudioGraphNode, AudioMeterFrame, AudioMeterHandle, AudioTransportState, ConnectionState, NavCrowdAgentState, NavigationAdapter, NavPoint, NetConditioning, NetMessageEvent, NetPeer, NetPlayerIdentity, NetRates, NetServerConfig, NetworkingAdapter, PhysicsAdapter, RenderDebugAdapter, ReplicationStats, RoomInfo, SystemAdapters, Unsubscribe, } from './system-adapter';
+export type { AudioAdapter, AudioDebugEvent, AudioGraphNode, AudioMeterFrame, AudioMeterHandle, AudioRecordingHandle, AudioTransportState, CameraAdapter, CameraRuntimeCamera, CameraRuntimeSnapshot, CameraRuntimeTransition, ConnectionState, NavCrowdAgentState, NavigationAdapter, NavPoint, NetConditioning, NetMessageEvent, NetPeer, NetPlayerIdentity, NetRates, NetServerConfig, NetworkingAdapter, PhysicsAdapter, PhysicsCarrier, PhysicsColliderShape, PhysicsColliderSnapshot, PhysicsJointSnapshot, PhysicsJointType, RenderDebugAdapter, ReplicationStats, RoomInfo, SystemAdapters, Unsubscribe, } from './system-adapter';
+/** The two narrowings of the tagged `SystemAdapters['physics']` union — see
+ *  `PhysicsAdapter`'s comment for why it is tagged at all. */
+export { displayKeyedPhysics, nodeKeyedPhysics } from './system-adapter';
 export type { Transform, TransformOwner } from './transform';
 //# sourceMappingURL=index.d.ts.map

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,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"}
+{"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,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,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,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,QAAQ,EACR,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,GACnB,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,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B;8DAC8D;AAC9D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapter/index.js

@@ -3,7 +3,7 @@
  *
  *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
  *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
- *   game    → SystemAdapters (physics/networking/navigation/audio/debug)
+ *   game    → SystemAdapters (physics/networking/navigation/audio/camera/debug)
  *
  * The first-party Rapier/Colyseus stack is ONE implementer of these
  * interfaces, not the engine's vocabulary..
@@ -22,4 +22,7 @@
  *   `@engine/adapter/colyseus-networking-adapter` createColyseusNetworkingAdapter
  *   `@engine/adapter/first-party-systems`       createNavigationAdapter
  */
-export {};
+export { AUTHORING_PROVIDER_KEYS, emptyWriteAnchorKindCounts, measureAuthoringProviders, WRITE_ANCHOR_KINDS, } from './authoring';
+/** The two narrowings of the tagged `SystemAdapters['physics']` union — see
+ *  `PhysicsAdapter`'s comment for why it is tagged at all. */
+export { displayKeyedPhysics, nodeKeyedPhysics } from './system-adapter';

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

@@ -25,6 +25,20 @@
  * other direction: a wrong "present" claim is as much a defect as a wrong
  * "empty" one.
  *
+ * ## Why `physics` also gets a KEYING check
+ *
+ * The physics slot is the one whose vocabulary follows the SURFACE
+ * ({@link PHYSICS_KEYING_BY_SURFACE}): a three-surface game keys by host node
+ * id, a canvas-surface game by the display object it already holds. Both shapes
+ * carry the same four member names, so presence-and-typeof cannot tell them
+ * apart — a carrier keyed for the other surface would pass every check here and
+ * then be called with values it has none of, which is the "green coverage row
+ * bought with four methods that have no caller" defect this whole slot was left
+ * open to avoid. So a mount that KNOWS its surface says so, and a mismatch is
+ * `malformed` by name. A caller with no surface fact (`undefined`) does not
+ * check — it has nothing to check against, and inventing a default would be a
+ * guess wearing a verdict.
+ *
  * Nothing here calls a declared method. Presence and shape only.
  */
 import type { SystemAdapters } from '../system-adapter';
@@ -32,6 +46,12 @@ 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;
+/**
+ * The render surface a declaration is being read ON — the same three words
+ * `IngestKind`/`AdapterSurface` already use, so nothing has to be declared
+ * twice.
+ */
+export type ContractSurface = 'three' | 'canvas' | 'dom';
 /** 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[];
@@ -59,6 +79,9 @@ export interface ContractSystemAdapterProjection {
  * 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.
+ *
+ * `surface` is the mount's own surface fact when it has one; see the module
+ * header for what it buys and why its absence checks nothing.
  */
-export declare function projectContractSystemAdapters(systems: VgaiGameSystems | undefined | null): ContractSystemAdapterProjection;
+export declare function projectContractSystemAdapters(systems: VgaiGameSystems | undefined | null, surface?: ContractSurface | undefined): ContractSystemAdapterProjection;
 //# sourceMappingURL=contract-system-adapters.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"contract-system-adapters.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/contract-system-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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;AA+B9D;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAezD;oEACoE;AACpE,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAO9D,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;AA8FD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,EAC3C,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,GACpC,+BAA+B,CAoBjC"}

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

@@ -25,6 +25,20 @@
  * other direction: a wrong "present" claim is as much a defect as a wrong
  * "empty" one.
  *
+ * ## Why `physics` also gets a KEYING check
+ *
+ * The physics slot is the one whose vocabulary follows the SURFACE
+ * ({@link PHYSICS_KEYING_BY_SURFACE}): a three-surface game keys by host node
+ * id, a canvas-surface game by the display object it already holds. Both shapes
+ * carry the same four member names, so presence-and-typeof cannot tell them
+ * apart — a carrier keyed for the other surface would pass every check here and
+ * then be called with values it has none of, which is the "green coverage row
+ * bought with four methods that have no caller" defect this whole slot was left
+ * open to avoid. So a mount that KNOWS its surface says so, and a mismatch is
+ * `malformed` by name. A caller with no surface fact (`undefined`) does not
+ * check — it has nothing to check against, and inventing a default would be a
+ * guess wearing a verdict.
+ *
  * Nothing here calls a declared method. Presence and shape only.
  */
 /**
@@ -50,8 +64,21 @@ const REQUIRED_MEMBERS = {
     ],
     navigation: ['hasNavMesh', 'findPath', 'debugMesh'],
     audio: ['setMuted', 'isMuted'],
+    camera: ['snapshot', 'subscribe'],
     renderDebug: ['captureFrame'],
 };
+/**
+ * THE surface→physics-vocabulary rule, stated once.
+ *
+ * `null` for `dom`: that surface has no physics consumer at all, so nothing
+ * here can say which keying would be right for it and the check stands down
+ * rather than inventing an answer.
+ */
+const PHYSICS_KEYING_BY_SURFACE = {
+    three: 'node-id',
+    canvas: 'display',
+    dom: null,
+};
 /** 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 = [
@@ -59,6 +86,7 @@ export const CONTRACT_SYSTEM_SLOTS = [
     'networking',
     'navigation',
     'audio',
+    'camera',
     'renderDebug',
 ];
 const EMPTY_PROJECTION = {
@@ -78,13 +106,77 @@ function missingMembers(slot, value) {
     }
     return missing;
 }
+/**
+ * The reason a declared physics carrier cannot serve `surface`, or `null` when
+ * it can (including when the caller supplied no surface to check against).
+ *
+ * The keying a carrier actually has is its tag's own answer, and an ABSENT tag
+ * IS `'node-id'` — see `PhysicsAdapter`'s comment for why the original
+ * vocabulary is the untagged one.
+ */
+function physicsKeyingMismatch(value, surface) {
+    const want = surface ? PHYSICS_KEYING_BY_SURFACE[surface] : null;
+    if (want === null)
+        return null;
+    const got = value.keyedBy === 'display' ? 'display' : 'node-id';
+    if (got === want)
+        return null;
+    return (`declared a ${got}-keyed physics carrier on the ${surface} surface, whose gizmo path ` +
+        `addresses bodies by ${want} — the four members are all present but nothing on this lane ` +
+        `can call them with values they accept (a ${surface}-surface carrier declares ` +
+        `\`keyedBy: '${want}'\`)`);
+}
+/**
+ * THE per-slot decision, in the order the module header states: is it declared
+ * at all, is it the positively-answered empty, does it carry the members its
+ * interface requires, and (physics only) is it keyed for this surface.
+ *
+ * Split out of {@link projectContractSystemAdapters} so the projection itself
+ * is a loop over verdicts — one place decides, one place files.
+ */
+function classifyDeclaredSlot(slot, value, surface) {
+    if (value === undefined || value === null)
+        return { kind: 'skip' };
+    if (typeof value !== 'object') {
+        return {
+            kind: 'malformed',
+            reason: `declared as ${typeof value}; expected an adapter object or { present: false, evidence }`,
+        };
+    }
+    if (isEmptyRecord(value)) {
+        const evidence = value.evidence;
+        // 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.
+        if (typeof evidence !== 'string' || evidence.trim() === '') {
+            return {
+                kind: 'malformed',
+                reason: 'declared `present: false` with no `evidence` string to back the absence',
+            };
+        }
+        return { kind: 'empty', evidence };
+    }
+    const missing = missingMembers(slot, value);
+    if (missing.length > 0) {
+        return {
+            kind: 'malformed',
+            reason: `declared an adapter missing required member(s): ${missing.join(', ')}`,
+        };
+    }
+    const mismatch = slot === 'physics' ? physicsKeyingMismatch(value, surface) : null;
+    if (mismatch !== null)
+        return { kind: 'malformed', reason: mismatch };
+    return { kind: 'bound' };
+}
 /**
  * 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.
+ *
+ * `surface` is the mount's own surface fact when it has one; see the module
+ * header for what it buys and why its absence checks nothing.
  */
-export function projectContractSystemAdapters(systems) {
+export function projectContractSystemAdapters(systems, surface) {
     const declared = systems?.systemAdapters;
     if (!declared)
         return EMPTY_PROJECTION;
@@ -92,39 +184,13 @@ export function projectContractSystemAdapters(systems) {
     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;
+        const verdict = classifyDeclaredSlot(slot, declared[slot], surface);
+        if (verdict.kind === 'bound')
+            bound[slot] = declared[slot];
+        else if (verdict.kind === 'empty')
+            empty.push({ slot, evidence: verdict.evidence });
+        else if (verdict.kind === 'malformed')
+            malformed.push({ slot, reason: verdict.reason });
     }
     return {
         bound: bound,

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

@@ -18,7 +18,7 @@
  * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
  * (`systems.systemAdapters`).
  */
-import type { AudioAdapter, NavigationAdapter, NetworkingAdapter, PhysicsAdapter, RenderDebugAdapter } from '../system-adapter';
+import type { AudioAdapter, CameraAdapter, NavigationAdapter, NetworkingAdapter, PhysicsCarrier, 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
@@ -34,6 +34,43 @@ export interface VgaiGameLifecycle {
     pause?(): void;
     resume?(): void;
 }
+/** One of the game's own scenes, as {@link VgaiGameScenes} lists it. `id` is the
+ *  game's OWN identifier for it — the string `current()` reports and `goTo()`
+ *  takes — and `label` is what a person reads. */
+export interface VgaiGameScene {
+    id: string;
+    label: string;
+}
+/**
+ * The game's SCENES: the whole-world states it swaps between — screens, levels,
+ * rooms — named by the game itself.
+ *
+ * A multi-screen game's screens ARE its scenes, and the editor already has a
+ * vocabulary for "the design-time states a world can be put into": stories.
+ * So this is projected onto the ordinary `StoriesProvider`
+ * (`adapter/authoring.ts`) by the host's canvas ingest mount
+ * (`packages/editor/src/authoring/contract-scenes-stories.ts`), WORLD-LEVEL —
+ * the same scope the react world adapter's stories have — so the inspector's
+ * story picker lists a game's screens and switching one runs the game's own
+ * navigation call. Nothing else is invented: there is no host-side scene model,
+ * no ordering rule, and no "no scene" state.
+ *
+ * Presence-only, like the rest of this contract. A game that declares nothing
+ * here reports no stories provider at all — a named absence in the coverage
+ * report, never an empty picker.
+ */
+export interface VgaiGameScenes {
+    /** Every scene a player can be sent to right now, in the game's own order. */
+    list(): VgaiGameScene[];
+    /** The scene the game currently has up, by its own id; `null` when it has
+     *  none yet (a game whose entry has not resolved, a boot screen the game does
+     *  not name). */
+    current(): string | null;
+    /** Put the game in that scene the way the game's OWN navigation does. May be
+     *  async — a scene commonly loads its own assets first — and the host awaits
+     *  whatever it returns before reporting the switch. */
+    goTo(id: string): Promise<unknown> | unknown;
+}
 /**
  * One invokable verb the game exposes. Deliberately the SAME listing shape a
  * first-party game gets from `ctx.debug.registerCommand`
@@ -157,12 +194,46 @@ export interface VgaiGameSystemEmpty {
  * for which wins.
  */
 export interface VgaiGameSystemAdapters {
-    physics?: PhysicsAdapter | VgaiGameSystemEmpty;
+    /**
+     * In the SURFACE'S OWN vocabulary: a three-surface game declares the node-id
+     * keyed `PhysicsAdapter`, a canvas-surface game the display-object keyed
+     * `PhysicsAdapter2D` (`keyedBy: 'display'` — the tag is what makes the two
+     * tellable apart, and `contract-system-adapters.ts` reports a carrier keyed
+     * for the wrong surface as MALFORMED by name rather than binding a shape
+     * nothing on that lane can call).
+     */
+    physics?: PhysicsCarrier | VgaiGameSystemEmpty;
     networking?: NetworkingAdapter | VgaiGameSystemEmpty;
     navigation?: NavigationAdapter | VgaiGameSystemEmpty;
     audio?: AudioAdapter | VgaiGameSystemEmpty;
+    camera?: CameraAdapter | VgaiGameSystemEmpty;
     renderDebug?: RenderDebugAdapter | VgaiGameSystemEmpty;
 }
+/**
+ * The game's own READINESS signal — "my world is built; what you see now is
+ * the game".
+ *
+ * A host-mounted (exported-composition) root needs none of this: the host runs
+ * the mount, so mount completion IS readiness and the host answers the question
+ * itself. A SELF-BOOTING game owns its own boot, and the host has no way to see
+ * the end of it — which is why every reader used to measure instead: poll the
+ * draw count, watch `scene.children.length` stop growing, wait a fixed window.
+ * Each of those is a guess at a fact the game's author can state, which is
+ * exactly the shape zero inference names (ARCHITECTURE-CORE §The editor
+ * protocol), so the fix is this declaration slot rather than a better poll.
+ *
+ * Either form is legal, because both are how games already write it: a promise
+ * the game resolves when its boot finishes, or a function returning one (a
+ * callback that resolves/returns when ready). The host normalizes both through
+ * {@link readGameReady} and awaits exactly once per mount.
+ *
+ * Declaring nothing is a supported, first-class answer: the measured waits
+ * remain as the documented fallback. What changes is that they stop being
+ * SILENT — a root with no declaration reports `source: 'measured'` wherever
+ * readiness is reported, so "nobody stated it" is a visible fact rather than
+ * an invisible default.
+ */
+export type VgaiGameReady = Promise<unknown> | (() => Promise<unknown> | unknown);
 export interface VgaiGameContract {
     /** Bump only on breaking shape changes; additive endpoints keep version 1. */
     contractVersion: 1;
@@ -173,7 +244,43 @@ export interface VgaiGameContract {
      * verifies it actually contains the captured canvas before adopting.
      */
     root?: HTMLElement;
+    /**
+     * The canvas the game PRESENTS on — the one whose pixels are "what the game
+     * looks like".
+     *
+     * `root` above answers a different question (which element owns the game's
+     * whole DOM), and a game routinely has more than one canvas inside it: an
+     * offscreen buffer it composites from, a minimap, a 2D overlay. The host's
+     * standing answer was "the first `<canvas>` in DOM order", which is a guess
+     * about authoring order, and the game's author knows the real answer.
+     *
+     * Declaring nothing keeps the measured answer, reported as `measured` (see
+     * `packages/editor/src/presentation-surface.ts`, the one reader).
+     */
+    presentation?: HTMLCanvasElement;
+    /**
+     * The game's own WORLD — the `THREE.Scene` the editor should adopt.
+     *
+     * Without it the host adopts whichever scene renders first that it did not
+     * draw itself (`scene-capture.ts`), which is a good measured default and a
+     * permanent, silent commitment: a splash screen, a shadow pre-pass or a
+     * render-to-texture warm-up that draws one frame earlier is adopted as the
+     * game forever. Declaring this makes the choice the game's, not a race's.
+     *
+     * Typed `object` rather than `THREE.Scene` on purpose — this file is the
+     * contract's shape and imports no renderer library; the host checks
+     * structurally (`isScene`) in {@link readGameWorld}.
+     */
+    world?: object;
+    /** The game's own readiness signal — see {@link VgaiGameReady}. */
+    ready?: VgaiGameReady;
     lifecycle?: VgaiGameLifecycle;
+    /**
+     * The game's own scenes. Absent means "this game declared no scene surface" —
+     * the mount then supplies no stories provider at all, and the coverage report
+     * says so by name.
+     */
+    scenes?: VgaiGameScenes;
     /**
      * The game's own systems. Absent means "this game declared no system
      * surface" — every dependent editor surface then shows a named absence, not
@@ -193,4 +300,83 @@ export interface VgaiGameContract {
  * happens to be asking.
  */
 export declare function readGameContract(scope?: Window | null | undefined): VgaiGameContract | null;
+/** What {@link readGameScenes} found. Both fields `null` ⇒ the game declared no
+ *  scene surface at all, which is a different answer from declaring an unusable
+ *  one (the same distinction `contract-system-adapters.ts` draws between an
+ *  omitted slot and a malformed one). */
+export interface GameScenesReading {
+    /** The callable surface, or `null` when nothing usable was declared. */
+    readonly scenes: VgaiGameScenes | null;
+    /** Why a DECLARED surface was refused, in the words the host prints. */
+    readonly malformed: string | null;
+}
+/**
+ * Read the declared {@link VgaiGameScenes}, refusing a malformed one BY NAME.
+ *
+ * The shape check is the same honesty `projectContractSystemAdapters` applies to
+ * a declared system slot: a `scenes: {}` would otherwise register as a
+ * capability and light up a story picker over an object with no methods. Nothing
+ * here CALLS a declared endpoint — presence and type only.
+ */
+export declare function readGameScenes(contract: VgaiGameContract | null | undefined): GameScenesReading;
+/** What {@link readGameReady} found. `ready: null` with `malformed: null` ⇒ the
+ *  game declared no readiness signal, which is a different answer from
+ *  declaring an unusable one — the same distinction {@link readGameScenes}
+ *  draws, and the reason the readiness facet can report `declared` vs
+ *  `measured` honestly instead of collapsing both into "not ready yet". */
+export interface GameReadyReading {
+    /** The normalized signal: awaiting it once resolves when the game says it is
+     *  ready. `null` when nothing usable was declared. */
+    readonly ready: (() => Promise<unknown>) | null;
+    /** Why a DECLARED signal was refused, in the words the host prints. */
+    readonly malformed: string | null;
+}
+/**
+ * Read the declared {@link VgaiGameReady}, refusing a malformed one BY NAME.
+ *
+ * Both legal forms normalize to one call: a promise is wrapped, a function is
+ * invoked lazily (once, when the host asks — which in the ingest mount is only
+ * AFTER the first captured render, so a `ready` that itself triggers the boot
+ * would deadlock the capture window; games self-boot on this lane),
+ * and whatever the function returns is coerced through `Promise.resolve` —
+ * a synchronous return means "already ready", which is a real declaration.
+ *
+ * A rejected/throwing signal is NOT swallowed here: the host awaits it and its
+ * failure is what separates "crashed before ready" from "never became ready"
+ * in the mount-failure report (`mount-readiness.ts`).
+ */
+export declare function readGameReady(contract: VgaiGameContract | null | undefined): GameReadyReading;
+/** What {@link readGameWorld} found — same two-field honesty as
+ *  {@link readGameScenes}. */
+export interface GameWorldReading {
+    readonly world: object | null;
+    readonly malformed: string | null;
+}
+/**
+ * Read the declared {@link VgaiGameContract.world}, refusing a malformed one BY
+ * NAME.
+ *
+ * STRUCTURAL (`isScene === true`), for two reasons: this file imports no
+ * renderer library, and an `instanceof THREE.Scene` across the realm the game
+ * runs in is exactly the check that silently answers `false` for a good scene —
+ * turning a correct declaration into an unexplained fall-back to first-render.
+ */
+export declare function readGameWorld(contract: VgaiGameContract | null | undefined): GameWorldReading;
+/** What {@link readGamePresentation} found — same two-field honesty as
+ *  {@link readGameScenes}. */
+export interface GamePresentationReading {
+    readonly canvas: HTMLCanvasElement | null;
+    readonly malformed: string | null;
+}
+/**
+ * Read the declared {@link VgaiGameContract.presentation} canvas, refusing a
+ * malformed one BY NAME.
+ *
+ * The shape check is STRUCTURAL (`tagName === 'CANVAS'` plus a `getContext`),
+ * not `instanceof`: the contract is read out of the realm the game runs in, and
+ * a realm-crossing `instanceof` is exactly the check that silently answers
+ * `false` for a perfectly good element. A wrong declaration must be refused by
+ * name, never by accident.
+ */
+export declare function readGamePresentation(contract: VgaiGameContract | null | undefined): GamePresentationReading;
 //# 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;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"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"}

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

@@ -36,3 +36,110 @@ export function readGameContract(scope = typeof window === 'undefined' ? null :
         return null;
     return declared;
 }
+/** The endpoints a scene surface must carry: every one of them is called by the
+ *  projection, so a declaration missing any cannot be honoured. */
+const SCENES_REQUIRED_MEMBERS = ['list', 'current', 'goTo'];
+/**
+ * Read the declared {@link VgaiGameScenes}, refusing a malformed one BY NAME.
+ *
+ * The shape check is the same honesty `projectContractSystemAdapters` applies to
+ * a declared system slot: a `scenes: {}` would otherwise register as a
+ * capability and light up a story picker over an object with no methods. Nothing
+ * here CALLS a declared endpoint — presence and type only.
+ */
+export function readGameScenes(contract) {
+    const declared = contract?.scenes;
+    if (declared === undefined || declared === null)
+        return { scenes: null, malformed: null };
+    if (typeof declared !== 'object') {
+        return {
+            scenes: null,
+            malformed: `declared as ${typeof declared}; expected an object with list(), current() and goTo()`,
+        };
+    }
+    const missing = SCENES_REQUIRED_MEMBERS.filter((member) => typeof declared[member] !== 'function');
+    if (missing.length > 0) {
+        return {
+            scenes: null,
+            malformed: `declared a scenes surface missing required member(s): ${missing.join(', ')}`,
+        };
+    }
+    return { scenes: declared, malformed: null };
+}
+/**
+ * Read the declared {@link VgaiGameReady}, refusing a malformed one BY NAME.
+ *
+ * Both legal forms normalize to one call: a promise is wrapped, a function is
+ * invoked lazily (once, when the host asks — which in the ingest mount is only
+ * AFTER the first captured render, so a `ready` that itself triggers the boot
+ * would deadlock the capture window; games self-boot on this lane),
+ * and whatever the function returns is coerced through `Promise.resolve` —
+ * a synchronous return means "already ready", which is a real declaration.
+ *
+ * A rejected/throwing signal is NOT swallowed here: the host awaits it and its
+ * failure is what separates "crashed before ready" from "never became ready"
+ * in the mount-failure report (`mount-readiness.ts`).
+ */
+export function readGameReady(contract) {
+    const declared = contract?.ready;
+    if (declared === undefined || declared === null)
+        return { ready: null, malformed: null };
+    if (typeof declared === 'function') {
+        const fn = declared;
+        return { ready: () => Promise.resolve(fn()), malformed: null };
+    }
+    if (typeof declared.then === 'function') {
+        const thenable = declared;
+        return { ready: () => Promise.resolve(thenable), malformed: null };
+    }
+    return {
+        ready: null,
+        malformed: `declared \`ready\` as ${typeof declared}; expected a promise or a function returning one`,
+    };
+}
+/**
+ * Read the declared {@link VgaiGameContract.world}, refusing a malformed one BY
+ * NAME.
+ *
+ * STRUCTURAL (`isScene === true`), for two reasons: this file imports no
+ * renderer library, and an `instanceof THREE.Scene` across the realm the game
+ * runs in is exactly the check that silently answers `false` for a good scene —
+ * turning a correct declaration into an unexplained fall-back to first-render.
+ */
+export function readGameWorld(contract) {
+    const declared = contract?.world;
+    if (declared === undefined || declared === null)
+        return { world: null, malformed: null };
+    if (typeof declared !== 'object' || declared.isScene !== true) {
+        return {
+            world: null,
+            malformed: `declared \`world\` as ${typeof declared}; expected the game's own THREE.Scene`,
+        };
+    }
+    return { world: declared, malformed: null };
+}
+/**
+ * Read the declared {@link VgaiGameContract.presentation} canvas, refusing a
+ * malformed one BY NAME.
+ *
+ * The shape check is STRUCTURAL (`tagName === 'CANVAS'` plus a `getContext`),
+ * not `instanceof`: the contract is read out of the realm the game runs in, and
+ * a realm-crossing `instanceof` is exactly the check that silently answers
+ * `false` for a perfectly good element. A wrong declaration must be refused by
+ * name, never by accident.
+ */
+export function readGamePresentation(contract) {
+    const declared = contract?.presentation;
+    if (declared === undefined || declared === null)
+        return { canvas: null, malformed: null };
+    const el = declared;
+    if (typeof el !== 'object' || el.tagName !== 'CANVAS' || typeof el.getContext !== 'function') {
+        return {
+            canvas: null,
+            malformed: `declared \`presentation\` as ${typeof declared === 'object'
+                ? String(el.tagName ?? 'object')
+                : typeof declared}; expected the game's own <canvas> element`,
+        };
+    }
+    return { canvas: declared, malformed: null };
+}