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

package/dist/instances/collect-profile.d.ts

@@ -0,0 +1,7 @@
+/** 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 declare const SCENE_COLLECT_PROFILE: SceneCollectProfile;
+//# sourceMappingURL=collect-profile.d.ts.map

package/dist/instances/collect-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-profile.d.ts","sourceRoot":"","sources":["../../src/instances/collect-profile.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC;IAClF,QAAQ,CAAC,YAAY,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC;CAClG;AAED,eAAO,MAAM,qBAAqB,EAAE,mBAGlC,CAAC"}

package/dist/instances/externalization.d.ts

@@ -0,0 +1,14 @@
+import type { AssetRef, SceneAsset } from '@forgeax/engine-types';
+import { 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[];
+}
+/** Project a SceneAsset's shared asset fields into a payload plus indexed refs. */
+export declare function externalizeSceneAsset(scene: SceneAsset, resolveSchema: SceneComponentSchemaResolver): Result<ExternalizedSceneAsset, SceneExternalizationError>;
+//# sourceMappingURL=externalization.d.ts.map

package/dist/instances/externalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalization.d.ts","sourceRoot":"","sources":["../../src/instances/externalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAiB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,4BAA4B,GAAG,CACzC,aAAa,EAAE,MAAM,KAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AA+BD,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,4BAA4B,GAC1C,MAAM,CAAC,sBAAsB,EAAE,yBAAyB,CAAC,CAsF3D"}

package/dist/instances/scene-instances.d.ts

@@ -0,0 +1,350 @@
+import { type Component, type ComponentData, type ComponentSchema, type EcsError, type EntityHandle, type ShapeOf, type World } from '@forgeax/engine-ecs';
+import type { Handle, LocalEntityId, MountOverride, SceneAsset, SceneInstanceMount } from '@forgeax/engine-types';
+import { type Result } from '@forgeax/engine-types';
+/**
+ * C-R2 (feat-20260622-s5 / studio-issues): one structured, non-fatal record of
+ * a SceneAsset payload field that did NOT match the target component's schema.
+ *
+ * Scene data is loader-fed and may carry a stale / deprecated / typo'd field
+ * (an editor renames a field, an old `.pack.json` lags). `worldInstantiateScene`
+ * does NOT blank the whole scene over one such field (#478 lesson: a
+ * prod-silent strip re-introduced an invisible-entity class) and does NOT abort
+ * fatally. Instead it skips the unknown key (no write, no input mutation) and
+ * surfaces this record on the success value's `diagnostics[]` — observable in
+ * production (NOT NODE_ENV-gated), consumed by property access (no string parse):
+ *
+ *   const r = worldInstantiateScene(world, handle);
+ *   if (r.ok) for (const d of r.value.diagnostics)
+ *     console.warn(`unknown field ${d.component}.${d.field} on localId ${d.localId}`);
+ *
+ * Direct `world.spawn` / `world.addComponent` / `Commands.spawn` stay fail-fast
+ * with `SpawnDataUnknownFieldError` — those are explicit API calls where a typo
+ * is a programming error, not loader-fed data.
+ */
+export type SceneInstantiateDiagnostic = {
+    /** Component name (schema key) the unknown field appeared under. */
+    readonly component: string;
+    /** The offending field name not declared in the component schema. */
+    readonly field: string;
+    /** LocalEntityId (within its owning SceneAsset) of the carrying entity. */
+    readonly localId: number;
+};
+/**
+ * Success value of `worldInstantiateScene`. `root` is the synthetic scene-root
+ * EntityHandle (carries `SceneInstance`); `diagnostics` is the (possibly empty)
+ * list of non-fatal unknown-field records aggregated across this scene and every
+ * recursively mounted sub-scene (C-R2). Empty array = no diagnostics.
+ */
+export type SceneInstantiateOk = {
+    readonly root: EntityHandle;
+    readonly diagnostics: readonly SceneInstantiateDiagnostic[];
+};
+/**
+ * Success value of `worldInstantiateSceneFlat` — the "edit the scene itself"
+ * primitive. Unlike `instantiateScene`, NO synthetic SceneInstance root is
+ * minted and NO `ChildOf` is forced onto top-level members: the scene's own
+ * entities become plain top-level world entities whose hierarchy is exactly
+ * their authored `ChildOf` (an entity with no `ChildOf` stays a root). `roots`
+ * is the set of those top-level handles (own rootless entities + top-level
+ * mount carriers). Nested prefabs inside the scene STILL materialise as their
+ * own SceneInstance anchors (charter P4: instance == entity-with-SceneInstance)
+ * — only THIS scene is flat.
+ */
+export type SceneInstantiateFlatOk = {
+    readonly roots: EntityHandle[];
+    /**
+     * All mount carrier entities spawned while flattening this scene. These are
+     * separate from `roots`: carriers with an authored parent are not roots,
+     * but still delimit a nested prefab subtree for post-spawn hooks.
+     */
+    readonly mountEntities: EntityHandle[];
+    readonly diagnostics: readonly SceneInstantiateDiagnostic[];
+};
+/**
+ * @internal Intermediate produced by `_spawnSceneMembers` and consumed by both
+ * the anchor finisher (`_instantiateSceneAsset`) and the flat finisher
+ * (`_instantiateSceneAssetFlat`). Holds everything the shared member-spawn
+ * (mounts recursion + own-entity spawn + deferred owned-parent wiring) computes,
+ * before either finisher decides whether to wrap the members in a synthetic
+ * SceneInstance root.
+ */
+export interface SceneMembersSpawn {
+    /** LocalEntityId → live Entity u32 (ENTITY_NULL_RAW for unspawned slots). */
+    readonly mapping: Uint32Array;
+    /** Reverse map live Entity → LocalEntityId for override / detach bookkeeping. */
+    readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+    /** Own entities that carried no `ChildOf` — the scene's authored top-level roots. */
+    readonly rootEntities: EntityHandle[];
+    /** Mount carriers whose `mount.parent === undefined` (default-parented). */
+    readonly mountEntitiesNeedingRootParent: EntityHandle[];
+    /** Every mount carrier spawned by this scene, including explicitly parented carriers. */
+    readonly mountEntities: EntityHandle[];
+    /**
+     * The child anchor and mapping for each mount. Flat scene opening has no
+     * outer SceneInstance state to own parent-namespace mount overrides, so it
+     * records those overrides on this child anchor after the shared spawn pass.
+     */
+    readonly mountInstances: readonly {
+        readonly mount: SceneInstanceMount;
+        readonly root: EntityHandle;
+        readonly mapping: Uint32Array;
+    }[];
+    /** `entities.length + mounts + Σ memberCount`, captured at instantiate-time. */
+    readonly totalSlots: number;
+}
+export type SceneAssetResolver = (source: number | string, parentHandle: Handle<'SceneAsset', 'shared'>) => Result<Handle<'SceneAsset', 'shared'>, unknown>;
+/** @internal */
+export declare function worldSetSceneAssetResolver(world: World, resolver: SceneAssetResolver): void;
+/** @internal */
+export declare function worldGetSceneAssetResolver(world: World): SceneAssetResolver | null;
+/**
+ * Materialise a SceneAsset (and any nested SceneAsset references via
+ * `mounts[]`) into live entities. Returns the synthetic root Entity that
+ * carries the `SceneInstance` ECS component (charter P4: instance ==
+ * entity-with-SceneInstance).
+ *
+ * Recursion path is closed inside `_instantiateSceneRec(handle, parent,
+ * stack)` (D-3); cycle detection is fail-fast `pack-cyclic-reference +
+ * detail.kind:'mount-asset'` (D-1 mirror, plan-strategy §D-3). The
+ * caller-supplied `parent` flows to the synthetic root's `ChildOf` so the
+ * full sub-tree attaches under the AI user's host entity.
+ *
+ * @example
+ *   const r = worldInstantiateScene(world, handle);
+ *   if (!r.ok) return r;
+ *   const { root, diagnostics } = r.value;
+ *   for (const d of diagnostics) // C-R2: unknown-field records, non-fatal
+ *     console.warn(`unknown field ${d.component}.${d.field} on localId ${d.localId}`);
+ *   const inst = world.get(root, SceneInstance).value;
+ *   const member = inst.mapping[0]; // first member entity
+ */
+export declare function worldInstantiateScene(world: World, handle: Handle<'SceneAsset', 'shared'>, parent?: EntityHandle): Result<SceneInstantiateOk, EcsError>;
+/**
+ * Materialise a projected `SceneAsset` payload without exposing the temporary
+ * shared-ref handle to the caller. The World remains the owner of both the
+ * handle and the instantiated SceneInstance: the producer grant is released
+ * after the SceneInstance retains its source, including when instantiation
+ * fails. This is the payload-shaped counterpart to `worldInstantiateScene` for
+ * hosts that load a SceneAsset directly from the Engine AssetRegistry.
+ */
+export declare function worldInstantiateScenePayload(world: World, asset: SceneAsset, parent?: EntityHandle): Result<SceneInstantiateOk, EcsError>;
+/**
+ * Materialise a SceneAsset FLAT — the "edit the scene itself" primitive.
+ * Unlike `instantiateScene`, this mints NO synthetic SceneInstance root and
+ * forces NO `ChildOf` onto top-level members: the scene's own entities become
+ * plain top-level world entities whose hierarchy is exactly their authored
+ * `ChildOf` (an entity with no `ChildOf` is a root). Use this to OPEN a scene
+ * for editing; use `instantiateScene` (anchor) at runtime / for nested
+ * prefabs where an instance boundary + override isolation is wanted.
+ *
+ * Nested prefabs referenced via `mounts[]` STILL materialise as their own
+ * SceneInstance anchors (charter P4 preserved) — only THIS top scene is flat.
+ *
+ * @example
+ *   const r = worldInstantiateSceneFlat(world, handle);
+ *   if (!r.ok) return r;
+ *   const { roots, diagnostics } = r.value; // roots = top-level handles
+ */
+export declare function worldInstantiateSceneFlat(world: World, handle: Handle<'SceneAsset', 'shared'>): Result<SceneInstantiateFlatOk, EcsError>;
+/**
+ * @internal Recursive helper carrying the cycle-detection stack. Sugar /
+ * other public callers must not see this mechanic — use `instantiateScene`
+ * (D-3 / charter P1).
+ */
+export declare function worldInstantiateSceneRec(world: World, handle: Handle<'SceneAsset', 'shared'>, parent: EntityHandle | undefined, stack: Set<number>, diagnostics: SceneInstantiateDiagnostic[]): Result<EntityHandle, EcsError>;
+/**
+ * @internal Resolve a SceneAsset handle through the SharedRefStore.
+ * The handle u32 is the SharedRefStore slot id (`world.allocSharedRef
+ * ('SceneAsset', asset)` is the producer; rc starts at 1, the SceneInstance
+ * spawn retains to rc=2 in M4 / w13). Errors propagate as EcsError so the
+ * instantiateScene chain returns a single closed union.
+ */
+export declare function worldResolveSceneAsset(world: World, handle: Handle<'SceneAsset', 'shared'>): Result<SceneAsset, EcsError>;
+/**
+ * @internal Spawn one SceneAsset's members — the shared body of both scene
+ * finishers. Recurses into `mounts[]` (each nested prefab becomes its own
+ * SceneInstance anchor), spawns `entities[]` honouring their authored
+ * `ChildOf`, and wires deferred owned-parent mount edges. Does NOT create a
+ * synthetic root or force any `ChildOf` — that is the caller's (finisher's)
+ * job. `_instantiateSceneRec` owns cycle bookkeeping.
+ */
+export declare function worldSpawnSceneMembers(world: World, handle: Handle<'SceneAsset', 'shared'>, asset: SceneAsset, stack: Set<number>, diagnostics: SceneInstantiateDiagnostic[]): Result<SceneMembersSpawn, EcsError>;
+/**
+ * @internal Spawn one SceneAsset's entities + apply mounts recursively, then
+ * wrap them in a synthetic SceneInstance root (the anchor). This is the
+ * runtime / Play / nested-mount finisher (charter P4: instance ==
+ * entity-with-SceneInstance). Caller (`_instantiateSceneRec`) owns cycle
+ * bookkeeping.
+ */
+export declare function worldInstantiateSceneAsset(world: World, handle: Handle<'SceneAsset', 'shared'>, asset: SceneAsset, parent: EntityHandle | undefined, stack: Set<number>, diagnostics: SceneInstantiateDiagnostic[]): Result<EntityHandle, EcsError>;
+/**
+ * @internal Flat finisher — spawn one SceneAsset's members WITHOUT wrapping
+ * them in a synthetic SceneInstance root and WITHOUT forcing `ChildOf` onto
+ * top-level members. Used for "opening a scene to edit": the scene's own
+ * entities become plain top-level world entities whose hierarchy is exactly
+ * their authored `ChildOf`. Nested prefabs inside still materialise as their
+ * own SceneInstance anchors (the mount recursion in `_spawnSceneMembers` is
+ * always anchored). Returns the top-level handles (own rootless entities +
+ * top-level mount carriers).
+ */
+export declare function worldInstantiateSceneAssetFlat(world: World, handle: Handle<'SceneAsset', 'shared'>, asset: SceneAsset, stack: Set<number>, diagnostics: SceneInstantiateDiagnostic[]): Result<{
+    roots: EntityHandle[];
+    mountEntities: EntityHandle[];
+}, EcsError>;
+/** @internal Build ComponentData[] for one SceneEntity, remapping localIds.
+ *
+ * C-R2 (feat-20260622-s5 M6): unknown fields on a SceneAsset payload are NOT
+ * fatal. Unlike `world.spawn` (an explicit API call where a typo is a
+ * programming error -> `SpawnDataUnknownFieldError`), scene data is loader-fed
+ * and may carry a stale / deprecated / typo'd field. The remap below builds a
+ * fresh `remappedRaw` and simply SKIPS keys absent from the schema (no input
+ * mutation — the source `raw` is never deleted-from), recording each skipped
+ * key as a non-fatal `SceneInstantiateDiagnostic` into the passed accumulator.
+ * All known fields still write through, so one bad field cannot blank the
+ * entity or the scene (C-AC-02/03/04).
+ */
+export declare function worldBuildSceneEntityComponentDatas(world: World, node: import('@forgeax/engine-types').SceneEntity, mapping: Uint32Array, diagnostics: SceneInstantiateDiagnostic[]): Result<ComponentData[], EcsError>;
+/**
+ * @internal feat-20260713 M2 / w8: apply one MountOverride to a live member
+ * entity column. The `field?` shape is the add-or-patch discriminant:
+ *
+ *   - `field` present -> PATCH one field: `world.set(member, comp, {[field]:
+ *     value})`. Omitted fields keep their authored / existing values.
+ *   - `field` absent  -> ADD/UPSERT the whole component: `value` is the
+ *     per-field value map for `comp`. When the member already carries `comp`
+ *     it is upserted (set-over each supplied field + schema defaults for the
+ *     omitted ones — the whole component is rewritten from the value map +
+ *     defaults, never a `component-already-present` error). When absent it is
+ *     added fresh via `addComponent` (fillComponentDefaults fills omitted
+ *     fields). The value-map is fed through `fillComponentDefaults` so the
+ *     add and upsert paths write byte-identical rows.
+ *
+ * Component registration + value-key validation happened at
+ * `_validateMountOverrides` (fail-fast before any spawn); by this point the
+ * comp resolves through the World-local catalog and the value keys are schema-valid.
+ * still guards defensively (an unregistered comp is a no-op skip, matching
+ * the prior field-patch behaviour). Returns the underlying set / addComponent
+ * Result so a shared-field value gate (D-4) or any other write error
+ * propagates unchanged.
+ */
+export declare function worldApplyMountOverride(world: World, member: EntityHandle, ov: MountOverride): Result<void, EcsError>;
+/**
+ * @internal R2/B-3 + R2/B-4: validate `mount.overrides[]` BEFORE any
+ * spawn so a malformed override fails fast with no observable side
+ * effects (charter P3 explicit-failure). Two checks:
+ *
+ * 1. `override.localId` must address a slot inside the parent-namespace
+ *    member window `[memberFirst, memberFirst + memberCount)` (AC-06).
+ * 2. `override.field` must exist in the resolved component schema
+ *    (AC-07). When the component is unregistered we cannot validate the
+ *    field shape; let the existing fall-through path proceed (the
+ *    catalog guard inside the override-application loop
+ *    will skip the write).
+ */
+export declare function worldValidateMountOverrides(world: World, mount: SceneInstanceMount): Result<void, EcsError>;
+/** @internal Spawn the mount-entity slot carrying mount.components (if any).
+ *
+ * R2/B-1: the mount entity is a structural intermediate in the ChildOf
+ * chain `cube -> innerSyntheticRoot -> mountEntity -> outerSyntheticRoot`,
+ * so it MUST carry Transform whenever Transform is registered (mirrors
+ * the D-V-0 synthetic-root invariant). Otherwise propagateTransforms
+ * walking the chain hits a Transform-less parent and emits per-frame
+ * `RhiError(hierarchy-broken)` (verify R1 root cause of the
+ * hello-scene-nesting demo black frames).
+ */
+export declare function worldSpawnMountEntity(world: World, mount: SceneInstanceMount, mapping: Uint32Array, diagnostics: SceneInstantiateDiagnostic[]): Result<EntityHandle, EcsError>;
+/** @internal Resolve mount.source through the wired SceneAssetResolver. */
+export declare function worldResolveMountSource(world: World, source: number | string, parentHandle: Handle<'SceneAsset', 'shared'>): Result<Handle<'SceneAsset', 'shared'>, EcsError>;
+/** @internal Convert mount.overrides Map shape to the SceneInstanceState shape.
+ *
+ * feat-20260713 M1 / w4: `field` is optional (add-or-patch discriminant). In
+ * M1 only the field-patch form reaches this builder (the component-add form
+ * fails fast in the apply loops); the record type stays `field?: string` so
+ * the M2 add path can flow through untouched. `exactOptionalPropertyTypes`
+ * forbids writing an explicit `field: undefined`, so omit the key when absent.
+ */
+export declare function worldMountOverridesToStateMap(src: Map<LocalEntityId, Map<string, MountOverride>>): Map<LocalEntityId, Map<string, {
+    comp: string;
+    field?: string;
+    value: unknown;
+}>>;
+/** @internal Set the payload of an already-allocated SceneInstance state ref. */
+export declare function worldSetUniqueRefPayload<T>(world: World, handle: Handle<string, 'unique'>, payload: T): void;
+/**
+ * @internal Resolve the SceneInstanceState payload behind the
+ * `SceneInstance.state` ref column on `root`. Returns Err when `root`
+ * does not carry SceneInstance or the ref slot is dead.
+ */
+export declare function worldResolveSceneInstanceStatePayload(world: World, root: EntityHandle): Result<SceneInstanceStatePayload, EcsError>;
+/**
+ * Public sugar — get the SceneInstanceState payload (Map / Set view) for
+ * `root`. Equivalent to `world.get(root, SceneInstance)` followed by a
+ * managed-ref resolution; provided so AI users do not have to learn the
+ * `ref<T>` slot resolution mechanic for the common read path.
+ */
+export declare function worldGetSceneInstanceState(world: World, root: EntityHandle): Result<SceneInstanceStatePayload, EcsError>;
+/**
+ * Despawn a SceneInstance root + all its members. `opts.keepDetached`
+ * preserves members marked via `worldDetachSceneMember` (plan-strategy
+ * §D-5). Returns the count of entities actually despawned (root + each
+ * non-detached member).
+ *
+ * For a plain entity (no SceneInstance), behaviour matches
+ * `world.despawn(entity)` followed by `despawnDescendants(entity)` — i.e.
+ * `keepDetached` is a no-op.
+ */
+export declare function worldDespawnScene(world: World, root: EntityHandle, opts?: {
+    keepDetached?: boolean;
+}): Result<number, EcsError>;
+/**
+ * Despawn every descendant of `root` reachable through Children mirror /
+ * SceneInstance.mapping. `opts.keepDetached` is honoured only when `root`
+ * carries a SceneInstance (otherwise the option is ignored — there is no
+ * detached set on a plain entity).
+ *
+ * Returns the count of entities despawned. The `root` itself is NOT
+ * despawned (that is `despawnScene`'s extra step).
+ */
+export declare function worldDespawnDescendants(world: World, root: EntityHandle, opts?: {
+    keepDetached?: boolean;
+}): Result<number, EcsError>;
+/**
+ * Write a runtime override to a member entity belonging to `root`. Routes
+ * through `world.set(member, comp, { [field]: value })` after an entity-
+ * scope guard so cross-instance writes fail-fast. Type-mismatch surfaces
+ * `EcsErrorCode = 'scene-override-type-mismatch'` (D-9).
+ */
+export declare function worldSetSceneOverride<S extends ComponentSchema>(world: World, root: EntityHandle, member: EntityHandle, component: Component<string, S>, field: keyof ShapeOf<S> & string, value: unknown): Result<void, EcsError>;
+/**
+ * Drop a runtime override (and any mount-time override for the same
+ * (member, comp, field) triple); roll the live column value back to the
+ * source SceneAsset's layer-1 explicit value (M2 v1 — M3+ widens to layer
+ * 2/3 defaults via fillComponentDefaults).
+ */
+export declare function worldRemoveSceneOverride<S extends ComponentSchema>(world: World, root: EntityHandle, member: EntityHandle, component: Component<string, S>, field: keyof ShapeOf<S> & string): Result<void, EcsError>;
+/** Mark a member entity detached. Idempotent (set semantics). */
+export declare function worldDetachSceneMember(world: World, root: EntityHandle, member: EntityHandle): Result<void, EcsError>;
+/** Clear a detached mark. Idempotent (set semantics). */
+export declare function worldReattachSceneMember(world: World, root: EntityHandle, member: EntityHandle): Result<void, EcsError>;
+/**
+ * Get the SceneAsset handle a SceneInstance root was instantiated from.
+ * Returns Err on a plain entity (no SceneInstance component).
+ */
+export declare function worldGetSceneAssetForInstance(world: World, root: EntityHandle): Result<Handle<'SceneAsset', 'shared'>, EcsError>;
+/** @internal Structural payload behind `SceneInstance.state` ref column. */
+export interface SceneInstanceStatePayload {
+    readonly source: Handle<'SceneAsset', 'shared'>;
+    readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+    readonly detachedLocalIds: Set<LocalEntityId>;
+    readonly overrides: Map<LocalEntityId, Map<string, {
+        readonly comp: string;
+        readonly field?: string;
+        readonly value: unknown;
+    }>>;
+    readonly rootEntities: EntityHandle[];
+    /** Synthetic roots of recursively mounted SceneAssets owned by this instance. */
+    readonly mountRoots: EntityHandle[];
+    readonly totalSlots: number;
+    readonly mountTimeOverrides: readonly MountOverride[];
+}
+//# sourceMappingURL=scene-instances.d.ts.map

package/dist/instances/scene-instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-instances.d.ts","sourceRoot":"","sources":["../../src/instances/scene-instances.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+export declare function scenePlugin(): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAiBrD,wBAAgB,WAAW,IAAI,MAAM,CASpC"}

package/dist/systems/hierarchy-projection.d.ts

@@ -0,0 +1,16 @@
+import { type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { SceneErrorCode, SceneErrorDetail } from '../errors';
+export interface SceneHierarchyDiagnostic {
+    readonly code: SceneErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SceneErrorDetail;
+}
+export interface SceneHierarchySnapshot {
+    readonly parentOf: ReadonlyMap<EntityHandle, EntityHandle>;
+    readonly diagnostics: readonly SceneHierarchyDiagnostic[];
+    getParent(entity: EntityHandle): EntityHandle | undefined;
+}
+/** Build the only World-local projection of ChildOf parent facts. */
+export declare function projectHierarchy(world: World): SceneHierarchySnapshot;
+//# sourceMappingURL=hierarchy-projection.d.ts.map

package/dist/systems/hierarchy-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-projection.d.ts","sourceRoot":"","sources":["../../src/systems/hierarchy-projection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG5E,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,WAAW,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC1D,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;CAC3D;AAqCD,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,sBAAsB,CA+ErE"}

package/dist/systems/index.d.ts

@@ -0,0 +1,3 @@
+export { projectHierarchy, type SceneHierarchyDiagnostic, type SceneHierarchySnapshot, } from './hierarchy-projection';
+export { PROPAGATE_TRANSFORMS_SYSTEM, propagateTransforms, registerPropagateTransforms, TransformSet, } from './propagate-transforms';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/systems/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,2BAA2B,EAC3B,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/dist/systems/propagate-transforms.d.ts

@@ -0,0 +1,15 @@
+import { type SystemHandle, type World } from '@forgeax/engine-ecs';
+import { type Result } from '@forgeax/engine-types';
+import { SceneError } from '../errors';
+import { type SceneHierarchySnapshot } from './hierarchy-projection';
+export declare const PROPAGATE_TRANSFORMS_SYSTEM: "propagateTransforms";
+export declare const PROPAGATE_TRANSFORMS_FIXED_SYSTEM: "propagateTransformsFixed";
+export declare const TransformSet: import("@forgeax/engine-ecs").SystemSet;
+export declare const TransformFixedSet: import("@forgeax/engine-ecs").SystemSet;
+export declare function propagateTransforms(world: World, _hierarchy?: SceneHierarchySnapshot): Result<void, SceneError>;
+export declare const PropagateTransforms: SystemHandle<readonly []>;
+export declare const PropagateTransformsFixed: SystemHandle<readonly []>;
+export declare function registerPropagateTransforms(world: World, options?: {
+    beforeSystemName?: string;
+}): () => void;
+//# sourceMappingURL=propagate-transforms.d.ts.map

package/dist/systems/propagate-transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagate-transforms.d.ts","sourceRoot":"","sources":["../../src/systems/propagate-transforms.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,KAAK,EACX,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAoB,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEvF,eAAO,MAAM,2BAA2B,EAAG,qBAA8B,CAAC;AAC1E,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AACrF,eAAO,MAAM,YAAY,yCAAyC,CAAC;AACnE,eAAO,MAAM,iBAAiB,yCAA+C,CAAC;AAgM9E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,UAAU,CAAC,EAAE,sBAAsB,GAClC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CA2F1B;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,SAAS,EAAE,CAOxD,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,YAAY,CAAC,SAAS,EAAE,CAI7D,CAAC;AAEH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,IAAI,CA6CZ"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@forgeax/engine-scene",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Scene identity, hierarchy, and world transform propagation.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "headless scene package"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "scene propagation covered by unit tests"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/asset-owner.integration.test.ts

@@ -0,0 +1,57 @@
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import type { SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Children, worldDespawnScene, worldInstantiateScenePayload } from '../index';
+
+const SceneInstance = defineComponent('SceneInstance', {
+  source: { type: 'shared<SceneAsset>' },
+  mapping: { type: 'array<entity>' },
+  state: { type: 'unique<SceneInstanceState>' },
+});
+const SceneMarker = defineComponent('ScenePayloadMarker', { value: 'i32' });
+
+function registerSceneWorld(world: World): void {
+  for (const component of [SceneInstance, ChildOf, Children, SceneMarker]) {
+    world.components.register(component).unwrap();
+  }
+}
+
+function scene(): SceneAsset {
+  return {
+    kind: 'scene',
+    entities: [
+      {
+        localId: 0 as never,
+        components: { ScenePayloadMarker: { value: 7 } },
+      },
+    ],
+  };
+}
+
+describe('scene payload ownership', () => {
+  it('retains the payload for the mounted instance and releases it on despawn', () => {
+    const world = new World();
+    registerSceneWorld(world);
+
+    const result = worldInstantiateScenePayload(world, scene());
+
+    expect(result.ok).toBe(true);
+    expect(world.sharedRefs._liveCount()).toBe(1);
+    if (!result.ok) return;
+    expect(worldDespawnScene(world, result.value.root).ok).toBe(true);
+    expect(world.sharedRefs._liveCount()).toBe(0);
+  });
+
+  it('releases the temporary producer grant when materialisation fails', () => {
+    const world = new World();
+    registerSceneWorld(world);
+
+    const result = worldInstantiateScenePayload(world, {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { MissingComponent: { value: 1 } } }],
+    } as SceneAsset);
+
+    expect(result.ok).toBe(false);
+    expect(world.sharedRefs._liveCount()).toBe(0);
+  });
+});

package/src/__tests__/components.unit.test.ts

@@ -0,0 +1,26 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Children, Name, Transform } from '../index';
+
+describe('scene component roster', () => {
+  it('exports exactly the four scene components', () => {
+    expect(Object.keys({ Name, Transform, ChildOf, Children }).sort()).toEqual([
+      'ChildOf',
+      'Children',
+      'Name',
+      'Transform',
+    ]);
+  });
+
+  it('registers and spawns in a headless world', () => {
+    const world = new World();
+    const entity = world
+      .spawn(
+        { component: Name, data: { value: 'root' } },
+        { component: Transform, data: {} },
+        { component: Children, data: {} },
+      )
+      .unwrap();
+    expect(world.get(entity, Name).unwrap().value).toBe('root');
+  });
+});

package/src/__tests__/diagnostic-type-surface.test-d.ts

@@ -0,0 +1,11 @@
+import type * as SceneSurface from '../index';
+
+type DiagnosticSurface = Pick<SceneSurface.SceneHierarchyDiagnostic, 'code' | 'detail'>;
+const diagnosticSurface: DiagnosticSurface | undefined = undefined;
+void diagnosticSurface;
+
+// These names were duplicate projections of the SceneError code/detail owners.
+// @ts-expect-error hierarchy diagnostics use SceneErrorCode directly.
+export type RemovedDiagnosticCode = SceneSurface['SceneHierarchyDiagnosticCode'];
+// @ts-expect-error hierarchy diagnostics use SceneErrorDetail directly.
+export type RemovedDiagnosticDetail = SceneSurface['SceneHierarchyDiagnosticDetail'];

package/src/__tests__/direct-child-of-import.unit.test.ts

@@ -0,0 +1,13 @@
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { describe, expect, it, vi } from 'vitest';
+
+describe('scene ChildOf module', () => {
+  it('registers its Children mirror when imported directly', async () => {
+    vi.resetModules();
+    const { ChildOf } = await import('../components/child-of');
+    const { Children } = await import('../components/children');
+
+    expect(ChildOf.name).toBe('ChildOf');
+    expect(componentSchema(Children).entities).toBe('array<entity>');
+  });
+});

package/src/__tests__/fixtures/malformed-hierarchy-edge.ts

@@ -0,0 +1,15 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { ChildOf } from '../../index';
+
+/**
+ * Scene-owned malformed-edge fixture. The public relationship write accepts
+ * stale handles as data; the projection then owns the liveness diagnostic.
+ * Keeping this fixture on `world.set` avoids a private ECS graph seam.
+ */
+export function setMalformedParentEdge(
+  world: World,
+  child: EntityHandle,
+  parent: EntityHandle,
+): void {
+  world.set(child, ChildOf, { parent }).unwrap();
+}