@forgeax/engine-scene 0.1.23 → 0.1.24

package/dist/index.mjs

@@ -1234,15 +1234,30 @@ function sceneTopoSort(nodes) {
 import {
   defineSystem,
   defineSystemSet,
+  ENTITY_NULL_RAW as ENTITY_NULL_RAW2,
   FixedUpdate,
   Update
 } from "@forgeax/engine-ecs";
+import {
+  getDerivedWriter,
+  worldInternal
+} from "@forgeax/engine-ecs/internal";
 import { mat4 } from "@forgeax/engine-math";
 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) {
@@ -1256,7 +1271,7 @@ function pairError(entity, expected) {
   );
 }
 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) {
+  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({
@@ -1265,16 +1280,23 @@ function ensureQueries(world, scratch) {
     without: [ChildOf],
     changed: [Transform]
   });
-  const output = world.query({ write: [GlobalTransform] });
-  const hierarchy = world.query({ read: [Transform, ChildOf] });
+  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 || !output.ok || !hierarchy.ok || !missingGlobal.ok || !missingTransform.ok) {
+  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.outputQuery = output.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);
@@ -1303,7 +1325,25 @@ function scratchFor(world) {
     rotation: new Float32Array(4),
     scale: new Float32Array(3),
     local: mat4.create(),
-    hierarchyPath: []
+    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;
@@ -1363,40 +1403,7 @@ function composeFlatColumns(positions, rotations, scales, worlds, count) {
     worlds[world + 15] = 1;
   }
 }
-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;
-    }
-  }
-  if (!changed) return ok5(void 0);
-  row.mut(GlobalTransform).world.set(value);
-  return ok5(void 0);
-}
-function propagateFlat(scratch) {
+function propagateFlat(world, scratch) {
   const query = scratch.flatQuery;
   if (query === void 0)
     return err5(
@@ -1412,161 +1419,674 @@ function propagateFlat(scratch) {
   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);
+      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(
-      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
-        }
-      })
-    );
+    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);
+    }
+  }
+  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 findEntry(entries, entity) {
-  for (let index = 0; index < entries.length; index += 1) {
-    if (entries[index]?.entity === entity) return index;
+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;
+    }
   }
-  return -1;
 }
-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;
+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;
     }
-    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 }
-      })
-    );
+    mat4.multiply(scratch.candidate, scratch.parent, scratch.local);
   }
-  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;
+  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;
+      }
+    }
+  }
+  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
+    }
+  });
+}
+function findHierarchyLocation(writer, bindings, entity, cursor) {
+  countPropagation("hierarchyEntityLookups");
+  if (!writer.locateEntity(entity, cursor)) return void 0;
+  return bindings[cursor.bindingIndex];
+}
+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 {
-      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;
+      runOpen = false;
+    }
+  }
+}
+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 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 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 (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;
+  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;
   }
-  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);
+}
+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 {
-    entry.world.set(scratch.local);
+    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;
+    }
   }
-  const write = writeWorld(world, output, entry.entity, entry.world);
-  if (!write.ok) {
-    scratch.hierarchyPath.pop();
-    return write;
+  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);
+    }
+  }
+}
+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 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;
   }
-  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) {
+  const hierarchyWriter = scratch.hierarchyWriter;
+  const transformWriter = scratch.transformWriter;
+  if (hierarchyWriter === void 0 || transformWriter === void 0) {
     return err5(
       new SceneError({
         code: "hierarchy-broken",
-        expected: "paired Transform and GlobalTransform query access",
+        expected: "paired Transform and GlobalTransform derived bindings",
         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
-    });
+  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);
   }
-  scratch.hierarchyPath.length = 0;
+  ensureHierarchyBuffers(scratch, hierarchyBindings);
+  resetHierarchyBuffers(scratch);
   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 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
+        );
       }
     }
   }
+  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
+      );
+    }
+  }
+  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));
+    }
+  }
   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);
+  const flat = propagateFlat(world, scratch);
   if (!flat.ok) return flat;
   return propagateHierarchy(world, scratch);
 }