@vgai/engine 0.5.21 → 0.5.23

package/src/adapter/authoring.ts

@@ -2,8 +2,8 @@
  * AuthoringAdapter — the editor's authoring contract. The editor talks to THIS,
  * keyed by opaque string node ids, instead of to a concrete document format.
  *
- * `.vscn` / `SceneEntity` is the private model of ONE implementer
- * (`VgaiSceneAuthoringAdapter`); an ingested game's adapter implements the same
+ * An implementer's document model is its own private business; an ingested
+ * game's adapter implements the same
  * providers directly over its live `Object3D` tree. The editor sees only the
  * interface and the advertised `capabilities` — it never branches on which
  * implementer it is talking to.
@@ -29,8 +29,7 @@ import type { Transform } from './transform';
  * Deliberately SMALL: a capability flag earns its place only when the shell
  * actually branches on it. Structural affordances (create/delete/reparent) are
  * gated by `structure` PROVIDER PRESENCE instead — the flag and the provider
- * cannot disagree that way. (WO-2 deleted `material`/`create`/`delete`/
- * `reparent`/`layout`, which no shell code ever read.)
+ * cannot disagree that way.
  */
 export interface AuthoringCapabilities {
   transform: boolean;
@@ -89,7 +88,7 @@ export type EditorNodeRole =
   | 'entity'
   | 'boundary';
 
-/** A node in the authoring hierarchy — format-neutral (not a `SceneEntity`). */
+/** A node in the authoring hierarchy — format-neutral. */
 export interface EditorNode {
   /** STABLE id — survives reload (see ingest structural-path ids). */
   id: string;
@@ -202,9 +201,9 @@ export interface SelectionProvider {
 }
 
 /** Adapter-owned result of semantic selection resolution: the raw native/render
- * hit mapped to the node the author actually means. (The former
- * `inspectorId`/`transformId`/`boundaryId` aliases were never read by the
- * shell — deleted in WO-2.) */
+ * hit mapped to the node the author actually means. ONE id, deliberately:
+ * separate inspector/transform/boundary aliases would have to agree, and
+ * nothing in the shell can enforce that. */
 export interface SelectionResolution {
   /** Hierarchy selection and Inspector subject. */
   id: string;
@@ -316,7 +315,7 @@ export interface TransformObservation {
 }
 
 export interface InspectorProvider {
-  /** Schema-driven — NOT fixed to `SceneEntity`. */
+  /** Schema-driven — fixed to no document format. */
   properties(id: string): PropertyDescriptor[];
   get(id: string, path: string): unknown;
   /**
@@ -620,24 +619,24 @@ export interface PersistenceProvider {
    * subsequent persistence clears it. Auto-saving source adapters use this to
    * report a rolled-back source write without inventing a dirty document. */
   lastError?(): string | null;
-  /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
+  /** Save to the adapter's OWN source of truth (its source file, its own
+   *  data, …) — whatever that adapter defines it to be. */
   save(): Promise<void>;
   /**
    * Human/agent-readable destination this provider persists to — e.g.
-   * `"scenes/main.vscn.json"`, `"live-only (not saved)"`, or `"ephemeral
+   * `"src/world.tsx"`, `"live-only (not saved)"`, or `"ephemeral
    * (discarded on stop)"`. Drives the save-status UI and makes routing
    * inspectable (design §2). Implementers whose destination can change during
-   * the session (e.g. the first-party provider tracks the loaded `.vscn` path)
+   * the session (a provider that tracks the currently focused document, say)
    * should expose this as a live getter rather than a value captured once.
    */
   readonly destination: string;
   /**
    * The reload contract (design §5): apply an external change to this
    * provider's persisted artifact into the RUNNING session (e.g. a file-watcher
-   * update to the `.vscn` or the overlay). Absent ⇒ the host must remount to
-   * pick up external changes (the honest floor). Implemented (T3.2 slice 3) by
-   * the first-party provider (`applyExternalUpdate`) and the ingest overlay
-   * provider (`applyOverlay`); absent (correctly) on the ephemeral provider.
+   * update to the artifact). Absent ⇒ the host must remount to
+   * pick up external changes — the honest floor, and correctly what the
+   * ephemeral provider reports.
    *
    * `rawContent`, when the host has it (the file-watcher SSE payload carries the
    * artifact's exact bytes), is an OPTIONAL second parameter enabling own-echo
@@ -823,7 +822,7 @@ export interface ColorSampleProvider {
 }
 
 /**
- * WO-IDX1 — where a node's live object CAME FROM in the game's own truth.
+ * Where a node's live object CAME FROM in the game's own truth.
  *
  * `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
@@ -1172,10 +1171,9 @@ export interface AuthoringAdapter {
    * Observe transform GESTURES on this adapter's nodes — the one seam the
    * animation sequencer needs to record a drag as keyframes and to refresh its
    * design baselines. Deliberately narrow (one event shape, one consumer, no
-   * general event bus): before it existed, the sequencer could only observe
-   * the first-party store's own `.vscn` transform path, so a live or
-   * source-backed world's gestures were invisible to it. Absent ⇒ this
-   * adapter reports no gestures.
+   * general event bus): without it the sequencer can only observe the store's
+   * own transform path, so a live or source-backed world's gestures are
+   * invisible to it. Absent ⇒ this adapter reports no gestures.
    */
   observeTransforms?(listener: (event: TransformObservation) => void): () => void;
 }

package/src/adapter/binding.ts

@@ -0,0 +1,468 @@
+/**
+ * THE ROOT BINDING — a game's declaration of itself, bound, as ONE host-side
+ * value.
+ *
+ * A game is a native program plus a declaration of itself; the editor is a
+ * universal client of that declaration; the host must not know what it is
+ * hosting. Today that declaration arrives at the host as a scatter — a
+ * `RootInstance`, a `MountedRoot`, an `AuthoringAdapter` provider bag, a
+ * `SystemAdapters` slot map, a `ResolvedAdapterRoot`, a parsed
+ * `AdapterDefinition` — and every consumer re-assembles its own subset by
+ * hand. `RootBinding` is that same material REGROUPED under one name, by the
+ * FIVE protocol families a host actually talks in.
+ *
+ * ## This file declares the vocabulary AND performs the regrouping
+ *
+ * {@link createRootBinding} is the one place the five families are assembled,
+ * and it is a pure re-address of values it is HANDED — it loads nothing,
+ * fetches nothing, and constructs no provider. The editor's
+ * `binding-resolver.ts` (`resolveRootBinding(root, realm, adapterDef)`) is what
+ * gathers those values per realm and calls this; `RootInstance.binding`
+ * (`runtime/game.ts`) is where the result lives for the life of the mount.
+ * Keeping the assembly here rather than in the resolver is what makes the
+ * reference-equality rule below checkable in ONE function instead of once per
+ * realm.
+ *
+ * ## The one rule that makes this a regrouping and not an abstraction
+ *
+ * **Every member is a REFERENCE to the thing that already exists — never a
+ * facade, never a copy, never a wrapper.** `substrate.mounted` IS the
+ * `MountedRoot` the adapter returned. `observation.debugRegistry` IS the ONE
+ * game-scoped registry every root of that game shares (this binding neither
+ * owns it nor tears it down). And the providers that are read AND written
+ * through — `selection`, `transforms`, `inspector`, `instances`,
+ * `spatialHandles`, `boxEdit`, `text` — appear in BOTH
+ * {@link ProjectionBinding} and {@link TruthBinding} as literally the same
+ * object, so `binding.projection.selection === binding.truth.selection`. A
+ * facade at either address would make the two views disagree the first time
+ * anything stateful moved through one of them; reference equality is what
+ * makes "regrouping" a checkable claim instead of a promise.
+ */
+
+import type { ResolvedAdapterRoot } from '../manifest/load';
+import type { DebugRegistry } from '../runtime/debug-registry';
+import type { AdapterDefinition } from './adapter-module';
+import type {
+  AssetDropProvider,
+  AssetSubjectProvider,
+  AuthoringCapabilities,
+  AuthoringProvenance,
+  BoxEditProvider,
+  ColorSampleProvider,
+  ComponentInstancesProvider,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  RectProvider,
+  RelatedSubjectsProvider,
+  SelectionProvider,
+  SpatialHandlesProvider,
+  StoriesProvider,
+  StructureProvider,
+  TextProvider,
+  TransformObservation,
+  TransformProvider,
+  TruthProvider,
+} from './authoring';
+import type { NativeDebugBinding, NativeSystemsBinding } from './native-debug-module';
+import type { MountedRoot, RootStateObserver, SurfaceAdapter } from './root-adapter';
+import type { SystemAdapters } from './system-adapter';
+
+/**
+ * THE PROTOCOL VOCABULARY — the five families a host talks to a root in, and
+ * the ONLY place they are enumerated.
+ *
+ * This union is the single enumeration on purpose: `RootBinding`'s keys are
+ * pinned to it by {@link RootBindingKeysAreExactlyTheProtocolFamilies} below,
+ * so a sixth family cannot be added at one address and forgotten at the
+ * other, and no second list of these names may exist anywhere in the repo
+ * (`adapter-binding-protocol-families.test.ts` is the tripwire).
+ */
+export type ProtocolFamily = 'substrate' | 'projection' | 'truth' | 'observation' | 'project';
+
+/**
+ * WHAT MOUNTED, AND HOW IT RUNS.
+ *
+ * The adapter that produced the mount, the mount itself, and the two
+ * lifecycle facts that are properties of the ROOT rather than of the mounted
+ * handle (`pausable` is the manifest's per-world play/pause semantics;
+ * `loop` is the declared loop model the loop gate reports against). Every
+ * other lifecycle member — `update`, `fixedUpdate`, `setPaused`, `step`,
+ * `resize`, `dispose`, `disposeComplete`, `drivesOwnLoop` — is reached
+ * through `mounted`, unrepeated, because repeating them here would be the
+ * facade this binding exists not to be.
+ */
+export interface SubstrateBinding {
+  /** The surface-tagged adapter the resolver produced for this root. */
+  readonly adapter: SurfaceAdapter;
+  /** The handle the adapter's `mount` returned — the same object, not a view. */
+  readonly mounted: MountedRoot;
+  /** Per-world play/pause semantics (D10's per-world default is `true`). */
+  readonly pausable: boolean;
+  /** The declared loop model: host-ticked, or the game owns its own rAF. */
+  readonly loop: ResolvedAdapterRoot['loop'];
+}
+
+/**
+ * READ VIEWS of the provider set — what the editor's panels ASK this root.
+ *
+ * `capabilities` and `hierarchy` are required because an `AuthoringAdapter`
+ * cannot exist without them; every other member is optional and absent means
+ * "this root does not support that", never a fabricated empty.
+ *
+ * The seven members marked STRADDLER also appear on {@link TruthBinding}, as
+ * the same object (see this module's header).
+ */
+export interface ProjectionBinding {
+  readonly capabilities: AuthoringCapabilities;
+  readonly hierarchy: HierarchyProvider;
+  readonly provenance?: AuthoringProvenance | undefined;
+  /** STRADDLER. */
+  readonly selection?: SelectionProvider | undefined;
+  /** STRADDLER. */
+  readonly transforms?: TransformProvider | undefined;
+  /** STRADDLER. */
+  readonly inspector?: InspectorProvider | undefined;
+  /** STRADDLER. */
+  readonly instances?: ComponentInstancesProvider | undefined;
+  /** STRADDLER. */
+  readonly spatialHandles?: SpatialHandlesProvider | undefined;
+  /** STRADDLER. */
+  readonly boxEdit?: BoxEditProvider | undefined;
+  /** STRADDLER. */
+  readonly text?: TextProvider | undefined;
+  readonly assetSubject?: AssetSubjectProvider | undefined;
+  readonly related?: RelatedSubjectsProvider | undefined;
+  readonly rects?: RectProvider | undefined;
+  readonly pickable?: PickProvider | undefined;
+  readonly stories?: StoriesProvider | undefined;
+  readonly colorSample?: ColorSampleProvider | undefined;
+}
+
+/**
+ * WRITE VIEWS of the provider set — what an authored edit goes THROUGH.
+ *
+ * The write-only members (`structure`, `persistence`, `truth`, `assetDrop`)
+ * plus the seven straddlers, which are the same objects the projection holds.
+ */
+export interface TruthBinding {
+  readonly structure?: StructureProvider | undefined;
+  readonly persistence?: PersistenceProvider | undefined;
+  /** Projection subject → source/data anchor and write lane, resolved together. */
+  readonly truth?: TruthProvider | undefined;
+  readonly assetDrop?: AssetDropProvider | undefined;
+  /** STRADDLER. */
+  readonly selection?: SelectionProvider | undefined;
+  /** STRADDLER. */
+  readonly transforms?: TransformProvider | undefined;
+  /** STRADDLER. */
+  readonly inspector?: InspectorProvider | undefined;
+  /** STRADDLER. */
+  readonly instances?: ComponentInstancesProvider | undefined;
+  /** STRADDLER. */
+  readonly spatialHandles?: SpatialHandlesProvider | undefined;
+  /** STRADDLER. */
+  readonly boxEdit?: BoxEditProvider | undefined;
+  /** STRADDLER. */
+  readonly text?: TextProvider | undefined;
+}
+
+/**
+ * WHAT THIS ROOT LETS ANYONE WATCH — references only.
+ *
+ * `debugRegistry` is the ONE registry the whole Game shares. This binding
+ * holds a reference to it and nothing more: it never creates it, never
+ * disposes it, and per-root teardown must not end it (a game-scoped resource
+ * destroyed by a root-scoped teardown is a bug this repo has already paid
+ * for once).
+ *
+ * `entryDebug`/`entrySystems` are the entry module's own statically declared
+ * bindings, harvested at resolve time and INSTALLED post-mount by
+ * `adapter-runtime-bindings` — they ride here rather than being re-read from
+ * the module a second time.
+ */
+export interface ObservationBinding {
+  /** The root's system-adapter slots (physics/networking/navigation/audio/debug). */
+  readonly systems?: SystemAdapters | undefined;
+  /** Reference to the game-scoped registry. Never owned, never disposed here. */
+  readonly debugRegistry: DebugRegistry | null;
+  /** The ingested-world observation contract, when the adapter has one. */
+  readonly observe?: RootStateObserver | undefined;
+  /** Change notification → UI refresh. */
+  readonly subscribe?: ((listener: () => void) => () => void) | undefined;
+  /** Transform GESTURE observation — the animation sequencer's one seam. */
+  readonly observeTransforms?:
+    | ((listener: (event: TransformObservation) => void) => () => void)
+    | undefined;
+  /** The entry module's `debug` export, already validated. */
+  readonly entryDebug?: NativeDebugBinding | undefined;
+  /** The entry module's `systems` export, already validated. */
+  readonly entrySystems?: NativeSystemsBinding | undefined;
+}
+
+/**
+ * The entry module's static surface, WITH the realm's reduction stated.
+ *
+ * In dev, browser-storage and packaged realms the host holds the entry
+ * module's whole namespace. On the hosted deployment there is no `/@fs`, so
+ * what exists is a build-time bundle map and the host holds only the four
+ * keys that map carries. Saying so in the type is the point: a
+ * `Record<string, unknown>` at both addresses would let a consumer reach for
+ * an export that CANNOT be there on the hosted lane and only find out at
+ * runtime, on the deployment, in someone else's browser.
+ */
+export type EntryStaticSurface =
+  | {
+      readonly reach: 'full';
+      /** The entry module's own namespace object. */
+      readonly module: Record<string, unknown>;
+    }
+  | {
+      readonly reach: 'bundleSubset';
+      readonly module: BundledEntrySubset;
+    };
+
+/** Everything the hosted build's bundle map carries for one root. */
+export interface BundledEntrySubset {
+  /** The entry's default-exported world component. */
+  readonly default: unknown;
+  readonly debug?: unknown;
+  readonly systems?: unknown;
+  readonly components?: unknown;
+}
+
+/**
+ * WHAT THE PROJECT DECLARED — the manifest root, the parsed `vgai.adapter.ts`
+ * definition, and the entry's static surface.
+ *
+ * `vgai.adapter.ts` LOADING stays where it is (`project-adapter.ts`); its
+ * parsed result is an INPUT to `resolveRootBinding`, not something this
+ * binding goes and fetches. That is deliberate: the binding is the hand-off's
+ * shape, never a second loader.
+ */
+export interface ProjectBinding {
+  /** The manifest's own resolved root record. */
+  readonly root: ResolvedAdapterRoot;
+  /**
+   * The project's parsed `vgai.adapter.ts`, or `null` when it declares none.
+   *
+   * `project-adapter.ts` is still the only thing that LOADS it; the editor's
+   * `resolveComposition` asks that owner once per composition — waiting on the
+   * load in flight rather than reading past it — and hands the answer to
+   * `resolveRootBinding`, so every root of one game carries the same
+   * declaration. `null` is therefore a fact about the PROJECT: it shipped no
+   * declaration file and runs on the declared native default. Which table
+   * stood in (project, registry, or native) is a separate question, answered
+   * by `ProjectAdapterFacet.source`.
+   */
+  readonly definition: AdapterDefinition | null;
+  /** The entry module's static surface, realm-honest about its reach. */
+  readonly entry: EntryStaticSurface;
+}
+
+/**
+ * One root's whole declaration, bound.
+ *
+ * The keys ARE {@link ProtocolFamily} — pinned below, so the vocabulary and
+ * the value can never drift apart.
+ */
+export interface RootBinding {
+  readonly substrate: SubstrateBinding;
+  /**
+   * Present only when this root's mount exposes an `AuthoringAdapter`.
+   *
+   * A `ProjectionBinding` cannot be fabricated — `capabilities`/`hierarchy`
+   * are required — so a mount with no authoring gets no projection. It gets
+   * the other four families, which are constructible from the declaration and
+   * the mount alone, because withholding those too would answer "what root is
+   * this, what did the project declare, what can be watched" with silence for
+   * a question the mount's authoring has nothing to do with.
+   *
+   * Absent is a REAL state, not a rare one: the editor supplies live authoring
+   * for native TSX roots itself (`play-mode.ts`'s per-root live adapters,
+   * composed into one `CompositeAuthoringAdapter`) rather than through the
+   * mount, so today every first-party three/canvas/dom root lands here. Moving
+   * that projection into the mount is its own program item; until it does, the
+   * absence is the honest report of where authoring lives.
+   */
+  readonly projection?: ProjectionBinding | undefined;
+  /** Present exactly when {@link projection} is — same authoring adapter, same
+   *  condition; see there. */
+  readonly truth?: TruthBinding | undefined;
+  readonly observation: ObservationBinding;
+  readonly project: ProjectBinding;
+}
+
+/**
+ * Compile-time pin: `keyof RootBinding` and `ProtocolFamily` are the same set
+ * of names, in both directions. Adding a family to one address and not the
+ * other is a type error HERE, at the vocabulary, rather than a silent
+ * asymmetry every consumer inherits.
+ */
+type MutuallyAssignable<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type AssertTrue<T extends true> = T;
+export type RootBindingKeysAreExactlyTheProtocolFamilies = AssertTrue<
+  MutuallyAssignable<keyof RootBinding, ProtocolFamily>
+>;
+
+/**
+ * Everything {@link createRootBinding} needs, and nothing it could go and get
+ * for itself.
+ *
+ * Each member is a value some OTHER owner already produced: the resolver
+ * mounted the adapter, the manifest loader resolved the root, `project-adapter`
+ * parsed the definition, the realm loaded the entry namespace, `createGame`
+ * owns the debug registry. This shape exists so that list is stated once, at
+ * the seam, instead of being re-derived per realm.
+ */
+export interface RootBindingParts extends RootDeclaration {
+  readonly adapter: SurfaceAdapter;
+  readonly mounted: MountedRoot;
+  readonly pausable: boolean;
+  /** The GAME-scoped registry, borrowed. Never created or disposed here. */
+  readonly debugRegistry: DebugRegistry | null;
+}
+
+/**
+ * The DECLARATION half — everything a resolver knows BEFORE anything mounts.
+ *
+ * This is the half that travels: `binding-resolver.ts` produces one per root
+ * while it is resolving adapters, hands it to the host on the root's mount
+ * spec, and the host completes the binding at REGISTRATION — the first moment
+ * `mounted` exists at all. Splitting it here is what keeps the resolver from
+ * having to be present at mount time, and the host from having to know how an
+ * entry module was loaded.
+ */
+export interface RootDeclaration {
+  /** The manifest's own resolved root record. `loop` rides on it. */
+  readonly root: ResolvedAdapterRoot;
+  /** The project's parsed `vgai.adapter.ts`, or `null` when it declares none —
+   *  see {@link ProjectBinding.definition} for the current wiring truth. */
+  readonly definition: AdapterDefinition | null;
+  /** The entry module's static surface, realm-honest about its reach. */
+  readonly entry: EntryStaticSurface;
+  /** The entry module's validated `debug` export, harvested at resolve. */
+  readonly entryDebug?: NativeDebugBinding | undefined;
+  /** The entry module's validated `systems` export, harvested at resolve. */
+  readonly entrySystems?: NativeSystemsBinding | undefined;
+}
+
+/**
+ * REGROUP the parts into the five families. No loading, no defaulting, no
+ * fabrication: every member of the result is one of `parts`' own values or one
+ * of `parts.mounted.authoring`'s own provider objects, read straight off it.
+ *
+ * The straddlers are read ONCE into locals and written to both bindings, which
+ * is what makes `binding.projection.selection === binding.truth.selection` true
+ * by construction rather than by care —
+ * `adapter-binding-protocol-families.test.ts` asserts it over a value this
+ * function built.
+ *
+ * The two callback members are the one exception to "the same reference", and
+ * deliberately: `subscribe`/`observeTransforms` are METHODS on their adapter
+ * (`live-three-authoring-adapter` reads `this.store` inside `subscribe`), so a
+ * bare property read would hand the caller a function whose `this` is the
+ * observation binding. They are bound to the authoring adapter that owns them —
+ * the same function over the same receiver, with nothing interposed. They are
+ * not straddlers and carry no equality claim.
+ *
+ * An absent `mounted.authoring` costs this root its `projection` and `truth`
+ * and NOTHING ELSE. There is no such thing as an empty `ProjectionBinding` —
+ * `capabilities`/`hierarchy` are required — so those two families are simply
+ * not there, which is the honest report. The other three are built from the
+ * declaration and the mount, neither of which the authoring adapter has
+ * anything to do with; refusing them as well would answer "which root is
+ * this, what did the project declare, what can be watched" with silence, and
+ * that is what made `binding` unreadable for every native TSX root the editor
+ * plays (the editor supplies their authoring itself — see
+ * {@link RootBinding.projection}).
+ */
+export function createRootBinding(parts: RootBindingParts): RootBinding {
+  const authoring = parts.mounted.authoring;
+
+  // Read each straddler ONCE — the two bindings below then hold these exact
+  // objects, not two reads of the same key.
+  const { selection, transforms, inspector, instances, spatialHandles, boxEdit, text } =
+    authoring ?? {};
+
+  return {
+    substrate: {
+      adapter: parts.adapter,
+      mounted: parts.mounted,
+      pausable: parts.pausable,
+      loop: parts.root.loop,
+    },
+    ...(authoring === undefined
+      ? {}
+      : projectionAndTruth(authoring, {
+          selection,
+          transforms,
+          inspector,
+          instances,
+          spatialHandles,
+          boxEdit,
+          text,
+        })),
+    observation: {
+      systems: parts.mounted.systems,
+      debugRegistry: parts.debugRegistry,
+      observe: parts.mounted.observe,
+      subscribe: authoring?.subscribe?.bind(authoring),
+      observeTransforms: authoring?.observeTransforms?.bind(authoring),
+      entryDebug: parts.entryDebug,
+      entrySystems: parts.entrySystems,
+    },
+    project: {
+      root: parts.root,
+      definition: parts.definition,
+      entry: parts.entry,
+    },
+  };
+}
+
+/** The two authoring-dependent families, built together from the ONE adapter
+ *  and the straddlers already read off it — so the reference-equality rule is
+ *  still decided in a single place. */
+function projectionAndTruth(
+  authoring: NonNullable<MountedRoot['authoring']>,
+  straddlers: Pick<
+    ProjectionBinding,
+    'selection' | 'transforms' | 'inspector' | 'instances' | 'spatialHandles' | 'boxEdit' | 'text'
+  >,
+): { projection: ProjectionBinding; truth: TruthBinding } {
+  const { selection, transforms, inspector, instances, spatialHandles, boxEdit, text } = straddlers;
+  return {
+    projection: {
+      capabilities: authoring.capabilities,
+      hierarchy: authoring.hierarchy,
+      provenance: authoring.provenance,
+      selection,
+      transforms,
+      inspector,
+      instances,
+      spatialHandles,
+      boxEdit,
+      text,
+      assetSubject: authoring.assetSubject,
+      related: authoring.related,
+      rects: authoring.rects,
+      pickable: authoring.pickable,
+      stories: authoring.stories,
+      colorSample: authoring.colorSample,
+    },
+    truth: {
+      structure: authoring.structure,
+      persistence: authoring.persistence,
+      truth: authoring.truth,
+      assetDrop: authoring.assetDrop,
+      selection,
+      transforms,
+      inspector,
+      instances,
+      spatialHandles,
+      boxEdit,
+      text,
+    },
+  };
+}

package/src/adapter/colyseus-networking-adapter.ts

@@ -109,12 +109,23 @@ export function createColyseusNetworkingAdapter(cfg: ColyseusNetworkingConfig):
       if (cfg.serverAuthoritative?.(o)) return false; // server owns it → inspect-only
       return cfg.ownerId(o) === cfg.localSessionId(); // only your own peer's objects
     },
-    getConnectionState: () => cfg.connectionState?.() ?? 'disconnected',
-    getRoomInfo: () => cfg.roomInfo?.() ?? null,
-    getReplicationStats: () =>
-      cfg.replicationStats?.() ?? { entities: 0, msgsInPerSec: 0, msgsOutPerSec: 0 },
+    // `subscribe` is the one member that still defaults, and honestly: an
+    // adapter with nothing to notify about has a real no-op subscription, and
+    // the caller's contract ("you will hear about changes") is kept — there are
+    // none. Every accessor below ANSWERS A QUESTION, and a default answer to a
+    // question nobody implemented is a fabricated measurement.
     subscribe: (cb) => cfg.subscribe?.(cb) ?? (() => {}),
   };
+  // The link-state accessors attach ONLY when supplied, exactly like the W3b
+  // capabilities below. They used to default — `'disconnected'`, `null`, and
+  // all-zero stats — which read as "we looked, and the game is idle and
+  // unconnected" for a config that had simply never been taught to look.
+  const connectionState = cfg.connectionState?.bind(cfg);
+  if (connectionState) adapter.getConnectionState = () => connectionState();
+  const roomInfo = cfg.roomInfo?.bind(cfg);
+  if (roomInfo) adapter.getRoomInfo = () => roomInfo();
+  const replicationStats = cfg.replicationStats?.bind(cfg);
+  if (replicationStats) adapter.getReplicationStats = () => replicationStats();
   // The W3b inspector capabilities attach ONLY when supplied: their absence
   // is the editor's degradation signal (`getStateSnapshot` in adapter ⇒ tree,
   // missing ⇒ "not provided by this adapter" — never a fabricated empty).
@@ -135,7 +146,11 @@ export function createColyseusNetworkingAdapter(cfg: ColyseusNetworkingConfig):
   // editor shows an editable field only when `setPlayerIdentity` is present.
   const playerIdentity = cfg.playerIdentity?.bind(cfg);
   if (playerIdentity) {
-    adapter.getPlayerIdentity = () => playerIdentity() ?? {};
+    // `cfg.playerIdentity` may answer `undefined` — "I read the game's state
+    // and it has no seat for this client yet". That is not `{}`, an identity
+    // that exists and happens to be blank; it is the reader's real answer, and
+    // the seam passes it through.
+    adapter.getPlayerIdentity = () => playerIdentity();
   }
   const setPlayerIdentity = cfg.setPlayerIdentity?.bind(cfg);
   if (setPlayerIdentity) {

package/src/adapter/entrypoint-selection-readers.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure TS-AST readers over an entrypoint's SELECTION TABLE — shared by the
+ * write side (`entrypoint-selection-source.ts`) and the read side
+ * (`finders/scenes-from-entrypoint-selection.ts`). These two must agree on
+ * what a selection table IS, or play remounts a key the finder never
+ * discovered; one spelling here is what makes that agreement structural.
+ * (The finder-import boundary bans importing from `finders/` — this sibling
+ * sits outside that directory precisely so both sides can share it.)
+ */
+
+import ts from 'typescript';
+
+/** The object literal a module-level `const <name> = { … }` binds. */
+export function selectionTable(
+  sf: ts.SourceFile,
+  name: string,
+): ts.ObjectLiteralExpression | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isObjectLiteralExpression(initializer)) return initializer;
+    }
+  }
+  return undefined;
+}
+
+/** A property's key when it is a plain identifier or string literal. */
+export function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined {
+  const name = property.name;
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+/**
+ * The identifier the entrypoint INDEXES the selection table with — the
+ * `activeScene` in `scenes[activeScene]`.
+ *
+ * `undefined` when the module never indexes the table; `null` when it does
+ * but not readably (several identifiers, or a non-identifier index). Both
+ * are honest "cannot be read" answers the callers turn into their own notes.
+ */
+export function indexingIdentifier(
+  sf: ts.SourceFile,
+  selection: string,
+): string | undefined | null {
+  const names = new Set<string>();
+  let unreadable = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === selection
+    ) {
+      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
+      else unreadable = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  if (names.size === 0 && !unreadable) return undefined;
+  if (names.size !== 1 || unreadable) return null;
+  return [...names][0];
+}