@forgeax/engine-scene 0.1.23 → 0.1.24

package/README.md

@@ -19,8 +19,29 @@ await context.fiber.restart();
 ```
 
 `scenePlugin()` is a native Cordis plugin. Its Fiber installs hierarchy
-propagation and removes it when the realm unloads. Read failures as
-`SceneError` and branch on `error.code`; do not parse messages.
+propagation and removes it when the realm unloads. The direct
+`propagateTransforms(world)` entry point returns `Result<void, SceneError>`;
+branch on `error.code` and repair a diagnosable stale edge, mirror mismatch, or
+cycle through `World.set`/`World.removeComponent` (or the owning structural
+command) before retrying while the World is healthy.
+
+When the plugin runs from the scheduled path, `world.update(deltaSeconds)`
+wraps a thrown Scene failure as `system-failed`; the wrapper's
+`error.detail.cause` is the original `SceneError` (including its structured
+`code`/`detail`). That post-write system failure poisons the World, so the next
+use returns `world-poisoned`. Inspect `detail.cause`, stop using that World
+identity, discard it, and ask the App execution owner to call
+`app.execution.rebuild()` for a fresh World. Do not retry a poisoned or
+partially-written World in place.
+
+If an explicitly malformed internal fixture reports a `Children` mirror
+mismatch, never write the target array directly. A same-target
+`world.set(child, ChildOf, { parent })` intentionally records the source
+evidence but skips mirror/index churn, so it cannot repair that mismatch. On a
+healthy World, repair through the source owner by removing and re-adding
+`ChildOf` (or reparenting through another target and then back to the intended
+one); if the failure has poisoned the World, discard it and rebuild through the
+App instead.
 
 Transform propagation writes the exact recomputed frontier into
 `GlobalTransform` and advances those rows' ordinary component versions only
@@ -30,6 +51,18 @@ subtree is exposed as contiguous spans without a parallel event journal.
 `Transform` remains authored local TRS; `GlobalTransform` is the resolved
 world-space authority.
 
+For a valid hierarchy, propagation expands the ECS-maintained `Children`
+buffer from each root in parent-first order. `ChildOf` is the writable source
+fact; `Children` is a read-only materialized target, so source mutations and
+their reverse lists converge before the frame pass. The numeric traversal
+borrows ECS columns and uses only constant matrix scratch plus depth/row
+markers; it does not build a Scene graph or per-node matrix cache.
+
+Removing `ChildOf` is a structural root transition. Even when the authored
+`Transform` is unchanged, the next propagation composes and publishes that
+entity as a flat local root; ordinary same-value hierarchy recomputation still
+does not publish an unchanged `GlobalTransform` row.
+
 Flat propagation uses the same numeric kernel inline or through an installed
 SharedKernel executor. It borrows the existing changed query, joins root
 matrices before resolving the hierarchy, and leaves small or fragmented ranges
@@ -50,6 +83,16 @@ the full local/world pair transitively, while explicit `Transform` data still
 wins. This keeps hierarchy authoring small without adding per-frame repair or
 an additional scene-side component registry.
 
+Deferred `Commands.spawn` uses the same `{ component, data }` entries as
+`World.spawn`; the pending child is materialized and linked at command flush.
+For an existing child, the generic reparent call is
+`world.reparent(child, newParent, ChildOf, { parent: newParent })` and routes
+through the same relationship owner.
+
+`ChildOf` uses `linkedSpawn: true`: despawning a parent recursively despawns
+its linked hierarchy. A generic relationship may opt out, but that is not the
+Scene hierarchy lifecycle.
+
 Removing the required component is still an explicit malformed-state escape
 hatch, not an automatic cascade. Propagation reports that state as a
 structured `SceneError`, preserving a clear owner and recovery path.

package/dist/__tests__/fixtures/malformed-hierarchy-edge.d.ts

@@ -1,8 +1,10 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 /**
- * Scene-owned malformed-edge fixture. The public relationship write accepts
- * stale handles as data; the projection then owns the liveness diagnostic.
- * Keeping this fixture on `world.set` avoids a private ECS graph seam.
+ * Scene-owned malformed-edge fixture. Production relationship writes reject
+ * stale targets and cycles before touching either side of the relationship.
+ * This test-only fixture deliberately corrupts the source column through the
+ * existing package-internal graph seam so projection can exercise its
+ * fail-closed diagnostics without weakening the public write contract.
  */
 export declare function setMalformedParentEdge(world: World, child: EntityHandle, parent: EntityHandle): void;
 //# sourceMappingURL=malformed-hierarchy-edge.d.ts.map

package/dist/__tests__/fixtures/malformed-hierarchy-edge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"malformed-hierarchy-edge.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/malformed-hierarchy-edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,IAAI,CAEN"}
+{"version":3,"file":"malformed-hierarchy-edge.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/malformed-hierarchy-edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAM/D;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,IAAI,CAmBN"}

package/dist/__tests__/hierarchy-propagation.perf.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hierarchy-propagation.perf.test.d.ts.map

package/dist/__tests__/hierarchy-propagation.perf.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-propagation.perf.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/hierarchy-propagation.perf.test.ts"],"names":[],"mappings":""}

package/dist/components/child-of.d.ts

@@ -3,15 +3,16 @@ export { ChildOf } from './children';
  * Hierarchy back-reference: pointer from child entity to its parent.
  *
  * Store the parent `Entity` handle (returned by `world.spawn(...).unwrap()`)
- * in the `parent` field; `propagateTransforms` reads it each frame to
- * compose the child's derived `GlobalTransform.world` mat4 (child.world =
- * parent.world x child local). `Transform` declares `GlobalTransform` as a
+ * in the `parent` field; `propagateTransforms` follows the ECS-maintained
+ * `Children` list each frame to compose the child's derived
+ * `GlobalTransform.world` mat4 (child.world = parent.world x child local).
+ * `Transform` declares `GlobalTransform` as a
  * generic ECS requirement, so normal spawn/add/command paths materialize the
  * pair without scene-specific repair. Propagation still fails closed when an
- * owner explicitly removes one half. Despawning a child auto-detaches it from the
- * parent's Children list (relationship `onRemove` hook). Despawning the
- * parent does not auto-clean the child's ChildOf; the consumer removes the
- * stale ChildOf (`world.removeComponent`) or checks `world.get(parent, Entity)` for liveness.
+ * owner explicitly removes one half. Despawning a child auto-detaches it from
+ * its parent's Children list; despawning the parent follows ChildOf's
+ * linkedSpawn cascade, while a malformed internal fixture can still leave a
+ * stale source for Scene diagnostics.
  *
  * Because ChildOf declares a `relationship` mirror and a structural
  * `Transform` requirement, the engine keeps the parent's `Children.entities`
@@ -22,8 +23,9 @@ export { ChildOf } from './children';
  * prior OOS-10 contract is retired).
  * Reparenting is a plain re-add: `world.addComponent(child, { component:
  * ChildOf, data: { parent: newParent } })` on an entity that already carries
- * ChildOf auto-reparents (exclusive arm), or use `world.reparent(child,
- * newParent)`.
+ * ChildOf auto-reparents (exclusive arm). The generic convenience method has
+ * the same owner path and requires the relationship component plus its data:
+ * `world.reparent(child, newParent, ChildOf, { parent: newParent })`.
  *
  * @example Spawn a child entity referencing an already-spawned root:
  *   const root = world.spawn(

package/dist/components/child-of.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"child-of.d.ts","sourceRoot":"","sources":["../../src/components/child-of.ts"],"names":[],"mappings":"AA2DA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG"}
+{"version":3,"file":"child-of.d.ts","sourceRoot":"","sources":["../../src/components/child-of.ts"],"names":[],"mappings":"AA6DA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}

package/dist/components/children.d.ts

@@ -2,25 +2,26 @@
  * Hierarchy forward-list of child entities.
  *
  * `entities` is a variable-length `array<entity>` field; each element is
- * an `Entity` u32 the AI user pushed via
- * `world.push(parent, Children, 'entities', child)`. The value returned by
- * `world.get(parent, Children).unwrap().entities` is a read-only
+ * an `Entity` u32 the ECS relationship owner materialized. The value returned
+ * by `world.get(parent, Children).unwrap().entities` is a detached read-only
  * `Uint32Array` snapshot rematerialised fresh on every read (D-4 no-cache);
- * the snapshot's `length` equals the live element count.
+ * mutating the returned array cannot change ECS-owned storage, and the
+ * snapshot's `length` equals the live element count. Internal Scene/ECS paths
+ * use the package-internal zero-copy array seams instead of this snapshot.
  *
  * Invariants:
- *   - Children is NOT consumed by `propagateTransforms` (which walks ChildOf
- *     upward, D-P2). The forward list is for AI-user traversal / debug /
- *     inspection.
+ *   - `propagateTransforms` consumes Children from the ECS-owned materialized
+ *     buffer and expands each root parent-first. The forward list is also
+ *     available for AI-user traversal / debug / inspection.
  *   - Children <-> ChildOf consistency is maintained by the engine via the
  *     ChildOf `relationship` mirror hook (see ./child-of.ts): adding /
  *     removing / reparenting ChildOf on a child auto-updates the parent's
  *     `entities` list. AI users do not hand-sync the two sides for the
  *     hierarchy.
- *   - Stored entity u32s are NOT auto-cleared when the referenced entity is
- *     despawned (OOS-01 above); a `world.get(despawnedChild, ...)` call
- *     returns `Result.err(...)` so AI users discover the dangling state
- *     through the engine's structured-error channel.
+ *   - ChildOf's linked lifecycle keeps ordinary Children entries aligned: a
+ *     child despawn prunes its source slot and a parent despawn cascades. A
+ *     deliberately malformed/non-linked edge remains observable as a dead
+ *     handle and must be diagnosed through the structured error channel.
  *
  * @example Spawn a parent and two children via ChildOf (engine maintains Children):
  *   const parent = world.spawn({ component: Transform, data: identityXf() }).unwrap();
@@ -36,8 +37,8 @@
  *   const snap = world.get(parent, Children).unwrap().entities;
  *   for (let i = 0; i < snap.length; i++) {
  *     const child = snap[i];
- *     // ... consume; world.get(child, ...) surfaces a structured error
- *     // if the child has been despawned (OOS-01 dangling-entity surface).
+ *     // ... consume; probe the handle before using it when reading a
+ *     // deliberately malformed/non-linked relationship.
  *   }
  */
 export declare const ChildOf: import("@forgeax/engine-ecs").Component<"ChildOf", {

package/dist/components/children.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"children.d.ts","sourceRoot":"","sources":["../../src/components/children.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAgB,OAAO;;IAAU,QAAQ;;GAY9C,CAAC"}
+{"version":3,"file":"children.d.ts","sourceRoot":"","sources":["../../src/components/children.ts"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAgB,OAAO;;IAAU,QAAQ;;GAY9C,CAAC"}