@forgeax/engine-scene 0.0.0-dev.8d955ade1c79

package/src/components/child-of.ts

@@ -0,0 +1,90 @@
+// @forgeax/engine-runtime - ChildOf (hierarchy back-reference; Bevy-aligned).
+//
+// Schema (M5 / w18): `{ parent: 'entity' }`.
+// Migrated from `'ref'` (raw u32 column) to the schema-vocab `'entity'`
+// keyword. The on-disk column is a Uint32Array carrying the encoded Entity
+// (24-bit index + 8-bit generation). The ECS does not validate the stored
+// 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).
+//
+// feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
+// ChildOf is declared as the holder side of a Bevy-style bidirectional
+// relationship via the `relationship` metadata block (one-cut breaking
+// migration, AGENTS.md Change stance - no v1/v2 dual-path, component name +
+// schema shape + holder-perspective naming all unchanged). The engine
+// auto-maintains the reverse `Children.entities` list on the parent entity at
+// `world.addComponent` / `world.removeComponent` / `world.despawn` time
+// (M2 bidirectional-sync hook), retiring the old OOS-10 "AI user keeps the two
+// sides consistent themselves" contract.
+//   - mirror: 'Children'  -- the reverse-list component name (string, not a
+//     type reference, so engine-ecs never imports the runtime ChildOf/Children
+//     types; AC-29). Relationship roles are resolved by the scene owner.
+//   - field: 'entities'   -- the `array<entity>` field on Children holding the
+//     reverse list. Validated to be exactly `'array<entity>'` at defineComponent time.
+//   - exclusive: true     -- re-adding ChildOf with a new parent auto-reparents
+//     (prunes the old parent's Children entry, appends to the new) instead of
+//     returning ComponentAlreadyPresentError (single-parent hierarchy, AC-12).
+//   - linkedSpawn: true   -- despawning the parent cascade-despawns all
+//     child entities that hold this ChildOf (AC-08; the human gate flipped
+//     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.
+//
+// Child despawn auto-detaches from the 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).
+//
+// 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
+// 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
+// (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
+// (consistent abstraction: the schema-vocab 'entity' keyword is the SSOT
+// for entity-typed columns across the engine).
+
+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.
+ *
+ * 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).
+ * 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)`.
+ *
+ * @example Spawn a child entity referencing an already-spawned root:
+ *   const root = world.spawn({ component: Transform, data: {...} }).unwrap();
+ *   const child = world.spawn(
+ *     { component: Transform, data: {...} },
+ *     { component: ChildOf, data: { parent: root } },
+ *   ).unwrap();
+ *   // root now carries Children with [child] in its `entities` list.
+ */

package/src/components/children.ts

@@ -0,0 +1,113 @@
+// @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).
+//
+// 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:
+//
+//   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).
+//
+// feat-20260531-ecs-relationship-abstraction-bidirectional-sync M4 / t20:
+// Children is the MIRROR side of the ChildOf relationship. Its schema is
+// unchanged (the `entities: 'array<entity>'` shape is exactly what the
+// relationship mirror contract requires), but the engine now maintains this
+// list automatically whenever ChildOf is added / removed / reparented on a
+// child entity (M2 bidirectional-sync hook on ChildOf). The prior OOS-10
+// "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.
+//
+// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w13 (kept
+// for context): migrated from the legacy `{ count: 'u32' }` advisory marker
+// to the real variable-length entity-array storage path.
+//   - 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.
+//
+// charter mapping: proposition 2 (Bevy ChildOf+Children pair, holder
+// perspective) + proposition 3 (machine-readable schema:
+// `componentSchema(Children).entities === 'array<entity>'`) + proposition 4 (explicit
+// failure: dangling entries surface to the AI user via `world.get(parent, Entity)` liveness probe,
+// not silent drop) + proposition 5 (consistent abstraction: Children is the
+// generic relationship-mirror shape, not a ChildOf special case).
+
+import { defineRelationship } from '@forgeax/engine-ecs';
+
+/**
+ * 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
+ * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
+ * the snapshot's `length` equals the live element count.
+ *
+ * Invariants:
+ *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
+ *     upward, D-P2). The forward list is 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.
+ *
+ * @example Spawn a parent and two children via ChildOf (engine maintains Children):
+ *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
+ *   const a = world.spawn(
+ *     { component: Transform, data: identityXf() },
+ *     { component: ChildOf, data: { parent } },
+ *   ).unwrap();
+ *   const b = world.spawn(
+ *     { component: Transform, data: identityXf() },
+ *     { component: ChildOf, data: { parent } },
+ *   ).unwrap();
+ *   // Read back via the read-only snapshot - engine appended a, b:
+ *   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).
+ *   }
+ */
+export const { source: ChildOf, target: Children } = defineRelationship({
+  sourceName: 'ChildOf',
+  sourceField: 'parent',
+  targetName: 'Children',
+  targetField: 'entities',
+  exclusive: true,
+  linkedSpawn: true,
+});

package/src/components/morph-weights.ts

@@ -0,0 +1,6 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Per-entity morph weights; length is validated against the mesh target count. */
+export const MorphWeights = defineComponent('MorphWeights', {
+  weights: { type: 'array<f32>' },
+});

package/src/components/name.ts

@@ -0,0 +1,22 @@
+// @forgeax/engine-runtime --- Name component (built-in identifier).
+//
+// Single-field minimal skeleton: { value: 'string' }. Bare 'string' schema
+// vocab keyword routes through ECS UniqueRefStore (D-R3 single-arm managed
+// dispatch); the read shape is a native JS string.
+//
+// Lives in `runtime` rather than `ecs` because Name is a built-in *component*,
+// not part of the ECS framework itself (it does not participate in archetype /
+// query / world mechanics like the essential `Entity` component does). Mirrors
+// Bevy's split: `Entity` lives in `bevy_ecs`; `Name` lives in `bevy_core`.
+//
+// Migrated from packages/ecs/src/name.ts by tweak-20260612-ecs-concept-compression
+// (architecture-principles.md §1 SSOT: Name's authoritative location is the
+// runtime built-in components surface, not the ECS framework barrel).
+//
+// Naming follows the Bevy-aligned convention locked by feat-20260513:
+// single-semantic component drops the 'Component' suffix (Transform / Camera
+// / DirectionalLight / Name).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+export const Name = defineComponent('Name', { value: { type: 'string' } });

package/src/components/transform.ts

@@ -0,0 +1,89 @@
+// @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).
+
+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]);
+
+/**
+ * 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] } });
+ *
+ * @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],
+ *   } });
+ */
+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 },
+});

package/src/errors.ts

@@ -0,0 +1,34 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+
+export type SceneErrorCode = 'hierarchy-broken' | 'hierarchy-cycle';
+
+/** Scene-instantiation failures owned by the scene package. */
+export type SceneInstanceErrorCode = 'component-not-defined' | 'scene-override-type-mismatch';
+
+export { ComponentNotDefinedError } from '@forgeax/engine-ecs/projection';
+
+export interface SceneErrorDetail {
+  readonly entity: EntityHandle;
+  readonly parent: EntityHandle;
+}
+
+export class SceneError extends Error {
+  readonly code: SceneErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SceneErrorDetail | undefined;
+
+  constructor(args: {
+    code: SceneErrorCode;
+    expected: string;
+    hint: string;
+    detail?: SceneErrorDetail;
+  }) {
+    super(`[SceneError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'SceneError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+export { sceneAssetContribution } from './assets/scene-decoder';
+export { collectSubtree } from './collect-subtree';
+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 {
+  ComponentNotDefinedError,
+  SceneError,
+  type SceneErrorCode,
+  type SceneInstanceErrorCode,
+} from './errors';
+export { SCENE_COLLECT_PROFILE, type SceneCollectProfile } from './instances/collect-profile';
+export {
+  type ExternalizedSceneAsset,
+  externalizeSceneAsset,
+  type SceneComponentSchemaResolver,
+  type SceneExternalizationError,
+} from './instances/externalization';
+export {
+  type SceneAssetResolver,
+  type SceneInstanceStatePayload,
+  type SceneInstantiateDiagnostic,
+  type SceneInstantiateFlatOk,
+  type SceneInstantiateOk,
+  type SceneMembersSpawn,
+  worldApplyMountOverride,
+  worldBuildSceneEntityComponentDatas,
+  worldDespawnDescendants,
+  worldDespawnScene,
+  worldDetachSceneMember,
+  worldGetSceneAssetForInstance,
+  worldGetSceneAssetResolver,
+  worldGetSceneInstanceState,
+  worldInstantiateScene,
+  worldInstantiateSceneAsset,
+  worldInstantiateSceneAssetFlat,
+  worldInstantiateSceneFlat,
+  worldInstantiateScenePayload,
+  worldInstantiateSceneRec,
+  worldMountOverridesToStateMap,
+  worldReattachSceneMember,
+  worldRemoveSceneOverride,
+  worldResolveMountSource,
+  worldResolveSceneAsset,
+  worldResolveSceneInstanceStatePayload,
+  worldSetSceneAssetResolver,
+  worldSetSceneOverride,
+  worldSpawnMountEntity,
+  worldSpawnSceneMembers,
+  worldValidateMountOverrides,
+} from './instances/scene-instances';
+export { scenePlugin } from './plugin';
+export {
+  projectHierarchy,
+  type SceneHierarchyDiagnostic,
+  type SceneHierarchySnapshot,
+} from './systems/hierarchy-projection';
+export {
+  PROPAGATE_TRANSFORMS_SYSTEM,
+  propagateTransforms,
+  registerPropagateTransforms,
+  TransformSet,
+} from './systems/propagate-transforms';

package/src/instances/collect-profile.ts

@@ -0,0 +1,10 @@
+/** Immutable Scene collection policy shared by runtime collectors. */
+export interface SceneCollectProfile {
+  readonly includeComponent: (componentName: string, transient: boolean) => boolean;
+  readonly includeField: (componentName: string, fieldName: string, transient: boolean) => boolean;
+}
+
+export const SCENE_COLLECT_PROFILE: SceneCollectProfile = Object.freeze({
+  includeComponent: (_componentName: string, transient: boolean) => !transient,
+  includeField: (_componentName: string, _fieldName: string, transient: boolean) => !transient,
+});

package/src/instances/externalization.ts

@@ -0,0 +1,137 @@
+import type { AssetRef, MountOverride, SceneAsset } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export type SceneComponentSchemaResolver = (
+  componentName: string,
+) => Readonly<Record<string, string>> | undefined;
+
+export interface SceneExternalizationError {
+  readonly field: string;
+  readonly value: unknown;
+}
+
+export interface ExternalizedSceneAsset {
+  readonly payload: Record<string, unknown>;
+  readonly refs: readonly AssetRef[];
+}
+
+function sharedKind(type: string | undefined): 'one' | 'many' | undefined {
+  if (type?.startsWith('shared<')) return 'one';
+  if (type?.startsWith('array<shared<')) return 'many';
+  return undefined;
+}
+
+function overrideGuids(
+  override: MountOverride,
+  resolveSchema: SceneComponentSchemaResolver,
+): readonly { field: string; guid: string }[] {
+  const schema = resolveSchema(override.comp);
+  const values =
+    override.field !== undefined
+      ? [[override.field, override.value] as const]
+      : override.value !== null &&
+          typeof override.value === 'object' &&
+          !Array.isArray(override.value)
+        ? Object.entries(override.value as Record<string, unknown>)
+        : [];
+  return values.flatMap(([field, value]) => {
+    const kind = sharedKind(schema?.[field]);
+    if (kind === 'one' && typeof value === 'string') return [{ field, guid: value }];
+    if (kind === 'many' && Array.isArray(value)) {
+      return value.flatMap((item) => (typeof item === 'string' ? [{ field, guid: item }] : []));
+    }
+    return [];
+  });
+}
+
+/** Project a SceneAsset's shared asset fields into a payload plus indexed refs. */
+export function externalizeSceneAsset(
+  scene: SceneAsset,
+  resolveSchema: SceneComponentSchemaResolver,
+): Result<ExternalizedSceneAsset, SceneExternalizationError> {
+  const refs: AssetRef[] = [];
+  const indexByGuid = new Map<string, number>();
+  const addRef = (
+    guid: string,
+    sourceField: NonNullable<AssetRef['sourceField']>,
+    sceneEntityId?: number,
+  ): number => {
+    const prior = indexByGuid.get(guid);
+    if (prior !== undefined) return prior;
+    const index = refs.length;
+    refs.push({ guid, sourceField, ...(sceneEntityId === undefined ? {} : { sceneEntityId }) });
+    indexByGuid.set(guid, index);
+    return index;
+  };
+
+  const entities = scene.entities.map((entity) => {
+    const components: Record<string, Record<string, unknown>> = {};
+    for (const componentName of Object.keys(entity.components)) {
+      const schema = resolveSchema(componentName);
+      const source = entity.components[componentName] as Record<string, unknown> | undefined;
+      if (source === undefined) continue;
+      const fields: Record<string, unknown> = {};
+      for (const fieldName of Object.keys(source)) {
+        const value = source[fieldName];
+        if (value === undefined) continue;
+        const kind = sharedKind(schema?.[fieldName]);
+        if (kind === 'one' && typeof value === 'string') {
+          fields[fieldName] = addRef(value, { componentName, fieldName }, entity.localId as number);
+        } else if (kind === 'many' && Array.isArray(value)) {
+          fields[fieldName] = value.map((item, arrayIndex) =>
+            typeof item === 'string'
+              ? addRef(item, { componentName, fieldName, arrayIndex }, entity.localId as number)
+              : item,
+          );
+        } else {
+          fields[fieldName] = value;
+        }
+      }
+      if (Object.keys(fields).length > 0 || Object.keys(schema ?? {}).length === 0) {
+        components[componentName] = fields;
+      }
+    }
+    return { localId: entity.localId as number, components };
+  });
+
+  const mounts = scene.mounts?.map((mount) => {
+    const source =
+      typeof mount.source === 'string'
+        ? addRef(
+            mount.source,
+            { componentName: 'SceneInstance', fieldName: 'source' },
+            mount.localId as number,
+          )
+        : (mount.source as number);
+    for (const { field, guid } of (mount.overrides ?? []).flatMap((override) =>
+      overrideGuids(override, resolveSchema),
+    )) {
+      addRef(guid, { componentName: 'SceneInstance', fieldName: `overrides.${field}` });
+    }
+    return {
+      localId: mount.localId as number,
+      source,
+      memberFirst: mount.memberFirst as number,
+      memberCount: mount.memberCount,
+      ...(mount.parent === undefined ? {} : { parent: mount.parent as number }),
+      ...(mount.publicationFence === undefined ? {} : { publicationFence: mount.publicationFence }),
+      ...(mount.overrides === undefined
+        ? {}
+        : { overrides: mount.overrides.map((item) => ({ ...item })) }),
+    };
+  });
+  for (const [arrayIndex, guid] of (scene.skinGuids ?? []).entries()) {
+    if (typeof guid !== 'string') return err({ field: 'skinGuids', value: guid });
+    addRef(guid, { componentName: '<scene>', fieldName: 'skinGuids', arrayIndex });
+  }
+  return ok({
+    payload: {
+      entities,
+      ...(mounts === undefined || mounts.length === 0 ? {} : { mounts }),
+      ...(scene.skinGuids === undefined
+        ? {}
+        : { skinGuids: scene.skinGuids.map((guid) => indexByGuid.get(guid) as number) }),
+    },
+    refs,
+  });
+}