@forgeax/engine-scene 0.1.21 → 0.1.24

package/src/assets/scene-decoder.ts

@@ -110,7 +110,11 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
       // component registry.
       components[componentName] = { ...(rawFields as Record<string, unknown>) };
     }
-    entities.push({ localId: entity.localId, components });
+    entities.push({
+      localId: entity.localId,
+      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+      components,
+    });
   }
 
   const mounts = resolveMounts(payload.mounts, refs);
@@ -125,6 +129,7 @@ function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): Sce
     ok: true,
     value: {
       kind: 'scene',
+      ...(payload.sourceKey === undefined ? {} : { sourceKey: payload.sourceKey }),
       entities,
       ...(mounts.value === undefined ? {} : { mounts: mounts.value }),
       ...(skinGuids.value === undefined ? {} : { skinGuids: skinGuids.value }),

package/src/components/child-of.ts

@@ -7,6 +7,8 @@
 // u32 against the live record on read; `world.get(child, ChildOf)` returns
 // the raw encoded Entity and consumers check liveness themselves (via
 // `world.get(parent, Entity)` — returns `err(stale-entity)` for despawned handles).
+// Public source writes validate target liveness before committing; only
+// controlled internal fixtures can create a stale source for diagnostics.
 //
 // feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
 // ChildOf is declared as the holder side of a Bevy-style bidirectional
@@ -30,30 +32,30 @@
 //     the D-1 default from false to true). When linkedSpawn is set to true,
 //     world.despawn(parent) recursively despawns the entire subtree.
 //
-//     The prior default (linkedSpawn: false) meant despawning the parent only
-//     pruned the Children entry, leaving the child entity alive. That behavior
-//     is still available by passing linkedSpawn: false explicitly.
+//     `ChildOf` uses linkedSpawn: true, so despawning a parent recursively
+//     despawns its linked subtree. A generic relationship may opt out with
+//     linkedSpawn: false, but that is not this scene hierarchy's lifecycle.
 //
-// Child despawn auto-detaches from the parent's Children list: the
+// Child despawn auto-detaches from its parent's Children list: the
 // relationship `onRemove` hook fires on `world.despawn(child)` and prunes the
 // child from the parent's `Children.entities` (a write-path hook). Despawning
-// the PARENT does not auto-clean the child's ChildOf: the child's `parent`
-// column keeps the stale encoded Entity. The ECS does not bottom out dangling
-// references on read; the consumer is responsible for cleanup
-// (`world.removeComponent(child, ChildOf)` / `world.get(parent, Entity)` liveness check).
+// the parent follows ChildOf's linkedSpawn cascade and retires the linked
+// subtree. A stale ChildOf source is consequently only an explicitly malformed
+// internal fixture (or a generic non-linked relationship); the consumer repairs
+// it with `world.removeComponent(child, ChildOf)` after the structured error.
 //
-// propagateTransforms system (./systems/propagate-transforms.ts) consumes
-// this component by reading the archetype Uint32Array column directly
-// (query-backed hierarchy access). When a parent has been despawned
+// propagateTransforms system (./systems/propagate-transforms.ts) consumes the
+// ECS-maintained Children buffer for parent-first traversal and reads this
+// source column only to validate the mirrored edge. When a parent has been despawned
 // but the child's stale ChildOf is left in place, the live-map lookup surfaces
-// `RhiError({ code: 'hierarchy-broken' })` - a deliberate per-frame fail-fast
+// `SceneError({ code: 'hierarchy-broken' })` - a deliberate per-frame fail-fast
 // (the consumer is expected to despawn the subtree or remove the stale
 // ChildOf), kept as the explicit-failure surface (charter proposition 4).
 //
 // charter mapping: proposition 2 (industry analogy: Bevy ChildOf is the
 // post-0.15 rename of Parent for the same shape as glTF node parent index
 // + Three.js Object3D.parent) + proposition 4 (explicit failure: dangling
-// parent surfaces structured RhiError) + proposition 5
+// parent surfaces structured SceneError) + proposition 5
 // (consistent abstraction: the schema-vocab 'entity' keyword is the SSOT
 // for entity-typed columns across the engine).
 
@@ -63,25 +65,34 @@ export { ChildOf } from './children';
  * Hierarchy back-reference: pointer from child entity to its parent.
  *
  * Store the parent `Entity` handle (returned by `world.spawn(...).unwrap()`)
- * in the `parent` field; `propagateTransforms` reads it each frame to
- * compose the child's derived `Transform.world` mat4 (child.world =
- * parent.world x child local). Despawning a child auto-detaches it from the
- * parent's Children list (relationship `onRemove` hook). Despawning the
- * parent does not auto-clean the child's ChildOf; the consumer removes the
- * stale ChildOf (`world.removeComponent`) or checks `world.get(parent, Entity)` for liveness.
+ * in the `parent` field; `propagateTransforms` follows the ECS-maintained
+ * `Children` list each frame to compose the child's derived
+ * `GlobalTransform.world` mat4 (child.world = parent.world x child local).
+ * `Transform` declares `GlobalTransform` as a
+ * generic ECS requirement, so normal spawn/add/command paths materialize the
+ * pair without scene-specific repair. Propagation still fails closed when an
+ * owner explicitly removes one half. Despawning a child auto-detaches it from
+ * its parent's Children list; despawning the parent follows ChildOf's
+ * linkedSpawn cascade, while a malformed internal fixture can still leave a
+ * stale source for Scene diagnostics.
  *
- * Because ChildOf declares a `relationship` mirror, the engine keeps the
- * parent's `Children.entities` reverse list consistent automatically: adding
- * ChildOf appends the child to the parent's Children, removing it (or
- * reparenting via the `exclusive` arm) prunes the stale entry. AI users no
- * longer hand-maintain both sides (the prior OOS-10 contract is retired).
+ * Because ChildOf declares a `relationship` mirror and a structural
+ * `Transform` requirement, the engine keeps the parent's `Children.entities`
+ * reverse list consistent automatically and materializes the local/world pair
+ * when the child did not author one: adding ChildOf appends the child to the
+ * parent's Children, removing it (or reparenting via the `exclusive` arm)
+ * prunes the stale entry. AI users no longer hand-maintain both sides (the
+ * prior OOS-10 contract is retired).
  * Reparenting is a plain re-add: `world.addComponent(child, { component:
  * ChildOf, data: { parent: newParent } })` on an entity that already carries
- * ChildOf auto-reparents (exclusive arm), or use `world.reparent(child,
- * newParent)`.
+ * ChildOf auto-reparents (exclusive arm). The generic convenience method has
+ * the same owner path and requires the relationship component plus its data:
+ * `world.reparent(child, newParent, ChildOf, { parent: newParent })`.
  *
  * @example Spawn a child entity referencing an already-spawned root:
- *   const root = world.spawn({ component: Transform, data: {...} }).unwrap();
+ *   const root = world.spawn(
+ *     { component: Transform, data: {...} },
+ *   ).unwrap();
  *   const child = world.spawn(
  *     { component: Transform, data: {...} },
  *     { component: ChildOf, data: { parent: root } },

package/src/components/children.ts

@@ -1,28 +1,23 @@
 // @forgeax/engine-runtime - Children (forward-list of child entities).
 //
 // Schema: 1 array<entity> field `entities` (variable-length, ECS-managed via
-// the BufferPool slot column + sidecar count column allocated by the ECS M2
-// `world.push` / `world.pop` / `world.capacity` command surface).
+// the BufferPool slot column + sidecar count column allocated by the ECS
+// relationship owner).
 //
 // feat-20260515-buffer-array-vocab-collapse M3 / w17:
 // the legacy `VarArrayView<Entity>` value-shape wrapper was retired in
-// favour of a direct `TypedArray` snapshot returned by `world.get` plus the
-// three `world` commands. AI users mutate the list through:
-//
-//   world.push(parent, Children, 'entities', child).unwrap();
-//   world.pop(parent, Children, 'entities').unwrap();
-//   world.capacity(parent, Children, 'entities').unwrap();
-//
-// And read through the read-only `Uint32Array` snapshot:
+// favour of a direct `TypedArray` snapshot returned by `world.get`. AI users
+// read the engine-maintained list through the read-only `Uint32Array` snapshot:
 //
 //   const snap = world.get(parent, Children).unwrap().entities;
 //   const liveCount = snap.length;
 //   for (let i = 0; i < liveCount; i++) { const child = snap[i]; ... }
 //
 // Snapshot length equals the live element count (sidecar count column owned
-// by the ECS layer); the snapshot is rematerialised on every `world.get`
-// (D-4 no-cache); writes routed through the snapshot are undefined behaviour
-// (the contract is read-only, plan-strategy §2.2 D-R3).
+// by the ECS layer); the public snapshot is detached and rematerialised on
+// every `world.get` (D-4 no-cache), so `fill` or index writes cannot mutate the
+// target. Internal relationship maintenance and Scene traversal borrow the
+// live array through the package-internal zero-copy seams instead.
 //
 // feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
 // Children is the MIRROR side of the ChildOf relationship. Its schema is
@@ -33,9 +28,8 @@
 // "AI users keep the two sides consistent themselves" contract is retired:
 // `world.addComponent(child, ChildOf{parent})` appends `child` to
 // `parent.Children.entities`, `world.removeComponent` / reparent prunes it.
-// AI users still MAY push/pop the list manually (the three `world` commands
-// below remain valid for non-ChildOf forward-lists), but for the ChildOf
-// hierarchy the engine owns consistency.
+// For the ChildOf hierarchy the engine owns consistency; no public target
+// write can diverge from the source relationship.
 //
 // feat-20260514-ecs-children-instances-managed-buffer-array M3 / w13 (kept
 // for context): migrated from the legacy `{ count: 'u32' }` advisory marker
@@ -43,14 +37,12 @@
 //   - OOS-09 (prior loop): no `addChild` / `removeChild` / `removeChildren`
 //     Commands API. Retired this feat: `world.addChild` / `world.removeChild`
 //     / `world.reparent` ship in M3, plus the relationship hook above.
-//   - OOS-01 (prior loop): no dangling-entity sweep on `array<entity>`. If a
-//     child entity has been despawned, the stored u32 still occupies the
-//     slot; AI users explicitly call the engine's entity-liveness check
-//     before consuming a child id (see `world.get(child, ChildOf)` returns
-//     `Result.err(...)` for a despawned entity --- the stored u32 surfaces
-//     as a dead handle, not a silent zero). Charter proposition 4
-//     (explicit failure): the engine does not silently drop dangling
-//     entries.
+//   - Normal ChildOf child despawn invokes the source onRemove hook and
+//     removes the child before the row is retired; parent despawn follows the
+//     linkedSpawn cascade. A dangling u32 is therefore an explicitly malformed
+//     internal fixture or a non-linked generic relationship, not a normal
+//     ChildOf lifecycle result. Consumers still probe liveness before using a
+//     handle and receive the structured ECS error for malformed state.
 //
 // charter mapping: proposition 2 (Bevy ChildOf+Children pair, holder
 // perspective) + proposition 3 (machine-readable schema:
@@ -60,30 +52,32 @@
 // generic relationship-mirror shape, not a ChildOf special case).
 
 import { defineRelationship } from '@forgeax/engine-ecs';
+import { Transform } from './transform';
 
 /**
  * Hierarchy forward-list of child entities.
  *
  * `entities` is a variable-length `array<entity>` field; each element is
- * an `Entity` u32 the AI user pushed via
- * `world.push(parent, Children, 'entities', child)`. The value returned by
- * `world.get(parent, Children).unwrap().entities` is a read-only
+ * an `Entity` u32 the ECS relationship owner materialized. The value returned
+ * by `world.get(parent, Children).unwrap().entities` is a detached read-only
  * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
- * the snapshot's `length` equals the live element count.
+ * mutating the returned array cannot change ECS-owned storage, and the
+ * snapshot's `length` equals the live element count. Internal Scene/ECS paths
+ * use the package-internal zero-copy array seams instead of this snapshot.
  *
  * Invariants:
- *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
- *     upward, D-P2). The forward list is for AI-user traversal / debug /
- *     inspection.
+ *   - `propagateTransforms` consumes Children from the ECS-owned materialized
+ *     buffer and expands each root parent-first. The forward list is also
+ *     available for AI-user traversal / debug / inspection.
  *   - Children <-> ChildOf consistency is maintained by the engine via the
  *     ChildOf `relationship` mirror hook (see ./child-of.ts): adding /
  *     removing / reparenting ChildOf on a child auto-updates the parent's
  *     `entities` list. AI users do not hand-sync the two sides for the
  *     hierarchy.
- *   - Stored entity u32s are NOT auto-cleared when the referenced entity is
- *     despawned (OOS-01 above); a `world.get(despawnedChild, ...)` call
- *     returns `Result.err(...)` so AI users discover the dangling state
- *     through the engine's structured-error channel.
+ *   - ChildOf's linked lifecycle keeps ordinary Children entries aligned: a
+ *     child despawn prunes its source slot and a parent despawn cascades. A
+ *     deliberately malformed/non-linked edge remains observable as a dead
+ *     handle and must be diagnosed through the structured error channel.
  *
  * @example Spawn a parent and two children via ChildOf (engine maintains Children):
  *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
@@ -99,8 +93,8 @@ import { defineRelationship } from '@forgeax/engine-ecs';
  *   const snap = world.get(parent, Children).unwrap().entities;
  *   for (let i = 0; i < snap.length; i++) {
  *     const child = snap[i];
- *     // ... consume; world.get(child, ...) surfaces a structured error
- *     // if the child has been despawned (OOS-01 dangling-entity surface).
+ *     // ... consume; probe the handle before using it when reading a
+ *     // deliberately malformed/non-linked relationship.
  *   }
  */
 export const { source: ChildOf, target: Children } = defineRelationship({
@@ -108,6 +102,11 @@ export const { source: ChildOf, target: Children } = defineRelationship({
   sourceField: 'parent',
   targetName: 'Children',
   targetField: 'entities',
+  // Every scene hierarchy node is spatial.  Adding ChildOf therefore
+  // materializes the local/derived transform pair at the same structural
+  // boundary, so render- and scene-authored children cannot enter a frame
+  // with an incomplete hierarchy node.
+  sourceRequires: [Transform],
   exclusive: true,
   linkedSpawn: true,
 });

package/src/components/transform.ts

@@ -1,89 +1,31 @@
-// @forgeax/engine-runtime - Transform (local TRS + world mat4).
-//
-// Schema: three local array<f32, N> columns -- pos (3-vec position), quat
-// (4-quat rotation, component order [x, y, z, w]), scale (3-vec scale) --
-// plus one `world: array<f32, 16>` field carrying the resolved world-space
-// mat4 (column-major 16 floats, written by the propagate kernel each frame).
-// Inline stride-N array columns (feat-20260602) store each row's N floats
-// contiguously, so per-row xyz locality is native to the column layout; the
-// former per-axis scalar decomposition (10 f32 columns) predates
-// inline array columns and was retired in feat-20260709 M2.
-//
-// The world column is the SSOT for the resolved world transform: a root's
-// world equals its local mat4; a child's world equals parent.world x local.
-// AI users author the local TRS arrays and read the derived world mat4 via
-// the ECS column-level array view (`world.get(e, Transform).world` -> live
-// Float32Array of 16 column-major floats). They MUST NOT hand-write the
-// world column -- it is overwritten by propagate.
-//
-// charter mapping: P1 (progressive disclosure via defaults map -- AI users
-// spawn with data: {} and get identity local TRS + identity world mat4),
-// F1 (context-limited: single-import barrel; 3 array keys replace 10 scalar
-// keys at every spawn call-site), P4 (consistent abstraction: pos / quat /
-// scale array columns follow the same access pattern as `world` -- learn
-// the flat column form once, apply it to every array<f32, N> field),
-// P3 (machine-readable schema > prose).
+// @forgeax/engine-runtime - authored local transform and derived world output.
 
 import { defineComponent } from '@forgeax/engine-ecs';
 
-// Column-major identity mat4 (16 floats) used as the world-column default so
-// `spawn({ component: Transform, data: {} })` lands an identity world view
-// before the first propagate pass writes the resolved transform.
 const IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
+/** Scene-owned derived world transform. Only TransformPropagation writes it. */
+export const GlobalTransform = defineComponent(
+  'GlobalTransform',
+  {
+    world: { type: 'array<f32, 16>', default: IDENTITY_MAT4 },
+  },
+  { transient: true },
+);
+
 /**
- * Transform: local position `pos` (xyz), rotation `quat` (quaternion,
- * component order [x, y, z, w]), scale `scale` (xyz), plus the resolved
- * `world` mat4 (column-major 16 floats).
- *
- * Local TRS is stored as three inline stride-N array<f32, N> columns. The
- * propagate kernel composes each entity's local TRS into a mat4 and writes it
- * into the `world` column (root: world = local; child: world = parent.world x
- * local) using `@forgeax/engine-math` mat4 / vec3 / quat APIs (charter P4: do
- * not reinvent math). MVP recomposes every frame; dirty-flag optimization is
- * owned by feat-future-render-world.
- *
- * The `world` column is a fixed-capacity `array<f32, 16>` (feat-20260602):
- * the 16 contiguous floats live inline in a stride-16 column -- no BufferPool
- * slot. Read it via `world.get(e, Transform).world` which returns a live
- * `Float32Array` aliasing the column buffer. The view is transient: it aliases
- * the archetype column buffer and is valid only until the next structural
- * change (spawn / despawn / addComponent / removeComponent). Re-fetch the view
- * on every access; holding a view across a structural change is undefined
- * behaviour (the backing `ArrayBuffer` is detached on column growth, and
- * swap-remove at the same row index points to the wrong entity). All existing
- * hot paths (propagate / render-extract / pick) already comply -- see
- * `packages/ecs/README.md` Transient view contract section.
- *
- * All three local columns carry explicit layer-2 defaults (identity
- * transform): `pos: [0, 0, 0]`, `quat: [0, 0, 0, 1]` (identity quaternion,
- * [x, y, z, w]), `scale: [1, 1, 1]`. quat and scale MUST stay explicit: the
- * layer-3 fallback for array<f32, N> is all-zero, which would land an invalid
- * zero quaternion / zero scale. The `world` field defaults to the identity
- * mat4. AI users spawn with `data: {}` or with only the fields they need to
- * override.
- *
- * @example Minimal spawn (local defaulted to identity, world = identity mat4):
- *   world.spawn({ component: Transform, data: {} });
- *
- * @example Override only the position, leaving rotation/scale at identity:
- *   world.spawn({ component: Transform, data: { pos: [0, 6, 0] } });
+ * Authored local position, rotation and scale columns.
  *
- * @example Full explicit local form (defaults are opt-in):
- *   world.spawn({ component: Transform, data: {
- *     pos: [1, 2, 3],
- *     quat: [0, 0, 0, 1], // [x, y, z, w]
- *     scale: [1, 1, 1],
- *   } });
+ * The ECS `requires` declaration is the generic structural invariant: callers
+ * add `Transform`, while `GlobalTransform` is materialized once at spawn/add.
  */
-export const Transform = defineComponent('Transform', {
-  pos: { type: 'array<f32, 3>', default: new Float32Array([0, 0, 0]) },
-  // Component order [x, y, z, w] end to end (glTF-aligned; E6).
-  quat: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
-  scale: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
-  // `world` is field-level transient (D-5): scene collect skips it. The resolved
-  // world mat4 is derived by the propagate kernel from the persisted local TRS
-  // each frame, so serializing it would store reconstructable data (SSOT: local
-  // TRS). Round-trip re-derives an equivalent world on the first propagate pass.
-  world: { type: 'array<f32, 16>', default: IDENTITY_MAT4, transient: true },
-});
+export const Transform = defineComponent(
+  'Transform',
+  {
+    pos: { type: 'array<f32, 3>', default: new Float32Array([0, 0, 0]) },
+    // Component order [x, y, z, w] is shared with glTF.
+    quat: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+    scale: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  },
+  { requires: [GlobalTransform] },
+);

package/src/errors.ts

@@ -1,4 +1,4 @@
-import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { EcsError, EntityHandle } from '@forgeax/engine-ecs';
 
 export type SceneErrorCode = 'hierarchy-broken' | 'hierarchy-cycle';
 
@@ -7,11 +7,35 @@ export type SceneInstanceErrorCode = 'component-not-defined' | 'scene-override-t
 
 export { ComponentNotDefinedError } from '@forgeax/engine-ecs/projection';
 
-export interface SceneErrorDetail {
+/** The structured ECS failure retained by a Scene derived-write diagnostic. */
+export interface SceneErrorCause {
+  readonly code: EcsError['code'];
+  readonly expected?: string;
+  readonly hint?: string;
+  readonly detail?: unknown;
+}
+
+/** Location detail shared by hierarchy diagnostics and derived-write errors. */
+export interface SceneHierarchyErrorDetail {
+  readonly kind?: 'hierarchy';
   readonly entity: EntityHandle;
   readonly parent: EntityHandle;
 }
 
+/** A flat derived publication failure with its original ECS error intact. */
+export interface SceneDerivedWriteErrorDetail {
+  readonly kind: 'derived-write';
+  readonly entity: EntityHandle;
+  readonly parent: EntityHandle;
+  readonly bindingIndex: number;
+  readonly base: number;
+  readonly start: number;
+  readonly count: number;
+  readonly cause: SceneErrorCause;
+}
+
+export type SceneErrorDetail = SceneHierarchyErrorDetail | SceneDerivedWriteErrorDetail;
+
 export class SceneError extends Error {
   readonly code: SceneErrorCode;
   readonly expected: string;

package/src/index.ts

@@ -4,13 +4,21 @@ export { ChildOf } from './components/child-of';
 export { Children } from './components/children';
 export { MorphWeights } from './components/morph-weights';
 export { Name } from './components/name';
-export { Transform } from './components/transform';
+export { GlobalTransform, Transform } from './components/transform';
 export {
   ComponentNotDefinedError,
   SceneError,
   type SceneErrorCode,
   type SceneInstanceErrorCode,
 } from './errors';
+export {
+  resolveSceneEntity,
+  type SceneBindingDeclarationError,
+  type SceneBindingError,
+  type SceneEntityRef,
+  sceneEntity,
+  validateSceneBindings,
+} from './instances/binding';
 export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
 export {
   type ExternalizedSceneAsset,
@@ -44,6 +52,7 @@ export {
   worldRemoveSceneOverride,
   worldResolveMountSource,
   worldResolveSceneAsset,
+  worldResolveSceneEntity,
   worldResolveSceneInstanceStatePayload,
   worldSetSceneAssetResolver,
   worldSetSceneOverride,

package/src/instances/binding.ts

@@ -0,0 +1,77 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { SceneEntityRef } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export type { SceneEntityRef } from '@forgeax/engine-types';
+
+export type SceneBindingError = {
+  readonly code: 'scene-binding-missing' | 'scene-binding-wrong-instance';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly sceneSourceKey: string; readonly bindingKey: string };
+};
+
+export type SceneBindingDeclarationError = {
+  readonly code: 'scene-binding-duplicate' | 'scene-binding-source-missing';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly sceneSourceKey?: string; readonly bindingKey?: string };
+};
+
+export function validateSceneBindings(
+  sceneSourceKey: string,
+  bindingKeys: readonly string[],
+): Result<readonly string[], SceneBindingDeclarationError> {
+  if (sceneSourceKey.length === 0) {
+    return err({
+      code: 'scene-binding-source-missing',
+      expected: 'a non-empty scene sourceKey',
+      hint: 'declare the scene sourceKey in the author inventory',
+      detail: {},
+    });
+  }
+  const seen = new Set<string>();
+  for (const bindingKey of bindingKeys) {
+    if (bindingKey.length === 0 || seen.has(bindingKey)) {
+      return err({
+        code: 'scene-binding-duplicate',
+        expected: 'unique non-empty bindingKey values within one scene',
+        hint: 'rename the duplicate bindingKey in the scene producer',
+        detail: { sceneSourceKey, bindingKey },
+      });
+    }
+    seen.add(bindingKey);
+  }
+  return ok([...bindingKeys]);
+}
+
+export function sceneEntity(sceneSourceKey: string, bindingKey: string): SceneEntityRef {
+  return { sceneSourceKey, bindingKey };
+}
+
+export function resolveSceneEntity(
+  ref: SceneEntityRef,
+  instance: {
+    readonly sceneSourceKey: string;
+    readonly bindings: ReadonlyMap<string, EntityHandle | number>;
+  },
+): Result<EntityHandle | number, SceneBindingError> {
+  if (ref.sceneSourceKey !== instance.sceneSourceKey) {
+    return err({
+      code: 'scene-binding-wrong-instance',
+      expected: `scene instance ${ref.sceneSourceKey}`,
+      hint: 'resolve the SceneEntityRef against its owning SceneInstance',
+      detail: { sceneSourceKey: ref.sceneSourceKey, bindingKey: ref.bindingKey },
+    });
+  }
+  const value = instance.bindings.get(ref.bindingKey);
+  if (value === undefined) {
+    return err({
+      code: 'scene-binding-missing',
+      expected: 'bindingKey declared by the scene producer',
+      hint: 'declare the bindingKey in the scene producer before consuming it',
+      detail: { sceneSourceKey: ref.sceneSourceKey, bindingKey: ref.bindingKey },
+    });
+  }
+  return ok(value);
+}

package/src/instances/externalization.ts

@@ -91,7 +91,11 @@ export function externalizeSceneAsset(
         components[componentName] = fields;
       }
     }
-    return { localId: entity.localId as number, components };
+    return {
+      localId: entity.localId as number,
+      ...(entity.bindingKey === undefined ? {} : { bindingKey: entity.bindingKey }),
+      components,
+    };
   });
 
   const mounts = scene.mounts?.map((mount) => {
@@ -126,6 +130,8 @@ export function externalizeSceneAsset(
   }
   return ok({
     payload: {
+      kind: 'scene',
+      ...(scene.sourceKey === undefined ? {} : { sourceKey: scene.sourceKey }),
       entities,
       ...(mounts === undefined || mounts.length === 0 ? {} : { mounts }),
       ...(scene.skinGuids === undefined