@forgeax/engine-scene 0.1.21 → 0.1.24

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,339 +1229,866 @@ 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 {
   defineSystem,
   defineSystemSet,
+  ENTITY_NULL_RAW as ENTITY_NULL_RAW2,
   FixedUpdate,
   Update
 } from "@forgeax/engine-ecs";
 import {
-  createWorldProjection as createWorldProjection2,
-  setDerivedComponent
-} from "@forgeax/engine-ecs/projection";
+  getDerivedWriter,
+  worldInternal
+} from "@forgeax/engine-ecs/internal";
 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 }
-    };
+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 propagationTrace;
+var hierarchyRootCursorAllocationCount = 0;
+function createHierarchyRootCursor() {
+  hierarchyRootCursorAllocationCount += 1;
+  return { bindingIndex: -1, row: -1 };
+}
+function countPropagation(name) {
+  const trace = propagationTrace;
+  if (trace !== void 0) trace[name] += 1;
+}
+var SCRATCH = /* @__PURE__ */ new WeakMap();
+var REGISTRATION_LEASES = /* @__PURE__ */ new WeakMap();
+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 ensureQueries(world, scratch) {
+  if (scratch.flatQuery !== void 0 && scratch.hierarchyQuery !== void 0 && scratch.transformQuery !== void 0 && scratch.hierarchyWriter !== void 0 && scratch.transformWriter !== 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 hierarchy = world.query({ read: [Transform, ChildOf], write: [GlobalTransform] });
+  const transform = world.query({ read: [Transform], write: [GlobalTransform] });
+  const missingGlobal = world.query({ with: [Transform], without: [GlobalTransform] });
+  const missingTransform = world.query({ with: [GlobalTransform], without: [Transform] });
+  if (!flatOutput.ok || !hierarchy.ok || !transform.ok || !missingGlobal.ok || !missingTransform.ok) {
+    return pairError(0, "valid Transform and GlobalTransform pair queries");
+  }
+  const hierarchyWriter = getDerivedWriter(hierarchy.value, GlobalTransform);
+  const transformWriter = getDerivedWriter(transform.value, GlobalTransform);
+  if (!hierarchyWriter.ok || !transformWriter.ok) {
+    return pairError(0, "dense Transform and ChildOf derived bindings");
+  }
+  scratch.flatQuery = flatOutput.value;
+  scratch.hierarchyQuery = hierarchy.value;
+  scratch.transformQuery = transform.value;
+  scratch.hierarchyWriter = hierarchyWriter.value;
+  scratch.transformWriter = transformWriter.value;
+  scratch.missingGlobalQuery = missingGlobal.value;
+  scratch.missingTransformQuery = missingTransform.value;
+  return ok5(void 0);
+}
+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");
   }
-  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 }
+  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 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(),
+    parent: mat4.create(),
+    candidate: mat4.create(),
+    hierarchyStackEntities: [],
+    hierarchyStackChildren: [],
+    hierarchyProbeEntities: [],
+    hierarchyCurrentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyParentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyChildCursor: { bindingIndex: -1, row: -1 },
+    hierarchyResidualCursor: { bindingIndex: -1, row: -1 },
+    hierarchyResidualParentCursor: { bindingIndex: -1, row: -1 },
+    hierarchyRootCursor: createHierarchyRootCursor(),
+    hierarchyStates: [],
+    hierarchyChanged: [],
+    hierarchyBindingTables: [],
+    hierarchyBindingRows: [],
+    flatChanged: [],
+    flatBindingTables: [],
+    flatBindingRows: [],
+    flatStructureEpoch: -1
   };
+  SCRATCH.set(world, created);
+  return created;
 }
-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;
+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 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;
   }
-  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);
+}
+function propagateFlat(world, scratch) {
+  const query = scratch.flatQuery;
+  if (query === void 0)
+    return err5(
+      new SceneError({
+        code: "hierarchy-broken",
+        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 world2 = span.mut(GlobalTransform).world;
+      composeFlatColumns(local.pos, local.quat, local.scale, world2, span.length);
+      bindingIndex += 1;
+    }
+  } catch (cause) {
+    const error = cause;
+    return err5(derivedWriteError(error, bindingIndex));
+  }
+  const transformWriter = scratch.transformWriter;
+  if (transformWriter === void 0) {
+    return pairError(0, "dense Transform and GlobalTransform derived bindings");
+  }
+  const transformBindings = transformWriter.bindings;
+  const structureEpoch = world[worldInternal].getStructureEpoch();
+  if (scratch.flatStructureEpoch === structureEpoch) return ok5(void 0);
+  ensureFlatBuffers(scratch, transformBindings);
+  resetFlatBuffers(scratch);
+  for (let bindingIndex2 = 0; bindingIndex2 < transformBindings.length; bindingIndex2 += 1) {
+    const binding = transformBindings[bindingIndex2];
+    const changed = scratch.flatChanged[bindingIndex2];
+    if (binding === void 0 || changed === void 0) continue;
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      const entity = binding.entities[row] ?? 0;
+      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, "parent");
+      if (parentRaw !== void 0 && parentRaw !== ENTITY_NULL_RAW2) continue;
+      countPropagation("flatStructuralRootRows");
+      composeBindingRow(binding, row, void 0, 0, scratch, changed);
     }
   }
-  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));
+  for (let bindingIndex2 = 0; bindingIndex2 < transformBindings.length; bindingIndex2 += 1) {
+    const changed = scratch.flatChanged[bindingIndex2];
+    if (changed === void 0) continue;
+    const published = transformWriter.publishChangedRows(bindingIndex2, changed);
+    if (!published.ok) return err5(derivedWriteError(published.error, bindingIndex2));
+  }
+  scratch.flatStructureEpoch = structureEpoch;
+  return ok5(void 0);
+}
+function transformColumns(binding) {
+  return binding.read;
+}
+function hierarchyColumns(binding) {
+  return binding.read;
+}
+function worldColumn(binding) {
+  return binding.write.world;
+}
+function hierarchyError(code, entity, parent, expected, hint) {
+  return new SceneError({ code, expected, hint, detail: { entity, parent } });
+}
+function writeCandidate(binding, row, candidate, changed) {
+  const worlds = worldColumn(binding);
+  const base = row * 16;
+  for (let index = 0; index < 16; index += 1) {
+    if (worlds[base + index] !== candidate[index]) {
+      worlds.set(candidate, base);
+      changed[row] = 1;
+      return;
     }
   }
-  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);
+}
+function composeBindingRow(binding, row, parentBinding, parentRow, scratch, changed) {
+  if ("parent" in binding.read) countPropagation("hierarchyRowsEvaluated");
+  const local = transformColumns(binding);
+  const offset = row * 3;
+  composeColumns(local.pos, local.quat, local.scale, scratch.local, scratch, offset, row * 4);
+  if (parentBinding === void 0) {
+    scratch.candidate.set(scratch.local);
+  } else {
+    const parentWorld = worldColumn(parentBinding);
+    const parentOffset = parentRow * 16;
+    for (let index = 0; index < 16; index += 1) {
+      scratch.parent[index] = parentWorld[parentOffset + index] ?? 0;
+    }
+    mat4.multiply(scratch.candidate, scratch.parent, scratch.local);
+  }
+  writeCandidate(binding, row, scratch.candidate, changed);
+}
+function ensureHierarchyBuffers(scratch, bindings) {
+  let same = scratch.hierarchyBindingTables.length === bindings.length;
+  if (same) {
+    for (let index = 0; index < bindings.length; index += 1) {
+      const binding = bindings[index];
+      if (binding === void 0 || scratch.hierarchyBindingTables[index] !== binding.tableId || scratch.hierarchyBindingRows[index] !== binding.rowCapacity) {
+        same = false;
+        break;
       }
-      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);
+  if (same) return;
+  scratch.hierarchyBindingTables = bindings.map((binding) => binding.tableId);
+  scratch.hierarchyBindingRows = bindings.map((binding) => binding.rowCapacity);
+  scratch.hierarchyStates = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+  scratch.hierarchyChanged = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+}
+function resetHierarchyBuffers(scratch) {
+  for (let index = 0; index < scratch.hierarchyStates.length; index += 1) {
+    scratch.hierarchyStates[index]?.fill(0);
+    scratch.hierarchyChanged[index]?.fill(0);
+  }
+}
+function ensureFlatBuffers(scratch, bindings) {
+  let same = scratch.flatBindingTables.length === bindings.length;
+  if (same) {
+    for (let index = 0; index < bindings.length; index += 1) {
+      const binding = bindings[index];
+      if (binding === void 0 || scratch.flatBindingTables[index] !== binding.tableId || scratch.flatBindingRows[index] !== binding.rowCapacity) {
+        same = false;
+        break;
+      }
+    }
+  }
+  if (same) return;
+  scratch.flatBindingTables = bindings.map((binding) => binding.tableId);
+  scratch.flatBindingRows = bindings.map((binding) => binding.rowCapacity);
+  scratch.flatChanged = bindings.map((binding) => new Uint8Array(binding.rowCapacity));
+}
+function resetFlatBuffers(scratch) {
+  for (const changed of scratch.flatChanged) changed.fill(0);
+}
+function derivedWriteError(cause, bindingIndex) {
+  return new SceneError({
+    code: "hierarchy-broken",
+    expected: "derived GlobalTransform range publication to succeed",
+    hint: cause.hint ?? "retry propagation on a healthy World",
+    detail: {
+      kind: "derived-write",
+      entity: 0,
+      parent: 0,
+      bindingIndex,
+      base: 0,
+      start: 0,
+      count: 0,
+      cause
     }
-  };
-  HIERARCHY_PROJECTION_CACHE.set(world, {
-    changes,
-    snapshot
   });
-  return snapshot;
 }
-
-// src/systems/propagate-transforms.ts
-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 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 findHierarchyLocation(writer, bindings, entity, cursor) {
+  countPropagation("hierarchyEntityLookups");
+  if (!writer.locateEntity(entity, cursor)) return void 0;
+  return bindings[cursor.bindingIndex];
 }
-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;
+function findTransformLocation(writer, bindings, entity, cursor) {
+  countPropagation("hierarchyEntityLookups");
+  if (!writer.locateEntity(entity, cursor)) return void 0;
+  return bindings[cursor.bindingIndex];
+}
+function countPublishedRows(changed) {
+  const trace = propagationTrace;
+  if (trace === void 0) return;
+  let runOpen = false;
+  for (let row = 0; row < changed.length; row += 1) {
+    if ((changed[row] ?? 0) !== 0) {
+      trace.hierarchyPublishedRows += 1;
+      if (!runOpen) {
+        trace.hierarchyPublishedRuns += 1;
+        runOpen = true;
+      }
+    } else {
+      runOpen = false;
+    }
   }
-  return true;
 }
-function sameState(left, right) {
-  return left !== void 0 && sameArray(left.pos, right.pos) && sameArray(left.quat, right.quat) && sameArray(left.scale, right.scale);
+function noteHierarchyError(current, next) {
+  if (current === void 0) return next;
+  const currentEntity = Number(current.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+  const nextEntity = Number(next.detail?.entity ?? Number.MAX_SAFE_INTEGER);
+  return nextEntity < currentEntity || nextEntity === currentEntity && next.code.localeCompare(current.code) < 0 ? next : current;
 }
-function compose(state, out) {
-  mat4.compose(out, state.pos, state.quat, state.scale);
+function composeLocalHierarchyEntity(writer, bindings, entity, scratch, changed) {
+  const cursor = scratch.hierarchyCurrentCursor;
+  const binding = findHierarchyLocation(writer, bindings, entity, cursor);
+  if (binding === void 0) return false;
+  composeBindingRow(
+    binding,
+    cursor.row,
+    void 0,
+    0,
+    scratch,
+    changed[cursor.bindingIndex]
+  );
+  const states = scratch.hierarchyStates[cursor.bindingIndex];
+  if (states !== void 0) states[cursor.row] = 3;
+  return true;
 }
-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);
+function handleActiveCycle(repeated, stackEntities, stackChildren, writer, bindings, scratch, changed, report) {
+  let cycleStart = -1;
+  for (let index = 0; index < stackEntities.length; index += 1) {
+    if (stackEntities[index] === repeated) {
+      cycleStart = index;
+      break;
+    }
+  }
+  if (cycleStart < 0) return;
+  const repeatedCursor = { bindingIndex: -1, row: -1 };
+  const repeatedBinding = findHierarchyLocation(writer, bindings, repeated, repeatedCursor);
+  const repeatedParent = repeatedBinding === void 0 ? repeated : hierarchyColumns(repeatedBinding).parent[repeatedCursor.row] ?? ENTITY_NULL_RAW2;
+  report(
+    hierarchyError(
+      "hierarchy-cycle",
+      repeated,
+      repeatedParent,
+      "a parent-before-child Transform hierarchy",
+      "repair the ChildOf cycle and retry TransformPropagation"
+    )
+  );
+  for (let index = cycleStart; index < stackEntities.length; index += 1) {
+    const cycleEntity = stackEntities[index];
+    if (cycleEntity === void 0) continue;
+    composeLocalHierarchyEntity(writer, bindings, cycleEntity, scratch, changed);
+    stackChildren[index] = 0;
   }
-  return childrenOf;
 }
-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 walkChildren(world, root, writer, bindings, transformWriter, transformBindings, scratch, report, allowCompletedRoot) {
+  countPropagation("hierarchyRootInvocations");
+  const stackEntities = scratch.hierarchyStackEntities;
+  const stackChildren = scratch.hierarchyStackChildren;
+  stackEntities.length = 0;
+  stackChildren.length = 0;
+  if (allowCompletedRoot) {
+    const rootCursor = scratch.hierarchyRootCursor;
+    const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
+    if (rootBinding !== void 0) {
+      const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
+      if (state === 4) return;
+    }
+  } else {
+    const rootCursor = scratch.hierarchyRootCursor;
+    countPropagation("hierarchyRootCursorReuses");
+    const rootBinding = findHierarchyLocation(writer, bindings, root, rootCursor);
+    if (rootBinding !== void 0) {
+      const state = scratch.hierarchyStates[rootCursor.bindingIndex]?.[rootCursor.row] ?? 0;
+      if (state !== 0) return;
+    }
+  }
+  stackEntities.push(root);
+  stackChildren.push(-1);
+  const currentCursor = scratch.hierarchyCurrentCursor;
+  const parentCursor = scratch.hierarchyParentCursor;
+  const childCursor = scratch.hierarchyChildCursor;
+  while (stackEntities.length > 0) {
+    const top = stackEntities.length - 1;
+    const current = stackEntities[top];
+    if (current === void 0) {
+      stackEntities.pop();
+      stackChildren.pop();
+      continue;
+    }
+    const hierarchyBinding = findHierarchyLocation(writer, bindings, current, currentCursor);
+    const nextChild = stackChildren[top] ?? -1;
+    if (nextChild < 0) {
+      if (hierarchyBinding !== void 0) {
+        const state = scratch.hierarchyStates[currentCursor.bindingIndex]?.[currentCursor.row] ?? 0;
+        if (state === 0) {
+          const states = scratch.hierarchyStates[currentCursor.bindingIndex];
+          if (states !== void 0) states[currentCursor.row] = 1;
+          const parentRaw = hierarchyColumns(hierarchyBinding).parent[currentCursor.row] ?? ENTITY_NULL_RAW2;
+          let completed = false;
+          if (parentRaw === ENTITY_NULL_RAW2) {
+            composeBindingRow(
+              hierarchyBinding,
+              currentCursor.row,
+              void 0,
+              0,
+              scratch,
+              scratch.hierarchyChanged[currentCursor.bindingIndex]
+            );
+            completed = true;
+          } else {
+            const parent = parentRaw;
+            const parentBinding = findTransformLocation(
+              transformWriter,
+              transformBindings,
+              parent,
+              parentCursor
+            );
+            const parentHierarchy = findHierarchyLocation(writer, bindings, parent, childCursor);
+            if (parentBinding === void 0) {
+              report(
+                hierarchyError(
+                  "hierarchy-broken",
+                  current,
+                  parent,
+                  "each ChildOf parent to carry Transform and GlobalTransform",
+                  "repair the missing parent pair before retrying propagation"
+                )
+              );
+              composeBindingRow(
+                hierarchyBinding,
+                currentCursor.row,
+                void 0,
+                0,
+                scratch,
+                scratch.hierarchyChanged[currentCursor.bindingIndex]
+              );
+              completed = true;
+            } else if (parentHierarchy !== void 0) {
+              const parentState = scratch.hierarchyStates[childCursor.bindingIndex]?.[childCursor.row] ?? 0;
+              if (parentState === 1) {
+                handleActiveCycle(
+                  parent,
+                  stackEntities,
+                  stackChildren,
+                  writer,
+                  bindings,
+                  scratch,
+                  scratch.hierarchyChanged,
+                  report
+                );
+                completed = true;
+              } else if (parentState === 0) {
+                report(
+                  hierarchyError(
+                    "hierarchy-broken",
+                    current,
+                    parent,
+                    "Children to enumerate every parent-before-child edge",
+                    "repair the Children mirror and retry TransformPropagation"
+                  )
+                );
+                composeBindingRow(
+                  hierarchyBinding,
+                  currentCursor.row,
+                  void 0,
+                  0,
+                  scratch,
+                  scratch.hierarchyChanged[currentCursor.bindingIndex]
+                );
+                completed = true;
+              } else {
+                composeBindingRow(
+                  hierarchyBinding,
+                  currentCursor.row,
+                  parentBinding,
+                  parentCursor.row,
+                  scratch,
+                  scratch.hierarchyChanged[currentCursor.bindingIndex]
+                );
+                completed = true;
+              }
+            } else {
+              composeBindingRow(
+                hierarchyBinding,
+                currentCursor.row,
+                parentBinding,
+                parentCursor.row,
+                scratch,
+                scratch.hierarchyChanged[currentCursor.bindingIndex]
+              );
+              completed = true;
+            }
+          }
+          if (completed && states !== void 0 && states[currentCursor.row] === 1) {
+            states[currentCursor.row] = 2;
+          }
+        }
+      }
+      stackChildren[top] = 0;
+      continue;
+    }
+    const childrenLength = world[worldInternal].getArrayLength(current, Children, "entities") ?? 0;
+    if (nextChild >= childrenLength) {
+      stackEntities.pop();
+      stackChildren.pop();
+      if (allowCompletedRoot) {
+        const completedCursor = scratch.hierarchyResidualCursor;
+        const completedBinding = findHierarchyLocation(writer, bindings, current, completedCursor);
+        const completedStates = completedBinding === void 0 ? void 0 : scratch.hierarchyStates[completedCursor.bindingIndex];
+        if (completedStates !== void 0 && completedStates[completedCursor.row] === 3) {
+          completedStates[completedCursor.row] = 4;
+        }
+      }
+      continue;
+    }
+    stackChildren[top] = nextChild + 1;
+    countPropagation("hierarchyEdgesVisited");
+    const childRaw = world[worldInternal].getArrayElement(current, Children, "entities", nextChild);
+    if (childRaw === void 0 || childRaw === ENTITY_NULL_RAW2) {
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          current,
+          current,
+          "Children.entities to contain live child handles",
+          "repair the Children mirror and retry TransformPropagation"
+        )
+      );
+      continue;
+    }
+    const child = childRaw;
+    const childBinding = findHierarchyLocation(writer, bindings, child, childCursor);
+    if (childBinding === void 0) {
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          child,
+          current,
+          "each Children entry to carry Transform, GlobalTransform, and ChildOf",
+          "repair the child component pair before retrying propagation"
+        )
+      );
+      continue;
+    }
+    const childParent = hierarchyColumns(childBinding).parent[childCursor.row] ?? ENTITY_NULL_RAW2;
+    const childState = scratch.hierarchyStates[childCursor.bindingIndex]?.[childCursor.row] ?? 0;
+    if (childParent !== current) {
+      if (childState === 0) continue;
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          child,
+          current,
+          "Children and ChildOf to describe the same parent",
+          "repair the relationship mirror and retry TransformPropagation"
+        )
+      );
+      continue;
+    }
+    if (childState === 1) {
+      handleActiveCycle(
+        child,
+        stackEntities,
+        stackChildren,
+        writer,
+        bindings,
+        scratch,
+        scratch.hierarchyChanged,
+        report
+      );
+    } else if (childState === 0) {
+      stackEntities.push(child);
+      stackChildren.push(-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 fallbackResidualPath(world, path, writer, bindings, transformWriter, transformBindings, scratch, report) {
+  for (const entity of path) {
+    composeLocalHierarchyEntity(writer, bindings, entity, scratch, scratch.hierarchyChanged);
+  }
+  for (const entity of path) {
+    walkChildren(
+      world,
+      entity,
+      writer,
+      bindings,
+      transformWriter,
+      transformBindings,
+      scratch,
+      report,
+      true
+    );
+  }
 }
-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 resolveResidualPath(world, entity, writer, bindings, transformWriter, transformBindings, scratch, report) {
+  const path = scratch.hierarchyProbeEntities;
+  path.length = 0;
+  const cursor = scratch.hierarchyResidualCursor;
+  const parentTransformCursor = scratch.hierarchyParentCursor;
+  const parentHierarchyCursor = scratch.hierarchyResidualParentCursor;
+  let current = entity;
+  while (true) {
+    countPropagation("hierarchyResidualParentProbes");
+    const binding = findHierarchyLocation(writer, bindings, current, cursor);
+    if (binding === void 0) break;
+    const states = scratch.hierarchyStates[cursor.bindingIndex];
+    const state = states?.[cursor.row] ?? 0;
+    if (state !== 0) {
+      const columns = hierarchyColumns(binding);
+      const parentRaw2 = columns.parent[cursor.row] ?? ENTITY_NULL_RAW2;
+      report(
+        hierarchyError(
+          "hierarchy-cycle",
+          current,
+          parentRaw2 === ENTITY_NULL_RAW2 ? current : parentRaw2,
+          "a parent-before-child Transform hierarchy",
+          "repair the ChildOf cycle and retry TransformPropagation"
+        )
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report
+      );
+      return;
+    }
+    if (states !== void 0) states[cursor.row] = 1;
+    path.push(current);
+    const parentRaw = hierarchyColumns(binding).parent[cursor.row] ?? ENTITY_NULL_RAW2;
+    if (parentRaw === ENTITY_NULL_RAW2) {
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          current,
+          current,
+          "Children to enumerate every parent-before-child edge",
+          "repair the Children mirror and retry TransformPropagation"
+        )
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report
+      );
+      return;
+    }
+    const parent = parentRaw;
+    const parentTransform = findTransformLocation(
+      transformWriter,
+      transformBindings,
+      parent,
+      parentTransformCursor
+    );
+    const parentHierarchy = findHierarchyLocation(writer, bindings, parent, parentHierarchyCursor);
+    if (parentHierarchy === void 0) {
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          current,
+          parent,
+          parentTransform === void 0 ? "each ChildOf parent to carry Transform and GlobalTransform" : "Children to enumerate every parent-before-child edge",
+          parentTransform === void 0 ? "repair the missing parent pair before retrying propagation" : "repair the Children mirror and retry TransformPropagation"
+        )
+      );
+      fallbackResidualPath(
+        world,
+        path,
+        writer,
+        bindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report
+      );
+      return;
     }
+    const parentState = scratch.hierarchyStates[parentHierarchyCursor.bindingIndex]?.[parentHierarchyCursor.row] ?? 0;
+    if (parentState === 0) {
+      current = parent;
+      continue;
+    }
+    if (parentState === 1) {
+      report(
+        hierarchyError(
+          "hierarchy-cycle",
+          parent,
+          current,
+          "a parent-before-child Transform hierarchy",
+          "repair the ChildOf cycle and retry TransformPropagation"
+        )
+      );
+    } else {
+      report(
+        hierarchyError(
+          "hierarchy-broken",
+          current,
+          parent,
+          "Children to enumerate every parent-before-child edge",
+          "repair the Children mirror and retry TransformPropagation"
+        )
+      );
+    }
+    fallbackResidualPath(
+      world,
+      path,
+      writer,
+      bindings,
+      transformWriter,
+      transformBindings,
+      scratch,
+      report
+    );
+    return;
   }
-  return {
-    projection,
-    hierarchy,
-    parentOf: hierarchy.parentOf,
-    childrenOf: indexChildren(hierarchy),
-    entities,
-    locals,
-    derived: /* @__PURE__ */ new Map(),
-    result: ok4(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 propagateHierarchy(world, scratch) {
+  const hierarchyWriter = scratch.hierarchyWriter;
+  const transformWriter = scratch.transformWriter;
+  if (hierarchyWriter === void 0 || transformWriter === 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: "paired Transform and GlobalTransform derived bindings",
+        hint: "register the scene components before running TransformPropagation"
       })
     );
   }
-  cache.derived.set(entity, resolved);
-  published.add(entity);
-  visiting.delete(entity);
-  return ok4(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 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);
-    }
-    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;
+  const hierarchyBindings = hierarchyWriter.bindings;
+  const transformBindings = transformWriter.bindings;
+  if (hierarchyBindings.length === 0) {
+    scratch.hierarchyBindingTables.length = 0;
+    scratch.hierarchyBindingRows.length = 0;
+    scratch.hierarchyStates.length = 0;
+    scratch.hierarchyChanged.length = 0;
+    return ok5(void 0);
+  }
+  ensureHierarchyBuffers(scratch, hierarchyBindings);
+  resetHierarchyBuffers(scratch);
+  let firstError;
+  const report = (error) => {
+    firstError = noteHierarchyError(firstError, error);
+  };
+  for (const binding of transformBindings) {
+    const entities = binding.entities;
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      const entity = entities[row] ?? 0;
+      const parentRaw = world[worldInternal].getFieldValue(entity, ChildOf, "parent");
+      if (parentRaw === void 0 || parentRaw === ENTITY_NULL_RAW2) {
+        walkChildren(
+          world,
+          entity,
+          hierarchyWriter,
+          hierarchyBindings,
+          transformWriter,
+          transformBindings,
+          scratch,
+          report,
+          false
+        );
+      }
     }
-    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);
+  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+    const binding = hierarchyBindings[bindingIndex];
+    if (binding === void 0) continue;
+    const entities = binding.entities;
+    const states = scratch.hierarchyStates[bindingIndex];
+    for (let row = 0; row < binding.rowCapacity; row += 1) {
+      if ((states?.[row] ?? 0) !== 0) continue;
+      const entity = entities[row] ?? 0;
+      resolveResidualPath(
+        world,
+        entity,
+        hierarchyWriter,
+        hierarchyBindings,
+        transformWriter,
+        transformBindings,
+        scratch,
+        report
+      );
     }
-    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);
+  for (let bindingIndex = 0; bindingIndex < hierarchyBindings.length; bindingIndex += 1) {
+    const changed = scratch.hierarchyChanged[bindingIndex];
+    if (changed === void 0) continue;
+    countPublishedRows(changed);
+    const published = hierarchyWriter.publishChangedRows(bindingIndex, changed);
+    if (!published.ok) {
+      const cause = published.error;
+      report(derivedWriteError(cause, bindingIndex));
+    }
   }
-  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(world, scratch);
+  if (!flat.ok) return flat;
+  return propagateHierarchy(world, scratch);
 }
 var PropagateTransforms = defineSystem({
   name: PROPAGATE_TRANSFORMS_SYSTEM,
@@ -1469,7 +2116,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 +2133,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 +2174,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 +2295,11 @@ export {
   projectHierarchy,
   propagateTransforms,
   registerPropagateTransforms,
+  resolveSceneEntity,
   sceneAssetContribution,
+  sceneEntity,
   scenePlugin,
+  validateSceneBindings,
   worldApplyMountOverride,
   worldBuildSceneEntityComponentDatas,
   worldDespawnDescendants,
@@ -1556,6 +2319,7 @@ export {
   worldRemoveSceneOverride,
   worldResolveMountSource,
   worldResolveSceneAsset,
+  worldResolveSceneEntity,
   worldResolveSceneInstanceStatePayload,
   worldSetSceneAssetResolver,
   worldSetSceneOverride,