@forgeax/engine-scene 0.1.20 → 0.1.23

package/dist/index.mjs

@@ -64,7 +64,11 @@ function resolveSceneWireRefs(payload, refs) {
     for (const [componentName, rawFields] of Object.entries(entity.components)) {
       components[componentName] = { ...rawFields };
     }
-    entities.push({ localId: entity.localId, components });
+    entities.push({
+      localId: entity.localId,
+      ...entity.bindingKey === void 0 ? {} : { bindingKey: entity.bindingKey },
+      components
+    });
   }
   const mounts = resolveMounts(payload.mounts, refs);
   if (!mounts.ok) return mounts;
@@ -77,6 +81,7 @@ function resolveSceneWireRefs(payload, refs) {
     ok: true,
     value: {
       kind: "scene",
+      ...payload.sourceKey === void 0 ? {} : { sourceKey: payload.sourceKey },
       entities,
       ...mounts.value === void 0 ? {} : { mounts: mounts.value },
       ...skinGuids.value === void 0 ? {} : { skinGuids: skinGuids.value }
@@ -103,11 +108,39 @@ var sceneAssetContribution = {
 
 // src/components/children.ts
 import { defineRelationship } from "@forgeax/engine-ecs";
+
+// src/components/transform.ts
+import { defineComponent } from "@forgeax/engine-ecs";
+var IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+var GlobalTransform = defineComponent(
+  "GlobalTransform",
+  {
+    world: { type: "array<f32, 16>", default: IDENTITY_MAT4 }
+  },
+  { transient: true }
+);
+var 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] }
+);
+
+// src/components/children.ts
 var { source: ChildOf, target: Children } = defineRelationship({
   sourceName: "ChildOf",
   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
 });
@@ -134,29 +167,14 @@ function collectSubtree(world, spawnRoot, visited) {
 }
 
 // src/components/morph-weights.ts
-import { defineComponent } from "@forgeax/engine-ecs";
-var MorphWeights = defineComponent("MorphWeights", {
+import { defineComponent as defineComponent2 } from "@forgeax/engine-ecs";
+var MorphWeights = defineComponent2("MorphWeights", {
   weights: { type: "array<f32>" }
 });
 
 // src/components/name.ts
-import { defineComponent as defineComponent2 } from "@forgeax/engine-ecs";
-var Name = defineComponent2("Name", { value: { type: "string" } });
-
-// src/components/transform.ts
 import { defineComponent as defineComponent3 } from "@forgeax/engine-ecs";
-var IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
-var Transform = defineComponent3("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 }
-});
+var Name = defineComponent3("Name", { value: { type: "string" } });
 
 // src/errors.ts
 import { ComponentNotDefinedError } from "@forgeax/engine-ecs/projection";
@@ -175,6 +193,55 @@ var SceneError = class extends Error {
   }
 };
 
+// src/instances/binding.ts
+import { err as err2, ok as ok2 } from "@forgeax/engine-types";
+function validateSceneBindings(sceneSourceKey, bindingKeys) {
+  if (sceneSourceKey.length === 0) {
+    return err2({
+      code: "scene-binding-source-missing",
+      expected: "a non-empty scene sourceKey",
+      hint: "declare the scene sourceKey in the author inventory",
+      detail: {}
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const bindingKey of bindingKeys) {
+    if (bindingKey.length === 0 || seen.has(bindingKey)) {
+      return err2({
+        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 ok2([...bindingKeys]);
+}
+function sceneEntity(sceneSourceKey, bindingKey) {
+  return { sceneSourceKey, bindingKey };
+}
+function resolveSceneEntity(ref, instance) {
+  if (ref.sceneSourceKey !== instance.sceneSourceKey) {
+    return err2({
+      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 === void 0) {
+    return err2({
+      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 ok2(value);
+}
+
 // src/instances/collect-profile.ts
 var SCENE_COLLECT_PROFILE = Object.freeze({
   includeComponent: (_componentName, transient) => !transient,
@@ -182,7 +249,7 @@ var SCENE_COLLECT_PROFILE = Object.freeze({
 });
 
 // src/instances/externalization.ts
-import { err as err2, ok as ok2 } from "@forgeax/engine-types";
+import { err as err3, ok as ok3 } from "@forgeax/engine-types";
 function sharedKind(type) {
   if (type?.startsWith("shared<")) return "one";
   if (type?.startsWith("array<shared<")) return "many";
@@ -236,7 +303,11 @@ function externalizeSceneAsset(scene, resolveSchema) {
         components[componentName] = fields;
       }
     }
-    return { localId: entity.localId, components };
+    return {
+      localId: entity.localId,
+      ...entity.bindingKey === void 0 ? {} : { bindingKey: entity.bindingKey },
+      components
+    };
   });
   const mounts = scene.mounts?.map((mount) => {
     const source = typeof mount.source === "string" ? addRef(
@@ -260,11 +331,13 @@ function externalizeSceneAsset(scene, resolveSchema) {
     };
   });
   for (const [arrayIndex, guid] of (scene.skinGuids ?? []).entries()) {
-    if (typeof guid !== "string") return err2({ field: "skinGuids", value: guid });
+    if (typeof guid !== "string") return err3({ field: "skinGuids", value: guid });
     addRef(guid, { componentName: "<scene>", fieldName: "skinGuids", arrayIndex });
   }
-  return ok2({
+  return ok3({
     payload: {
+      kind: "scene",
+      ...scene.sourceKey === void 0 ? {} : { sourceKey: scene.sourceKey },
       entities,
       ...mounts === void 0 || mounts.length === 0 ? {} : { mounts },
       ...scene.skinGuids === void 0 ? {} : { skinGuids: scene.skinGuids.map((guid) => indexByGuid.get(guid)) }
@@ -281,14 +354,14 @@ import { classifyEntityField, remapEntityFieldValue } from "@forgeax/engine-ecs/
 import { componentSchema } from "@forgeax/engine-ecs/internal";
 import { fillComponentDefaults, StaleEntityError } from "@forgeax/engine-ecs/projection";
 import {
-  err as err3,
-  ok as ok3,
+  err as err4,
+  ok as ok4,
   PACK_ERROR_HINTS,
   toUnique,
   unwrapHandle
 } from "@forgeax/engine-types";
-var entityIndex = (entity) => entity & 16777215;
-var entityGeneration = (entity) => entity >>> 24 & 255;
+
+// src/instances/state.ts
 var sceneWorldStates = /* @__PURE__ */ new WeakMap();
 function sceneWorldState(world) {
   const current = sceneWorldStates.get(world);
@@ -297,6 +370,24 @@ function sceneWorldState(world) {
   sceneWorldStates.set(world, created);
   return created;
 }
+function mountOverrideStateKey(ov) {
+  return ov.field !== void 0 ? `${ov.comp}:${ov.field}` : ov.comp;
+}
+function isPrimitiveScalarFieldType(fieldType) {
+  if (fieldType === "f32" || fieldType === "f64" || fieldType === "u32" || fieldType === "i32" || fieldType === "u8" || fieldType === "i8" || fieldType === "u16" || fieldType === "i16" || fieldType === "bool" || fieldType === "string") {
+    return true;
+  }
+  return fieldType.startsWith("enum<");
+}
+function primitiveJsType(fieldType) {
+  if (fieldType === "bool") return "boolean";
+  if (fieldType === "string") return "string";
+  return "number";
+}
+
+// src/instances/scene-instances.ts
+var entityIndex = (entity) => entity & 16777215;
+var entityGeneration = (entity) => entity >>> 24 & 255;
 function worldSetSceneAssetResolver(world, resolver) {
   sceneWorldState(world).resolver = resolver;
 }
@@ -308,7 +399,7 @@ function worldInstantiateScene(world, handle, parent) {
   const diagnostics = [];
   const r = worldInstantiateSceneRec(world, handle, parent, stack, diagnostics);
   if (!r.ok) return r;
-  return ok3({ root: r.value, diagnostics });
+  return ok4({ root: r.value, diagnostics });
 }
 function worldInstantiateScenePayload(world, asset, parent) {
   const handle = world.allocSharedRef("SceneAsset", asset);
@@ -332,7 +423,7 @@ function worldInstantiateSceneFlat(world, handle) {
     stack.delete(handleKey);
   }
   if (!r.ok) return r;
-  return ok3({ ...r.value, diagnostics });
+  return ok4({ ...r.value, diagnostics });
 }
 function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
   const handleKey = unwrapHandle(handle);
@@ -345,7 +436,7 @@ function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
       kind: "mount-asset",
       cycle: cycleArr
     };
-    return err3({
+    return err4({
       code: "pack-cyclic-reference",
       expected: "acyclic SceneAsset mount graph",
       hint: PACK_ERROR_HINTS["pack-cyclic-reference"],
@@ -365,18 +456,27 @@ function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
 function worldResolveSceneAsset(world, handle) {
   const r = world.sharedRefs.resolve(handle);
   if (!r.ok) {
-    return err3(r.error);
+    return err4(r.error);
   }
-  return ok3(r.value);
+  return ok4(r.value);
 }
 function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err3(new ComponentNotDefinedError("SceneInstance"));
+    return err4(new ComponentNotDefinedError("SceneInstance"));
   }
   const childOfToken = world.components.resolve("ChildOf");
   const ownEntities = asset.entities;
   const ownMounts = asset.mounts ?? [];
+  const bindingKeys = ownEntities.flatMap(
+    (entity) => entity.bindingKey === void 0 ? [] : [entity.bindingKey]
+  );
+  if (bindingKeys.length > 0) {
+    const bindingCheck = validateSceneBindings(asset.sourceKey ?? "", bindingKeys);
+    if (!bindingCheck.ok) {
+      return err4(bindingCheck.error);
+    }
+  }
   const memberSum = ownMounts.reduce((s, m) => s + m.memberCount, 0);
   const countBaseline = ownEntities.length + ownMounts.length + memberSum;
   let maxLocalId = ownEntities.reduce((m, e) => Math.max(m, e.localId), -1);
@@ -417,7 +517,7 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
     }
     if (overlapLids.size > 0) {
       const overlapping = Array.from(overlapLids).sort((a, b) => a - b);
-      return err3({
+      return err4({
         code: "pack-mount-localid-overlap",
         expected: "each LocalEntityId claimed by exactly one entity or mount slot",
         hint: PACK_ERROR_HINTS["pack-mount-localid-overlap"],
@@ -457,7 +557,7 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
     const childMapping = childInstRes.value.mapping;
     mountInstances.push({ mount, root: childRes.value, mapping: childMapping });
     if (childMapping.length !== mount.memberCount) {
-      return err3({
+      return err4({
         code: "pack-mount-count-mismatch",
         expected: "mount.memberCount === child SceneAsset totalSlots",
         hint: PACK_ERROR_HINTS["pack-mount-count-mismatch"],
@@ -528,7 +628,7 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
       }
     }
   }
-  return ok3({
+  return ok4({
     mapping,
     entityToLocalId,
     rootEntities,
@@ -541,7 +641,7 @@ function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
 function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err3(new ComponentNotDefinedError("SceneInstance"));
+    return err4(new ComponentNotDefinedError("SceneInstance"));
   }
   const childOfToken = world.components.resolve("ChildOf");
   const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
@@ -599,8 +699,18 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
     }
   }
   const detached = /* @__PURE__ */ new Set();
+  const bindings = /* @__PURE__ */ new Map();
+  for (const entity of asset.entities) {
+    if (entity.bindingKey === void 0) continue;
+    const live = mapping[entity.localId];
+    if (live !== void 0 && live !== ENTITY_NULL_RAW) {
+      bindings.set(entity.bindingKey, live);
+    }
+  }
   const state = {
     source: handle,
+    sceneSourceKey: asset.sourceKey,
+    bindings,
     entityToLocalId,
     detachedLocalIds: detached,
     // Convert overrides Map<LocalEntityId, Map<string, MountOverride>>
@@ -641,7 +751,7 @@ function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnos
       if (!r.ok) return r;
     }
   }
-  return ok3(rootEntity);
+  return ok4(rootEntity);
 }
 function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics) {
   const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
@@ -680,7 +790,7 @@ function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics
       }
     }
   }
-  return ok3({ roots: [...rootEntities, ...mountEntitiesNeedingRootParent], mountEntities });
+  return ok4({ roots: [...rootEntities, ...mountEntitiesNeedingRootParent], mountEntities });
 }
 function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics) {
   const out = [];
@@ -688,7 +798,7 @@ function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics)
   for (const compName of Object.keys(node.components)) {
     const token = world.components.resolve(compName);
     if (token === void 0) {
-      return err3(new ComponentNotDefinedError(compName));
+      return err4(new ComponentNotDefinedError(compName));
     }
     const raw = node.components[compName] ?? {};
     const schema = componentSchema(token);
@@ -715,11 +825,11 @@ function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics)
     const filled = fillComponentDefaults(token, remappedRaw);
     out.push({ component: token, data: filled });
   }
-  return ok3(out);
+  return ok4(out);
 }
 function worldApplyMountOverride(world, member, ov) {
   const ovToken = world.components.resolve(ov.comp);
-  if (ovToken === void 0) return ok3(void 0);
+  if (ovToken === void 0) return ok4(void 0);
   if (ov.field !== void 0) {
     return world.set(member, ovToken, { [ov.field]: ov.value });
   }
@@ -733,7 +843,7 @@ function worldApplyMountOverride(world, member, ov) {
 }
 function worldValidateMountOverrides(world, mount) {
   const overrides = mount.overrides;
-  if (overrides === void 0) return ok3(void 0);
+  if (overrides === void 0) return ok4(void 0);
   const memberFirst = mount.memberFirst;
   const memberCount = mount.memberCount;
   const memberLast = memberFirst + memberCount;
@@ -741,7 +851,7 @@ function worldValidateMountOverrides(world, mount) {
   for (const ov of overrides) {
     const ovLid = ov.localId;
     if (ovLid < memberFirst || ovLid >= memberLast) {
-      return err3({
+      return err4({
         code: "pack-mount-override-localid-out-of-range",
         expected: `override.localId in [${memberFirst}, ${memberLast})`,
         hint: PACK_ERROR_HINTS["pack-mount-override-localid-out-of-range"],
@@ -758,7 +868,7 @@ function worldValidateMountOverrides(world, mount) {
       if (ovToken !== void 0) {
         const schema = componentSchema(ovToken);
         if (!(ov.field in schema)) {
-          return err3({
+          return err4({
             code: "pack-mount-override-unknown-field",
             expected: `override.field defined on component '${ov.comp}'`,
             hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
@@ -773,13 +883,13 @@ function worldValidateMountOverrides(world, mount) {
       }
     } else {
       if (ovToken === void 0) {
-        return err3(new ComponentNotDefinedError(ov.comp));
+        return err4(new ComponentNotDefinedError(ov.comp));
       }
       const schema = componentSchema(ovToken);
       const valueMap = ov.value ?? {};
       for (const key of Object.keys(valueMap)) {
         if (!(key in schema)) {
-          return err3({
+          return err4({
             code: "pack-mount-override-unknown-field",
             expected: `override.value keys defined on component '${ov.comp}'`,
             hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
@@ -794,7 +904,7 @@ function worldValidateMountOverrides(world, mount) {
       }
     }
   }
-  return ok3(void 0);
+  return ok4(void 0);
 }
 function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
   const fakeNode = {
@@ -813,7 +923,7 @@ function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
   if (cdRes.value.length === 0) {
     const childOfToken = world.components.resolve("ChildOf");
     if (childOfToken === void 0) {
-      return err3(new ComponentNotDefinedError("ChildOf"));
+      return err4(new ComponentNotDefinedError("ChildOf"));
     }
     cdRes.value.push({
       component: childOfToken,
@@ -825,7 +935,7 @@ function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
 function worldResolveMountSource(world, source, parentHandle) {
   const resolver = worldGetSceneAssetResolver(world);
   if (resolver === null) {
-    return err3({
+    return err4({
       code: "stale-entity",
       expected: "wired SceneAssetResolver (auto-wired by engine.assets.instantiate)",
       hint: "engine.assets.instantiate sugar wires this for you; call worldSetSceneAssetResolver before nested scene expansion.",
@@ -834,9 +944,9 @@ function worldResolveMountSource(world, source, parentHandle) {
   }
   const r = resolver(source, parentHandle);
   if (!r.ok) {
-    return err3(r.error);
+    return err4(r.error);
   }
-  return ok3(r.value);
+  return ok4(r.value);
 }
 function worldMountOverridesToStateMap(src) {
   const out = /* @__PURE__ */ new Map();
@@ -859,7 +969,7 @@ function worldSetUniqueRefPayload(world, handle, payload) {
 function worldResolveSceneInstanceStatePayload(world, root) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err3(new ComponentNotDefinedError("SceneInstance"));
+    return err4(new ComponentNotDefinedError("SceneInstance"));
   }
   const r = world.get(root, sceneInstanceToken);
   if (!r.ok) return r;
@@ -867,7 +977,7 @@ function worldResolveSceneInstanceStatePayload(world, root) {
   const stateRefHandle = toUnique(stateRefRaw);
   const payload = sceneWorldState(world).statePayloads.get(Number(stateRefHandle));
   if (payload === void 0) {
-    return err3(
+    return err4(
       new StaleEntityError(root, entityIndex(root), entityGeneration(root), {
         operation: "resolveSceneInstanceState",
         component: "SceneInstance",
@@ -876,17 +986,27 @@ function worldResolveSceneInstanceStatePayload(world, root) {
       })
     );
   }
-  return ok3(payload);
+  return ok4(payload);
 }
 function worldGetSceneInstanceState(world, root) {
   return worldResolveSceneInstanceStatePayload(world, root);
 }
+function worldResolveSceneEntity(world, root, ref) {
+  const state = worldResolveSceneInstanceStatePayload(world, root);
+  if (!state.ok) return state;
+  const resolved = resolveSceneEntity(ref, {
+    sceneSourceKey: state.value.sceneSourceKey ?? ref.sceneSourceKey,
+    bindings: state.value.bindings
+  });
+  if (!resolved.ok) return err4(resolved.error);
+  return ok4(resolved.value);
+}
 function worldDespawnScene(world, root, opts) {
   const dRes = worldDespawnDescendants(world, root, opts);
   if (!dRes.ok) return dRes;
   const drop = world.despawn(root);
   if (!drop.ok) return drop;
-  return ok3(dRes.value + 1);
+  return ok4(dRes.value + 1);
 }
 function worldDespawnDescendants(world, root, opts) {
   let detached = null;
@@ -963,7 +1083,7 @@ function worldDespawnDescendants(world, root, opts) {
     }
     count += 1;
   }
-  return ok3(count);
+  return ok4(count);
 }
 function worldSetSceneOverride(world, root, member, component, field, value) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
@@ -971,7 +1091,7 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
   if (lid === void 0) {
-    return err3(
+    return err4(
       new StaleEntityError(
         member,
         entityIndex(member),
@@ -990,7 +1110,7 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
     const expectJsType = primitiveJsType(schemaType);
     const actualJsType = typeof value;
     if (expectJsType !== actualJsType) {
-      return err3({
+      return err4({
         code: "scene-override-type-mismatch",
         expected: `value typeof === ${expectJsType}`,
         hint: `setSceneOverride(${component.name}.${field}) expected ${expectJsType}, got ${actualJsType}; coerce or pick a different override path.`,
@@ -1016,14 +1136,14 @@ function worldSetSceneOverride(world, root, member, component, field, value) {
     field,
     value
   });
-  return ok3(void 0);
+  return ok4(void 0);
 }
 function worldRemoveSceneOverride(world, root, member, component, field) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok3(void 0);
+  if (lid === void 0) return ok4(void 0);
   const fieldMap = state.overrides.get(lid);
   if (fieldMap !== void 0) {
     fieldMap.delete(`${component.name}:${field}`);
@@ -1039,34 +1159,34 @@ function worldRemoveSceneOverride(world, root, member, component, field) {
     const r = world.set(member, component, { [field]: layer1[field] });
     if (!r.ok) return r;
   }
-  return ok3(void 0);
+  return ok4(void 0);
 }
 function worldDetachSceneMember(world, root, member) {
   const sceneInstanceToken = world.components.resolve("SceneInstance");
   if (sceneInstanceToken === void 0) {
-    return err3(new ComponentNotDefinedError("SceneInstance"));
+    return err4(new ComponentNotDefinedError("SceneInstance"));
   }
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok3(void 0);
+  if (lid === void 0) return ok4(void 0);
   state.detachedLocalIds.add(lid);
-  return ok3(void 0);
+  return ok4(void 0);
 }
 function worldReattachSceneMember(world, root, member) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
   const state = stateRes.value;
   const lid = state.entityToLocalId.get(member);
-  if (lid === void 0) return ok3(void 0);
+  if (lid === void 0) return ok4(void 0);
   state.detachedLocalIds.delete(lid);
-  return ok3(void 0);
+  return ok4(void 0);
 }
 function worldGetSceneAssetForInstance(world, root) {
   const stateRes = worldResolveSceneInstanceStatePayload(world, root);
   if (!stateRes.ok) return stateRes;
-  return ok3(stateRes.value.source);
+  return ok4(stateRes.value.source);
 }
 function sceneTopoSort(nodes) {
   const n = nodes.length;
@@ -1109,21 +1229,6 @@ function sceneTopoSort(nodes) {
   }
   return order;
 }
-function mountOverrideStateKey(ov) {
-  return ov.field !== void 0 ? `${ov.comp}:${ov.field}` : ov.comp;
-}
-function isPrimitiveScalarFieldType(fieldType) {
-  if (fieldType === "f32" || fieldType === "f64" || fieldType === "u32" || fieldType === "i32" || fieldType === "u8" || fieldType === "i8" || fieldType === "u16" || fieldType === "i16" || fieldType === "bool" || fieldType === "string") {
-    return true;
-  }
-  if (fieldType.startsWith("enum<")) return true;
-  return false;
-}
-function primitiveJsType(fieldType) {
-  if (fieldType === "bool") return "boolean";
-  if (fieldType === "string") return "string";
-  return "number";
-}
 
 // src/systems/propagate-transforms.ts
 import {
@@ -1132,316 +1237,338 @@ import {
   FixedUpdate,
   Update
 } from "@forgeax/engine-ecs";
-import {
-  createWorldProjection as createWorldProjection2,
-  setDerivedComponent
-} from "@forgeax/engine-ecs/projection";
 import { mat4 } from "@forgeax/engine-math";
-import { err as err4, ok as ok4 } from "@forgeax/engine-types";
-
-// src/systems/hierarchy-projection.ts
-import { Entity } from "@forgeax/engine-ecs";
-import { createWorldProjection } from "@forgeax/engine-ecs/projection";
-var HIERARCHY_PROJECTION_CACHE = /* @__PURE__ */ new WeakMap();
-function diagnostic(code, entity, parent) {
-  if (code === "hierarchy-cycle") {
-    return {
-      code,
-      expected: "ChildOf parent edges form an acyclic live hierarchy",
-      hint: "remove one ChildOf edge from the reported cycle, then re-run the extract",
-      detail: { entity, parent }
-    };
-  }
-  return {
-    code,
-    expected: "ChildOf.parent references a live entity in the same World",
-    hint: "remove the stale ChildOf component or restore the referenced parent in this World",
-    detail: { entity, parent }
-  };
-}
-function projectHierarchy(world) {
-  const cached = HIERARCHY_PROJECTION_CACHE.get(world);
-  const changes = cached?.changes ?? createWorldProjection(world, { components: [ChildOf] });
-  if (cached !== void 0) {
-    const evidence = changes.poll();
-    if (evidence.status === "delta" && evidence.changes.length === 0) return cached.snapshot;
-  }
-  const liveEntities = /* @__PURE__ */ new Set();
-  const authoredParents = /* @__PURE__ */ new Map();
-  const query = world.query({ read: [Entity], optional: [ChildOf] });
-  if (query.ok) {
-    for (const row of query.value) {
-      liveEntities.add(row.entity);
-      const parent = row.get(ChildOf)?.parent;
-      if (parent !== void 0 && parent !== null) authoredParents.set(row.entity, parent);
-    }
-  }
-  const parentOf = /* @__PURE__ */ new Map();
-  const diagnostics = [];
-  for (const [entity, parent] of authoredParents) {
-    if (liveEntities.has(parent)) {
-      parentOf.set(entity, parent);
-    } else {
-      diagnostics.push(diagnostic("hierarchy-broken", entity, parent));
-    }
-  }
-  const state = /* @__PURE__ */ new Map();
-  const stack = [];
-  const cycleMembers = /* @__PURE__ */ new Set();
-  const visit = (entity) => {
-    const currentState = state.get(entity) ?? 0;
-    if (currentState === 2) return;
-    if (currentState === 1) {
-      const cycleStart = stack.indexOf(entity);
-      for (let index = cycleStart; index >= 0 && index < stack.length; index++) {
-        const member = stack[index];
-        if (member !== void 0) cycleMembers.add(member);
-      }
-      return;
-    }
-    state.set(entity, 1);
-    stack.push(entity);
-    const parent = parentOf.get(entity);
-    if (parent !== void 0) visit(parent);
-    stack.pop();
-    state.set(entity, 2);
-  };
-  for (const entity of liveEntities) visit(entity);
-  for (const entity of cycleMembers) {
-    const parent = authoredParents.get(entity);
-    if (parent !== void 0) diagnostics.push(diagnostic("hierarchy-cycle", entity, parent));
-    parentOf.delete(entity);
-  }
-  diagnostics.sort((left, right) => {
-    const entityDelta = left.detail.entity - right.detail.entity;
-    if (entityDelta !== 0) return entityDelta;
-    return left.code.localeCompare(right.code);
-  });
-  const stableParentOf = new Map(parentOf);
-  const stableDiagnostics = Object.freeze(diagnostics.slice());
-  const snapshot = {
-    parentOf: stableParentOf,
-    diagnostics: stableDiagnostics,
-    getParent(entity) {
-      return stableParentOf.get(entity);
-    }
-  };
-  HIERARCHY_PROJECTION_CACHE.set(world, {
-    changes,
-    snapshot
-  });
-  return snapshot;
-}
-
-// src/systems/propagate-transforms.ts
+import { err as err5, ok as ok5 } from "@forgeax/engine-types";
 var PROPAGATE_TRANSFORMS_SYSTEM = "propagateTransforms";
 var PROPAGATE_TRANSFORMS_FIXED_SYSTEM = "propagateTransformsFixed";
 var TransformSet = defineSystemSet({ name: "transform" });
 var TransformFixedSet = defineSystemSet({ name: "transform-fixed" });
-var CACHE = /* @__PURE__ */ new WeakMap();
+var SCRATCH = /* @__PURE__ */ new WeakMap();
 var REGISTRATION_LEASES = /* @__PURE__ */ new WeakMap();
-function copyState(value) {
-  return {
-    pos: new Float32Array(value.pos),
-    quat: new Float32Array(value.quat),
-    scale: new Float32Array(value.scale)
-  };
+function pairError(entity, expected) {
+  return err5(
+    new SceneError({
+      code: "hierarchy-broken",
+      expected,
+      hint: "attach both Transform and GlobalTransform at scene authoring or import time, then retry propagation",
+      detail: { entity, parent: entity }
+    })
+  );
 }
-function sameArray(left, right) {
-  if (left.length !== right.length) return false;
-  for (let index = 0; index < left.length; index += 1) {
-    if (left[index] !== right[index]) return false;
-  }
-  return true;
+function ensureQueries(world, scratch) {
+  if (scratch.flatQuery !== void 0 && scratch.outputQuery !== void 0 && scratch.hierarchyQuery !== void 0 && scratch.missingGlobalQuery !== void 0 && scratch.missingTransformQuery !== void 0) {
+    return ok5(void 0);
+  }
+  const flatOutput = world.query({
+    read: [Transform],
+    write: [GlobalTransform],
+    without: [ChildOf],
+    changed: [Transform]
+  });
+  const output = world.query({ write: [GlobalTransform] });
+  const hierarchy = world.query({ read: [Transform, ChildOf] });
+  const missingGlobal = world.query({ with: [Transform], without: [GlobalTransform] });
+  const missingTransform = world.query({ with: [GlobalTransform], without: [Transform] });
+  if (!flatOutput.ok || !output.ok || !hierarchy.ok || !missingGlobal.ok || !missingTransform.ok) {
+    return pairError(0, "valid Transform and GlobalTransform pair queries");
+  }
+  scratch.flatQuery = flatOutput.value;
+  scratch.outputQuery = output.value;
+  scratch.hierarchyQuery = hierarchy.value;
+  scratch.missingGlobalQuery = missingGlobal.value;
+  scratch.missingTransformQuery = missingTransform.value;
+  return ok5(void 0);
 }
-function sameState(left, right) {
-  return left !== void 0 && sameArray(left.pos, right.pos) && sameArray(left.quat, right.quat) && sameArray(left.scale, right.scale);
+function validateTransformPairs(world, scratch) {
+  const queryResult = ensureQueries(world, scratch);
+  if (!queryResult.ok) return queryResult;
+  const missingGlobal = scratch.missingGlobalQuery;
+  const missingTransform = scratch.missingTransformQuery;
+  if (missingGlobal === void 0 || missingTransform === void 0) {
+    return pairError(0, "valid Transform and GlobalTransform pair queries");
+  }
+  for (const row of missingGlobal) {
+    return pairError(row.entity, "each Transform entity to carry a GlobalTransform pair");
+  }
+  for (const row of missingTransform) {
+    return pairError(row.entity, "each GlobalTransform entity to carry a Transform pair");
+  }
+  return ok5(void 0);
 }
-function compose(state, out) {
-  mat4.compose(out, state.pos, state.quat, state.scale);
+function scratchFor(world) {
+  const existing = SCRATCH.get(world);
+  if (existing !== void 0) return existing;
+  const created = {
+    position: new Float32Array(3),
+    rotation: new Float32Array(4),
+    scale: new Float32Array(3),
+    local: mat4.create(),
+    hierarchyPath: []
+  };
+  SCRATCH.set(world, created);
+  return created;
 }
-function indexChildren(hierarchy) {
-  const childrenOf = /* @__PURE__ */ new Map();
-  for (const [child, parent] of hierarchy.parentOf) {
-    const children = childrenOf.get(parent);
-    if (children === void 0) childrenOf.set(parent, [child]);
-    else children.push(child);
-  }
-  return childrenOf;
+function composeColumns(position, rotation, scale, out, scratch, positionStart = 0, rotationStart = 0) {
+  scratch.position[0] = position[positionStart] ?? 0;
+  scratch.position[1] = position[positionStart + 1] ?? 0;
+  scratch.position[2] = position[positionStart + 2] ?? 0;
+  scratch.rotation[0] = rotation[rotationStart] ?? 0;
+  scratch.rotation[1] = rotation[rotationStart + 1] ?? 0;
+  scratch.rotation[2] = rotation[rotationStart + 2] ?? 0;
+  scratch.rotation[3] = rotation[rotationStart + 3] ?? 1;
+  scratch.scale[0] = scale[positionStart] ?? 1;
+  scratch.scale[1] = scale[positionStart + 1] ?? 1;
+  scratch.scale[2] = scale[positionStart + 2] ?? 1;
+  mat4.compose(out, scratch.position, scratch.rotation, scratch.scale);
 }
-function descendants(childrenOf, roots) {
-  const affected = new Set(roots);
-  const pending = [...roots];
-  for (let index = 0; index < pending.length; index += 1) {
-    const parent = pending[index];
-    if (parent === void 0) continue;
-    for (const child of childrenOf.get(parent) ?? []) {
-      if (affected.has(child)) continue;
-      affected.add(child);
-      pending.push(child);
-    }
+function composeFlatColumns(positions, rotations, scales, worlds, count) {
+  for (let row = 0; row < count; row += 1) {
+    const position = row * 3;
+    const rotation = row * 4;
+    const world = row * 16;
+    const x = rotations[rotation] ?? 0;
+    const y = rotations[rotation + 1] ?? 0;
+    const z = rotations[rotation + 2] ?? 0;
+    const w = rotations[rotation + 3] ?? 1;
+    const x2 = x + x;
+    const y2 = y + y;
+    const z2 = z + z;
+    const xx = x * x2;
+    const xy = x * y2;
+    const xz = x * z2;
+    const yy = y * y2;
+    const yz = y * z2;
+    const zz = z * z2;
+    const wx = w * x2;
+    const wy = w * y2;
+    const wz = w * z2;
+    const sx = scales[position] ?? 1;
+    const sy = scales[position + 1] ?? 1;
+    const sz = scales[position + 2] ?? 1;
+    worlds[world] = (1 - (yy + zz)) * sx;
+    worlds[world + 1] = (xy + wz) * sx;
+    worlds[world + 2] = (xz - wy) * sx;
+    worlds[world + 3] = 0;
+    worlds[world + 4] = (xy - wz) * sy;
+    worlds[world + 5] = (1 - (xx + zz)) * sy;
+    worlds[world + 6] = (yz + wx) * sy;
+    worlds[world + 7] = 0;
+    worlds[world + 8] = (xz + wy) * sz;
+    worlds[world + 9] = (yz - wx) * sz;
+    worlds[world + 10] = (1 - (xx + yy)) * sz;
+    worlds[world + 11] = 0;
+    worlds[world + 12] = positions[position] ?? 0;
+    worlds[world + 13] = positions[position + 1] ?? 0;
+    worlds[world + 14] = positions[position + 2] ?? 0;
+    worlds[world + 15] = 1;
   }
-  return affected;
-}
-function hierarchyError(hierarchy) {
-  const first = hierarchy.diagnostics[0];
-  if (first === void 0) return ok4(void 0);
-  return err4(
-    new SceneError({
-      code: first.code,
-      expected: first.expected,
-      hint: first.hint,
-      detail: first.detail
-    })
-  );
 }
-function buildCache(world, projection) {
-  const hierarchy = projectHierarchy(world);
-  const locals = /* @__PURE__ */ new Map();
-  const entities = /* @__PURE__ */ new Set();
-  const query = world.query({ read: [Transform], optional: [ChildOf] });
-  if (query.ok) {
-    for (const row of query.value) {
-      const transform = row.get(Transform);
-      if (transform === void 0) continue;
-      entities.add(row.entity);
-      locals.set(row.entity, copyState(transform));
+function writeWorld(world, output, entity, value) {
+  const row = output.at(entity);
+  if (row === void 0) {
+    return err5(
+      new SceneError({
+        code: "hierarchy-broken",
+        expected: "each Transform entity to carry a GlobalTransform pair",
+        hint: "attach GlobalTransform at scene authoring or import time, then retry propagation",
+        detail: { entity, parent: entity }
+      })
+    );
+  }
+  const current = world.get(entity, GlobalTransform);
+  if (!current.ok)
+    return err5(
+      new SceneError({
+        code: "hierarchy-broken",
+        expected: "each Transform entity to carry a GlobalTransform pair",
+        hint: "attach GlobalTransform at scene authoring or import time, then retry propagation",
+        detail: { entity, parent: entity }
+      })
+    );
+  let changed = false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (current.value.world[index] !== value[index]) {
+      changed = true;
+      break;
     }
   }
-  return {
-    projection,
-    hierarchy,
-    parentOf: hierarchy.parentOf,
-    childrenOf: indexChildren(hierarchy),
-    entities,
-    locals,
-    derived: /* @__PURE__ */ new Map(),
-    result: ok4(void 0)
-  };
+  if (!changed) return ok5(void 0);
+  row.mut(GlobalTransform).world.set(value);
+  return ok5(void 0);
 }
-function deriveEntity(world, entity, cache, affected, visiting, published) {
-  if (!affected.has(entity) || cache.derived.has(entity)) return ok4(void 0);
-  if (visiting.has(entity)) return ok4(void 0);
-  visiting.add(entity);
-  const local = cache.locals.get(entity);
-  if (local === void 0) {
-    visiting.delete(entity);
-    return ok4(void 0);
-  }
-  const parent = cache.parentOf.get(entity);
-  if (parent !== void 0 && cache.entities.has(parent)) {
-    const parentResult = deriveEntity(world, parent, cache, affected, visiting, published);
-    if (!parentResult.ok) return parentResult;
-  }
-  const localWorld = mat4.create();
-  compose(local, localWorld);
-  const parentWorld = parent === void 0 ? void 0 : cache.derived.get(parent);
-  const resolved = mat4.create();
-  if (parentWorld === void 0) resolved.set(localWorld);
-  else mat4.multiply(resolved, parentWorld, localWorld);
-  const write = setDerivedComponent(world, entity, Transform, { world: resolved });
-  if (!write.ok) {
-    visiting.delete(entity);
-    return err4(
+function propagateFlat(scratch) {
+  const query = scratch.flatQuery;
+  if (query === void 0)
+    return err5(
       new SceneError({
         code: "hierarchy-broken",
-        expected: "the derived Transform.world write to succeed",
-        hint: "inspect the ECS mutation error before retrying transform propagation",
-        detail: { entity, parent: entity }
+        expected: "a valid changed Transform write query",
+        hint: "register the scene components before running TransformPropagation"
+      })
+    );
+  const spans = query.spans();
+  if (!spans.ok) return pairError(0, "dense numeric Transform spans");
+  let bindingIndex = 0;
+  try {
+    for (const span of spans.value) {
+      const local = span.get(Transform);
+      const world = span.mut(GlobalTransform).world;
+      composeFlatColumns(local.pos, local.quat, local.scale, world, span.length);
+      bindingIndex += 1;
+    }
+  } catch (cause) {
+    const error = cause;
+    return err5(
+      new SceneError({
+        code: "hierarchy-broken",
+        expected: "derived GlobalTransform range publication to succeed",
+        hint: error.hint,
+        detail: {
+          kind: "derived-write",
+          entity: 0,
+          parent: 0,
+          bindingIndex,
+          base: 0,
+          start: 0,
+          count: 0,
+          cause: error
+        }
       })
     );
   }
-  cache.derived.set(entity, resolved);
-  published.add(entity);
-  visiting.delete(entity);
-  return ok4(void 0);
+  return ok5(void 0);
 }
-function drainPublishedChanges(cache, published) {
-  const drained = cache.projection.poll();
-  if (drained.status === "rebuild") return true;
-  return drained.changes.every(
-    (change) => change.kind === "derived-component-changed" && change.component === Transform && published.has(change.entity)
-  );
+function findEntry(entries, entity) {
+  for (let index = 0; index < entries.length; index += 1) {
+    if (entries[index]?.entity === entity) return index;
+  }
+  return -1;
 }
-function propagateTransforms(world, _hierarchy) {
-  let cache = CACHE.get(world);
-  if (cache === void 0) {
-    cache = buildCache(world, createWorldProjection2(world, { components: [Transform, ChildOf] }));
-    CACHE.set(world, cache);
-    const initial = new Set(cache.entities);
-    const published2 = /* @__PURE__ */ new Set();
-    for (const entity of initial) {
-      const result = deriveEntity(world, entity, cache, initial, /* @__PURE__ */ new Set(), published2);
-      if (!result.ok) return result;
-    }
-    if (!drainPublishedChanges(cache, published2)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
-    }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
-  }
-  const evidence = cache.projection.poll();
-  if (evidence.status === "rebuild") {
-    cache = buildCache(world, cache.projection);
-    CACHE.set(world, cache);
-    const all = new Set(cache.entities);
-    const published2 = /* @__PURE__ */ new Set();
-    for (const entity of all) {
-      const result = deriveEntity(world, entity, cache, all, /* @__PURE__ */ new Set(), published2);
-      if (!result.ok) return result;
-    }
-    if (!drainPublishedChanges(cache, published2)) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+function resolveEntry(index, entries, world, output, scratch) {
+  const entry = entries[index];
+  if (entry === void 0 || entry.state === 2) return ok5(void 0);
+  if (entry.state === 1) {
+    const cycleParent = entry.parent ?? entry.entity;
+    const cycleStart = scratch.hierarchyPath.indexOf(index);
+    const start = cycleStart < 0 ? 0 : cycleStart;
+    for (let pathIndex = start; pathIndex < scratch.hierarchyPath.length; pathIndex += 1) {
+      const cycleEntry = entries[scratch.hierarchyPath[pathIndex] ?? -1];
+      if (cycleEntry !== void 0) cycleEntry.parent = void 0;
     }
-    cache.result = hierarchyError(cache.hierarchy);
-    return cache.result;
-  }
-  if (evidence.changes.length === 0) return cache.result;
-  const transformSeeds = /* @__PURE__ */ new Set();
-  let rebuild = false;
-  for (const change of evidence.changes) {
-    if (change.kind === "entity-removed" || change.kind === "component-added" || change.kind === "component-removed") {
-      rebuild = true;
-      break;
-    }
-    if (change.kind !== "component-changed") continue;
-    if (change.component === ChildOf) {
-      rebuild = true;
-      break;
+    return err5(
+      new SceneError({
+        code: "hierarchy-cycle",
+        expected: "a parent-before-child Transform hierarchy",
+        hint: "repair the ChildOf cycle and retry TransformPropagation",
+        detail: { entity: entry.entity, parent: cycleParent }
+      })
+    );
+  }
+  entry.state = 1;
+  scratch.hierarchyPath.push(index);
+  let parentIndex = entry.parent === void 0 ? -1 : findEntry(entries, entry.parent);
+  let failure;
+  if (entry.parent !== void 0 && parentIndex < 0) {
+    const local = world.get(entry.parent, Transform);
+    const global = world.get(entry.parent, GlobalTransform);
+    if (!local.ok || !global.ok) {
+      failure = new SceneError({
+        code: "hierarchy-broken",
+        expected: "each ChildOf parent to carry Transform and GlobalTransform",
+        hint: "repair the missing parent pair before retrying propagation",
+        detail: { entity: entry.entity, parent: entry.parent }
+      });
+      entry.parent = void 0;
+      parentIndex = -1;
+    } else {
+      const relation = world.get(entry.parent, ChildOf);
+      entries.push({
+        entity: entry.parent,
+        parent: relation.ok && relation.value.parent !== null ? relation.value.parent : void 0,
+        position: new Float32Array(local.value.pos),
+        rotation: new Float32Array(local.value.quat),
+        scale: new Float32Array(local.value.scale),
+        world: mat4.create(),
+        state: 0
+      });
+      parentIndex = entries.length - 1;
     }
-    if (change.component === Transform) transformSeeds.add(change.entity);
-  }
-  if (rebuild) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
-  }
-  const changed = /* @__PURE__ */ new Set();
-  for (const entity of transformSeeds) {
-    const current = world.get(entity, Transform);
-    if (!current.ok) {
-      CACHE.delete(world);
-      return propagateTransforms(world);
+  }
+  if (parentIndex >= 0) {
+    const parentResult = resolveEntry(parentIndex, entries, world, output, scratch);
+    if (!parentResult.ok) failure = parentResult.error;
+    parentIndex = entry.parent === void 0 ? -1 : findEntry(entries, entry.parent);
+    if (parentIndex >= 0 && entries[parentIndex]?.state !== 2) parentIndex = -1;
+  }
+  composeColumns(entry.position, entry.rotation, entry.scale, scratch.local, scratch);
+  if (parentIndex >= 0) {
+    const parent = entries[parentIndex];
+    if (parent !== void 0) mat4.multiply(entry.world, parent.world, scratch.local);
+  } else {
+    entry.world.set(scratch.local);
+  }
+  const write = writeWorld(world, output, entry.entity, entry.world);
+  if (!write.ok) {
+    scratch.hierarchyPath.pop();
+    return write;
+  }
+  entry.state = 2;
+  scratch.hierarchyPath.pop();
+  return failure === void 0 ? ok5(void 0) : err5(failure);
+}
+function propagateHierarchy(world, scratch) {
+  const query = scratch.hierarchyQuery;
+  const output = scratch.outputQuery;
+  if (query === void 0 || output === void 0) {
+    return err5(
+      new SceneError({
+        code: "hierarchy-broken",
+        expected: "paired Transform and GlobalTransform query access",
+        hint: "register the scene components before running TransformPropagation"
+      })
+    );
+  }
+  const entries = [];
+  for (const row of query) {
+    if (findEntry(entries, row.entity) >= 0) continue;
+    const local = row.get(Transform);
+    const parentValue = row.get(ChildOf).parent;
+    const parent = parentValue === null ? void 0 : parentValue;
+    entries.push({
+      entity: row.entity,
+      parent,
+      position: new Float32Array(local.pos),
+      rotation: new Float32Array(local.quat),
+      scale: new Float32Array(local.scale),
+      world: mat4.create(),
+      state: 0
+    });
+  }
+  scratch.hierarchyPath.length = 0;
+  let firstError;
+  for (let index = 0; index < entries.length; index += 1) {
+    const result = resolveEntry(index, entries, world, output, scratch);
+    if (!result.ok) {
+      const currentEntity = Number(result.error.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+      if (firstError === void 0) {
+        firstError = result.error;
+      } else {
+        const firstEntity = Number(firstError.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+        if (currentEntity < firstEntity || currentEntity === firstEntity && result.error.code.localeCompare(firstError.code) < 0) {
+          firstError = result.error;
+        }
+      }
     }
-    const next = copyState(current.value);
-    if (!sameState(cache.locals.get(entity), next)) changed.add(entity);
-    cache.locals.set(entity, next);
-  }
-  if (changed.size === 0) return cache.result;
-  const affected = descendants(cache.childrenOf, changed);
-  const published = /* @__PURE__ */ new Set();
-  for (const entity of affected) cache.derived.delete(entity);
-  for (const entity of affected) {
-    const result = deriveEntity(world, entity, cache, affected, /* @__PURE__ */ new Set(), published);
-    if (!result.ok) return result;
-  }
-  if (!drainPublishedChanges(cache, published)) {
-    CACHE.delete(world);
-    return propagateTransforms(world);
-  }
-  cache.result = hierarchyError(cache.hierarchy);
-  return cache.result;
+  }
+  return firstError === void 0 ? ok5(void 0) : err5(firstError);
+}
+function propagateTransforms(world) {
+  const scratch = scratchFor(world);
+  const pairs = validateTransformPairs(world, scratch);
+  if (!pairs.ok) return pairs;
+  const flat = propagateFlat(scratch);
+  if (!flat.ok) return flat;
+  return propagateHierarchy(world, scratch);
 }
 var PropagateTransforms = defineSystem({
   name: PROPAGATE_TRANSFORMS_SYSTEM,
@@ -1469,7 +1596,7 @@ function registerPropagateTransforms(world, options = {}) {
         world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
         world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
         REGISTRATION_LEASES.delete(world);
-        CACHE.delete(world);
+        SCRATCH.delete(world);
       }
     };
   }
@@ -1486,23 +1613,31 @@ function registerPropagateTransforms(world, options = {}) {
     ]).unwrap();
   }
   world.addSystems(FixedUpdate, TransformFixedSet, [PropagateTransformsFixed]).unwrap();
-  const lease = { refs: 1 };
-  REGISTRATION_LEASES.set(world, lease);
+  REGISTRATION_LEASES.set(world, { refs: 1 });
   let active = true;
   return () => {
     if (!active) return;
     active = false;
+    const lease = REGISTRATION_LEASES.get(world);
+    if (lease === void 0) return;
     lease.refs -= 1;
     if (lease.refs !== 0) return;
     world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
     world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
     REGISTRATION_LEASES.delete(world);
-    CACHE.delete(world);
+    SCRATCH.delete(world);
   };
 }
 
 // src/plugin.ts
-var SCENE_COMPONENTS = [ChildOf, Children, MorphWeights, Name, Transform];
+var SCENE_COMPONENTS = [
+  ChildOf,
+  Children,
+  MorphWeights,
+  Name,
+  Transform,
+  GlobalTransform
+];
 function registerSceneComponents(world) {
   const leases = SCENE_COMPONENTS.map((component) => world.components.register(component).unwrap());
   return () => {
@@ -1519,10 +1654,115 @@ function scenePlugin() {
     }
   };
 }
+
+// src/systems/hierarchy-projection.ts
+import { Entity } from "@forgeax/engine-ecs";
+var HIERARCHY_PROJECTION_CACHE = /* @__PURE__ */ new WeakMap();
+function createChildOfChangeQuery(world) {
+  const result = world.query({ changed: [ChildOf] });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+function drainChanges(query) {
+  let changed = false;
+  for (const span of query.spans().unwrap()) changed ||= span.length > 0;
+  return changed;
+}
+function diagnostic(code, entity, parent) {
+  if (code === "hierarchy-cycle") {
+    return {
+      code,
+      expected: "ChildOf parent edges form an acyclic live hierarchy",
+      hint: "remove one ChildOf edge from the reported cycle, then re-run the extract",
+      detail: { entity, parent }
+    };
+  }
+  return {
+    code,
+    expected: "ChildOf.parent references a live entity in the same World",
+    hint: "remove the stale ChildOf component or restore the referenced parent in this World",
+    detail: { entity, parent }
+  };
+}
+function projectHierarchy(world) {
+  const cached = HIERARCHY_PROJECTION_CACHE.get(world);
+  if (cached !== void 0 && cached.structureEpoch === world.getStructureEpoch() && !drainChanges(cached.childOfChanges)) {
+    return cached.snapshot;
+  }
+  const liveEntities = /* @__PURE__ */ new Set();
+  const authoredParents = /* @__PURE__ */ new Map();
+  const query = world.query({ read: [Entity], optional: [ChildOf] });
+  if (query.ok) {
+    for (const row of query.value) {
+      liveEntities.add(row.entity);
+      const parent = row.get(ChildOf)?.parent;
+      if (parent !== void 0 && parent !== null) authoredParents.set(row.entity, parent);
+    }
+  }
+  const parentOf = /* @__PURE__ */ new Map();
+  const diagnostics = [];
+  for (const [entity, parent] of authoredParents) {
+    if (liveEntities.has(parent)) {
+      parentOf.set(entity, parent);
+    } else {
+      diagnostics.push(diagnostic("hierarchy-broken", entity, parent));
+    }
+  }
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const cycleMembers = /* @__PURE__ */ new Set();
+  const visit = (entity) => {
+    const currentState = state.get(entity) ?? 0;
+    if (currentState === 2) return;
+    if (currentState === 1) {
+      const cycleStart = stack.indexOf(entity);
+      for (let index = cycleStart; index >= 0 && index < stack.length; index++) {
+        const member = stack[index];
+        if (member !== void 0) cycleMembers.add(member);
+      }
+      return;
+    }
+    state.set(entity, 1);
+    stack.push(entity);
+    const parent = parentOf.get(entity);
+    if (parent !== void 0) visit(parent);
+    stack.pop();
+    state.set(entity, 2);
+  };
+  for (const entity of liveEntities) visit(entity);
+  for (const entity of cycleMembers) {
+    const parent = authoredParents.get(entity);
+    if (parent !== void 0) diagnostics.push(diagnostic("hierarchy-cycle", entity, parent));
+    parentOf.delete(entity);
+  }
+  diagnostics.sort((left, right) => {
+    const entityDelta = left.detail.entity - right.detail.entity;
+    if (entityDelta !== 0) return entityDelta;
+    return left.code.localeCompare(right.code);
+  });
+  const stableParentOf = new Map(parentOf);
+  const stableDiagnostics = Object.freeze(diagnostics.slice());
+  const snapshot = {
+    parentOf: stableParentOf,
+    diagnostics: stableDiagnostics,
+    getParent(entity) {
+      return stableParentOf.get(entity);
+    }
+  };
+  const childOfChanges = createChildOfChangeQuery(world);
+  drainChanges(childOfChanges);
+  HIERARCHY_PROJECTION_CACHE.set(world, {
+    structureEpoch: world.getStructureEpoch(),
+    childOfChanges,
+    snapshot
+  });
+  return snapshot;
+}
 export {
   ChildOf,
   Children,
   ComponentNotDefinedError,
+  GlobalTransform,
   MorphWeights,
   Name,
   PROPAGATE_TRANSFORMS_SYSTEM,
@@ -1535,8 +1775,11 @@ export {
   projectHierarchy,
   propagateTransforms,
   registerPropagateTransforms,
+  resolveSceneEntity,
   sceneAssetContribution,
+  sceneEntity,
   scenePlugin,
+  validateSceneBindings,
   worldApplyMountOverride,
   worldBuildSceneEntityComponentDatas,
   worldDespawnDescendants,
@@ -1556,6 +1799,7 @@ export {
   worldRemoveSceneOverride,
   worldResolveMountSource,
   worldResolveSceneAsset,
+  worldResolveSceneEntity,
   worldResolveSceneInstanceStatePayload,
   worldSetSceneAssetResolver,
   worldSetSceneOverride,