@vworlds/vecs 1.0.44 → 1.0.46

package/dist/entity/entity.js

@@ -16,7 +16,7 @@ import { IdentityEntity } from "./entity.identity.js";
  * ## Deferred semantics
  *
  * Inside a system body or `forEach` iteration the world is in **deferred
- * mode**: `add` / `attach` / `set` / `ensure` / `ensureTarget` / `modified` / `remove` /
+ * mode**: `add` / `attach` / `set` / `ensure` / `modified` / `remove` /
  * `destroy` only enqueue commands. The data layer (the components map and
  * `componentBitmask`) is mutated when the world drains its queue. Concretely,
  * while deferred:
@@ -25,7 +25,6 @@ import { IdentityEntity } from "./entity.identity.js";
  * - `entity.get(C)` / `entity.getMut(C)` returns `undefined` after `entity.attach(instance)` if C was absent.
  * - `entity.get(C)` / `entity.getMut(C)` returns the previous value after `entity.set(C, props)`.
  * - `entity.ensure(C)` returns a mutable component immediately, but `entity.get(C)` does not see it until the queue drains.
- * - `entity.ensureTarget(R)` returns its pending target immediately, but `entity.target(R)` does not see it until the queue drains.
  * - `entity.get(C)` / `entity.getMut(C)` still returns the component after `entity.remove(C)`.
  *
  * Outside deferred mode the same calls execute inline and mutations are
@@ -34,7 +33,7 @@ import { IdentityEntity } from "./entity.identity.js";
 export class Entity extends IdentityEntity {
     /** Attach this entity to `parent` through the built-in `ChildOf` relationship. */
     childOf(parent) {
-        return this.set(ChildOf, { target: parent });
+        return this.add(ChildOf, parent);
     }
     /** Get this entity's parent through the built-in `ChildOf` relationship, if present. */
     get parent() {

package/dist/entity/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/entity/entity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAWtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,MAAO,SAAQ,cAAc;IACxC,kFAAkF;IAC3E,OAAO,CAAC,MAAc;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,wFAAwF;IACxF,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,IAAW,MAAM,CAAC,MAA0B;QAC1C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,IAAW,SAAS;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,oDAAoD;IACpD,IAAW,KAAK;QACd,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/entity/entity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAWtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,MAAO,SAAQ,cAAc;IACxC,kFAAkF;IAC3E,OAAO,CAAC,MAAc;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,wFAAwF;IACxF,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,IAAW,MAAM,CAAC,MAA0B;QAC1C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,IAAW,SAAS;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,oDAAoD;IACpD,IAAW,KAAK;QACd,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;IAC1B,CAAC;CACF"}

package/dist/entity/entity.lifecycle.d.ts

@@ -1,4 +1,5 @@
 import { Components } from "./entity.components.js";
+import type { Entity } from "./entity.js";
 export declare class Lifecycle extends Components {
     /**
      * Destroy this entity.
@@ -6,8 +7,13 @@ export declare class Lifecycle extends Components {
      * Each component fires its `onRemove` hook, the entity is unregistered from
      * the world, and incoming relationship cleanup policies are applied. After
      * destruction the entity must not be used.
+     *
+     * A synchronous throw (a `Throw`-policy component entity still in use)
+     * happens before any mutation, so the world stays usable. A throw during
+     * deferred application or a cleanup cascade propagates out of `progress()` /
+     * `flush()` and leaves the world partial — treat it as a programming error.
      */
-    destroy(): void;
+    destroy(this: Entity): void;
     private _applyOnDelete;
     /**
      * Walk this entity's incoming relationships and buffer cleanup ops onto the

package/dist/entity/entity.lifecycle.js

@@ -21,39 +21,30 @@ export class Lifecycle extends Components {
         }
         try {
             const entityMeta = this._meta;
-            // Mark destroyed up front so a carrier cleanup that re-enters this entity's
-            // `_destroy` (possible with exotic relationship topologies under Delete)
-            // hits the guard above instead of tearing down twice.
-            this._destroyed = true;
+            let selfCarry = 0;
             if (entityMeta) {
-                const selfCarry = this._components.has(entityMeta.eid) ? 1 : 0;
-                if (entityMeta.usageCount > selfCarry) {
-                    if (entityMeta.onDelete === CleanupPolicy.Throw) {
-                        // The public `destroy()` already throws when an in-use component is
-                        // destroyed; reaching here means usage grew between that check and
-                        // this deferred apply. Abort instead of throwing so a mid-drain
-                        // `_processCommandQueue` is not left half-applied, and revive the
-                        // entity since nothing has been torn down yet.
-                        this._destroyed = false;
-                        return;
-                    }
-                    this._applyOnDelete(entityMeta, selfCarry);
+                selfCarry = this._components.has(entityMeta.eid) ? 1 : 0;
+                if (entityMeta.usageCount > selfCarry && entityMeta.onDelete === CleanupPolicy.Throw) {
+                    throw new Error(`Cannot destroy entity ${this.eid}; component eid is still in use`);
                 }
             }
-            const entity = this;
-            this.world._notifyEntityDestroyed(entity);
-            this._components.forEach((c, ceid) => {
+            // Mark destroyed before applying cleanup so a carrier cascade that
+            // re-enters this entity cannot tear it down twice.
+            this._destroyed = true;
+            if (entityMeta && entityMeta.usageCount > selfCarry) {
+                this._applyOnDelete(entityMeta, selfCarry);
+            }
+            this.world._notifyEntityDestroyed(this);
+            this._components.forEachSafe((c, ceid) => {
                 const componentMeta = this.world.entity(ceid).meta;
                 if (componentMeta.isRelationship) {
-                    this._removeIncoming(c.target, ceid);
+                    this._detachRelationship(componentMeta, c);
+                    return;
                 }
                 this.componentBitmask.deleteBit(componentMeta.bitPtr);
-                this.world._notifyComponentRemoved(ceid, entity);
-                componentMeta._decrementUsage();
-                const removeHandlers = componentMeta._onRemoveHandlers;
-                if (removeHandlers) {
-                    removeHandlers.forEach((handler) => handler(entity, c));
-                }
+                this.world._notifyComponentRemoved(ceid, this);
+                componentMeta._detachCarrier(this);
+                componentMeta._onRemove?.(this, c);
             });
             this._dirtyComponentBitmask.clear();
             this._queries.clear();
@@ -61,7 +52,7 @@ export class Lifecycle extends Components {
             if (entityMeta && entityMeta.usageCount === 0 && entityMeta.Class !== Object) {
                 this.world._classRegistry.delete(entityMeta.Class);
             }
-            this.world._unregisterEntity(entity);
+            this.world._unregisterEntity(this);
             this._cleanupIncoming();
         }
         finally {
@@ -81,6 +72,11 @@ export class Lifecycle extends Components {
      * Each component fires its `onRemove` hook, the entity is unregistered from
      * the world, and incoming relationship cleanup policies are applied. After
      * destruction the entity must not be used.
+     *
+     * A synchronous throw (a `Throw`-policy component entity still in use)
+     * happens before any mutation, so the world stays usable. A throw during
+     * deferred application or a cleanup cascade propagates out of `progress()` /
+     * `flush()` and leaves the world partial — treat it as a programming error.
      */
     destroy() {
         const entityMeta = this._meta;
@@ -96,34 +92,28 @@ export class Lifecycle extends Components {
             this._destroy();
         }
     }
-    // Collect carriers first, then act: the scan must not mutate `world.entities`
-    // while iterating, and `_destroy` idempotency makes overlapping Delete
-    // cascades safe. Carriers are cleaned via the internal `_remove`/`_destroy`
-    // (not the deferred-aware public methods) so `usageCount` drops synchronously
-    // and the `usageCount === 0` classRegistry cleanup in `_destroy` stays correct.
-    // Edge: if a Delete carrier is itself an in-use component key with
-    // `onDelete = Throw`, its `_destroy` safe-aborts and it survives still holding
-    // this now-destroyed component eid. This is the same exotic policy-interaction
-    // class flagged in `_cleanupIncoming`; left for the relationship/query rework.
     _applyOnDelete(entityMeta, selfCarry) {
-        const ceid = entityMeta.eid;
-        const carriers = [];
-        let remaining = entityMeta.usageCount - selfCarry;
-        this.world.entities.forEach((e) => {
-            if (remaining > 0 && e !== this && e._get(ceid) !== undefined) {
-                carriers.push(e);
-                remaining--;
-            }
-        });
+        const carriers = entityMeta._carriers;
+        if (!carriers || carriers.size <= selfCarry) {
+            return;
+        }
         const shouldDelete = entityMeta.onDelete === CleanupPolicy.Delete;
-        for (const carrier of carriers) {
+        // forEachSafe tolerates deletion of the current carrier mid-loop: each
+        // `_destroy`/`_remove` below detaches only its own carrier from this meta
+        // (via `_detachCarrier`), and any further cascade is buffered onto the
+        // world's deletion scope and drained after this scan completes — so no
+        // other slot of `carriers` is mutated while we are iterating it.
+        carriers.forEachSafe((carrier) => {
+            if (carrier === this) {
+                return;
+            }
             if (shouldDelete) {
                 carrier._destroy();
             }
             else {
                 carrier._remove(entityMeta);
             }
-        }
+        });
     }
     /**
      * Walk this entity's incoming relationships and buffer cleanup ops onto the
@@ -154,14 +144,11 @@ export class Lifecycle extends Components {
                 // `sources` is iterated read-only here; re-entrant _removeIncoming
                 // mutates it during the scope flush (after this scan completes), not
                 // during this forEach, so no snapshot is needed.
-                const sourceEntity = source;
                 if (policy === CleanupPolicy.Delete) {
-                    // If source is also an in-use component entity with onDelete Throw,
-                    // this exotic cascade can still throw; revisit with the relationship rework.
-                    scope.push([0 /* DeletionOpKind.Destroy */, sourceEntity]);
+                    scope.push([0 /* DeletionOpKind.Destroy */, source]);
                 }
                 else {
-                    scope.push([1 /* DeletionOpKind.Remove */, sourceEntity, relEntity.meta]);
+                    scope.push([1 /* DeletionOpKind.Remove */, source, relEntity.meta, this]);
                 }
             }
         });
@@ -183,7 +170,7 @@ export class Lifecycle extends Components {
                     op[1]._destroy();
                 }
                 else {
-                    op[1]._remove(op[2]);
+                    op[1]._removeTarget(op[2], op[3]);
                 }
             }
         }

package/dist/entity/entity.lifecycle.js.map

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

package/dist/entity/entity.queries.js

@@ -33,5 +33,35 @@ export class Queries extends Base {
     _isMemberOf(q) {
         return this._queries.has(q);
     }
+    /**
+     * @internal Route a `modified` event for component `ceid` to the queries this
+     * entity belongs to. Queries that do not watch `ceid` ignore it, so only the
+     * watchers matter.
+     *
+     * When every query watching `ceid` is a system, delivery only queues inbox
+     * events and the order across queries is unobservable, so the shorter of the
+     * world's watcher list and this entity's membership set is walked. Otherwise
+     * the membership set is walked in insertion order exactly as before: a plain
+     * query's `update` callback runs synchronously and may change that set
+     * mid-walk.
+     */
+    _routeModified(ceid, component) {
+        const watchers = this.world._updateWatchers[ceid];
+        if (watchers === undefined) {
+            return;
+        }
+        const queries = this._queries;
+        const list = watchers.queries;
+        if (watchers.synchronous === 0 && list.length < queries.size) {
+            for (let i = 0; i < list.length; i++) {
+                const q = list[i];
+                if (queries.has(q)) {
+                    q._notifyModified(this, ceid, component);
+                }
+            }
+            return;
+        }
+        queries.forEach((q) => q._notifyModified(this, ceid, component));
+    }
 }
 //# sourceMappingURL=entity.queries.js.map

package/dist/entity/entity.queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.queries.js","sourceRoot":"","sources":["../../src/entity/entity.queries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,MAAM,OAAO,OAAQ,SAAQ,IAAI;IAC/B;;;OAGG;IACI,mBAAmB,CAAC,CAAQ;QACjC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,WAAW,CAAC,CAAQ;QACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,sBAAsB,CAAC,CAAQ;QACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAAC,CAAQ;QACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;CACF"}
+{"version":3,"file":"entity.queries.js","sourceRoot":"","sources":["../../src/entity/entity.queries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGxC,MAAM,OAAO,OAAQ,SAAQ,IAAI;IAC/B;;;OAGG;IACI,mBAAmB,CAAC,CAAQ;QACjC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,WAAW,CAAC,CAAQ;QACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,sBAAsB,CAAC,CAAQ;QACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,WAAW,CAAC,CAAQ;QACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,cAAc,CAAe,IAAS,EAAE,SAA4B;QACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC;QAC9B,IAAI,QAAQ,CAAC,WAAW,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;YAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnB,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;IACnE,CAAC;CACF"}

package/dist/entity/entity.relationships.d.ts

@@ -4,6 +4,10 @@ import { Queries } from "./entity.queries.js";
 export declare class Relationships extends Queries {
     /** Return this entity's target through relationship `ref`, if present. */
     target(rel: ComponentRef): Entity | undefined;
+    /** Return a safe readonly snapshot of all targets through relationship `ref`. */
+    targets(rel: ComponentRef): readonly Entity[];
+    /** Return whether this entity targets `target` through relationship `ref`. */
+    hasTarget(rel: ComponentRef, target: Entity): boolean;
     /** Return entities targeting this one through relationship `ref`. */
     children(ref: ComponentRef): ReadonlySet<Entity>;
 }

package/dist/entity/entity.relationships.js

@@ -5,7 +5,21 @@ export class Relationships extends Queries {
     /** Return this entity's target through relationship `ref`, if present. */
     target(rel) {
         const relEid = typeof rel === "number" ? rel : this.world.entity(rel).eid;
-        return this._components.get(relEid)?.target;
+        return this._components.get(relEid)?._target();
+    }
+    /** Return a safe readonly snapshot of all targets through relationship `ref`. */
+    targets(rel) {
+        const relEid = typeof rel === "number" ? rel : this.world.entity(rel).eid;
+        return this._components.get(relEid)?._targetArray() ?? [];
+    }
+    /** Return whether this entity targets `target` through relationship `ref`. */
+    hasTarget(rel, target) {
+        const relEid = typeof rel === "number" ? rel : this.world.entity(rel).eid;
+        return this._components.get(relEid)?._hasTarget(target) ?? false;
+    }
+    /** @internal Test targets by relationship eid without allocating a snapshot. */
+    _someTargetByEid(relEid, predicate) {
+        return (this._components.get(relEid)?._someTarget(predicate) ?? false);
     }
     /** Return entities targeting this one through relationship `ref`. */
     children(ref) {
@@ -43,15 +57,9 @@ export class Relationships extends Queries {
         }
     }
     /** @internal */
-    _updateIncoming(meta, oldTarget, newTarget) {
-        if (!meta.isRelationship || oldTarget === newTarget) {
-            return;
-        }
-        this._removeIncoming(oldTarget, meta.eid);
-        this._addIncoming(newTarget, meta.eid);
-        if (oldTarget && newTarget) {
-            meta._onRetargetHandlers?.forEach((handler) => handler(this, oldTarget, newTarget));
-        }
+    _notifyRelationshipChanged(meta, relationship) {
+        this.world._notifyComponentChanged(meta.eid, this);
+        this._routeModified(meta.eid, relationship);
     }
 }
 //# sourceMappingURL=entity.relationships.js.map

package/dist/entity/entity.relationships.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.relationships.js","sourceRoot":"","sources":["../../src/entity/entity.relationships.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,MAAM,OAAO,aAAc,SAAQ,OAAO;IACxC,0EAA0E;IACnE,MAAM,CAAC,GAAiB;QAC7B,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;QAC1E,OAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAA8B,EAAE,MAAM,CAAC;IAC5E,CAAC;IAED,qEAAqE;IAC9D,QAAQ,CAAC,GAAiB;QAC/B,MAAM,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;QAC1E,OAAO,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,cAAc,CAAC;IACrE,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,MAAW;QAC/B,OAAO,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,gBAAgB;IACN,YAAY,CAAC,MAA0B,EAAE,MAAW;QAC5D,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QACD,IAAI,OAAO,GAAG,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,IAAI,QAAQ,EAAU,CAAC;YACjC,CAAC,MAAM,CAAC,SAAS,KAAhB,MAAM,CAAC,SAAS,GAAK,IAAI,gBAAgB,EAAE,EAAC,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAyB,CAAC,CAAC;IACzC,CAAC;IAED,gBAAgB;IACN,eAAe,CAAC,MAA0B,EAAE,MAAW;QAC/D,MAAM,OAAO,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,IAAyB,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACvB,MAAO,CAAC,SAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,gBAAgB;IACN,eAAe,CACvB,IAAmB,EACnB,SAA6B,EAC7B,SAA6B;QAE7B,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACpD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5C,OAAO,CAAC,IAAyB,EAAE,SAAS,EAAE,SAAS,CAAC,CACzD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"entity.relationships.js","sourceRoot":"","sources":["../../src/entity/entity.relationships.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,17 +2,20 @@ export { System, type SystemQuery } from "./system.js";
 export { Query, GroupedQuery, Group } from "./query/index.js";
 export type { EntityTestFunc, MaybeRequired, QueryDSL } from "./dsl.js";
 export { Iter } from "./inject.js";
-export type { DownInject, FanInjectElement, FanInjectTuple, InjectElement, InjectTuple, MaybeResolvedInjectTuple, RequiredResolvedInjectTuple, TargetInject, } from "./inject.js";
+export type { DownInject, FanInjectElement, FanInjectTuple, InjectElement, InjectTuple, MaybeResolvedInjectTuple, RequiredResolvedInjectTuple, ResolvedTargets, ResolvedTargetsRow, TargetInject, TargetInjectProjection, TargetsInject, } from "./inject.js";
 export { DEFAULT_POOLS, World, type WorldOptions } from "./world/index.js";
 export { Filter } from "./filter.js";
-export { ChildOf, DependsOn, OwnedTarget, SilenceSource } from "./modules/relationships.js";
-export { CleanupPolicy, Component, Implements, Relationship, type ComponentInstance, type ComponentClass, type ComponentMeta, type ComponentRef, type RetargetHandler, } from "./component.js";
+export { ChildOf, DependsOn, Exclusive, OneOf, OwnedTarget, SilenceSource, } from "./modules/relationships.js";
+export { CleanupPolicy, Component, Implements, Relationship, type ComponentInstance, type ComponentClass, type ComponentMeta, type ComponentRef, type CustomSnapshotOptions, type HookEvent, type HookEventMap, type HookHandler, type TargetHandler, } from "./component.js";
 export { Entity, type EID, type EntityClass, Identity } from "./entity/index.js";
 export { Module, type ModuleConfig } from "./module.js";
+export { MoveSubtreeError } from "./world/world.transfers.js";
 export { IdentityModule } from "./modules/identity.js";
 export { ImplementsModule } from "./modules/implements.js";
 export { Singleton, SingletonModule } from "./modules/singleton.js";
-export { Traversable, RelationshipsModule } from "./modules/relationships.js";
+export { Traversable, With, RelationshipsModule } from "./modules/relationships.js";
+export { type SnapshotCapture, type SnapshotMaterialize, ClonePublic, CustomSnapshot, DontSnapshot, OnSnapshot, SnapshotModule, } from "./modules/snapshot.js";
+export { type ComponentSnapshot, type EntitySubtreeSnapshot, type ExternalTargetPolicy, type MoveSubtreeResult, type RelationshipSnapshot, type RelationshipType, type RestoreSubtreeResult, type SubtreeEntitySnapshot, type SubtreeSnapshotOptions, } from "./snapshot/types.js";
 export { BUILTIN_PIPELINE_PHASES, insertPhaseAfter, ON_LOAD, ON_STORE, ON_UPDATE, ON_VALIDATE, POST_LOAD, POST_UPDATE, PRE_STORE, PRE_UPDATE, Phase, PipelineModule, } from "./modules/pipeline.js";
 export { getDSLKey } from "./dsl.js";
 export { Term, TermEventKind, type TermConsumer } from "./terms/term.js";

package/dist/index.js

@@ -3,14 +3,16 @@ export { Query, GroupedQuery, Group } from "./query/index.js";
 export { Iter } from "./inject.js";
 export { DEFAULT_POOLS, World } from "./world/index.js";
 export { Filter } from "./filter.js";
-export { ChildOf, DependsOn, OwnedTarget, SilenceSource } from "./modules/relationships.js";
+export { ChildOf, DependsOn, Exclusive, OneOf, OwnedTarget, SilenceSource, } from "./modules/relationships.js";
 export { CleanupPolicy, Component, Implements, Relationship, } from "./component.js";
 export { Entity, Identity } from "./entity/index.js";
 export { Module } from "./module.js";
+export { MoveSubtreeError } from "./world/world.transfers.js";
 export { IdentityModule } from "./modules/identity.js";
 export { ImplementsModule } from "./modules/implements.js";
 export { Singleton, SingletonModule } from "./modules/singleton.js";
-export { Traversable, RelationshipsModule } from "./modules/relationships.js";
+export { Traversable, With, RelationshipsModule } from "./modules/relationships.js";
+export { ClonePublic, CustomSnapshot, DontSnapshot, OnSnapshot, SnapshotModule, } from "./modules/snapshot.js";
 export { BUILTIN_PIPELINE_PHASES, insertPhaseAfter, ON_LOAD, ON_STORE, ON_UPDATE, ON_VALIDATE, POST_LOAD, POST_UPDATE, PRE_STORE, PRE_UPDATE, Phase, PipelineModule, } from "./modules/pipeline.js";
 export { getDSLKey } from "./dsl.js";
 export { Term } from "./terms/term.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAWnC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAqB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC5F,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,YAAY,GAMb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAA8B,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,MAAM,EAAqB,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,UAAU,EACV,KAAK,EACL,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,IAAI,EAAoC,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAuC,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAqB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAenC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAqB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,OAAO,EACP,SAAS,EACT,SAAS,EACT,KAAK,EACL,WAAW,EACX,aAAa,GACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,YAAY,GAUb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAA8B,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,MAAM,EAAqB,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAGL,WAAW,EACX,cAAc,EACd,YAAY,EACZ,UAAU,EACV,cAAc,GACf,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,UAAU,EACV,KAAK,EACL,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,IAAI,EAAoC,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAuC,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAqB,MAAM,mBAAmB,CAAC"}

package/dist/inject.d.ts

@@ -2,30 +2,70 @@ import { type ComponentInstance, type ComponentRef, type ComponentType } from ".
 import { Entity, type EID } from "./entity/index.js";
 import { type World } from "./world/index.js";
 import { type MaybeRequired } from "./dsl.js";
-export type TargetInject<J extends readonly ComponentType[] = readonly ComponentType[]> = {
-    target: readonly [ComponentRef, readonly [...J]];
+export type TargetInjectProjection = ComponentType | typeof Entity;
+/**
+ * Follows a relationship and injects values from its target into a callback tuple.
+ *
+ * Pass one component class or {@link Entity} directly for a single slot, or pass
+ * a tuple to project several slots in order:
+ *
+ * ```ts
+ * { target: [FriendOf, Position] }          // Position | undefined
+ * { target: [FriendOf, Entity] }            // Entity | undefined
+ * { target: [FriendOf, [Entity, Position]] } // Entity | undefined, Position | undefined
+ * ```
+ *
+ * Every projected slot is optional because the relationship or target-side
+ * component may be absent when the callback runs.
+ */
+export type TargetInject<P extends TargetInjectProjection | readonly TargetInjectProjection[] = TargetInjectProjection | readonly TargetInjectProjection[]> = {
+    target: readonly [ComponentRef, P];
+};
+/**
+ * Follows every target of a relationship and injects one array-valued tuple slot.
+ * Each array entry is a projected tuple for one target, in relationship order.
+ */
+export type TargetsInject<P extends TargetInjectProjection | readonly TargetInjectProjection[] = TargetInjectProjection | readonly TargetInjectProjection[]> = {
+    targets: readonly [ComponentRef, P];
 };
 export type DownInject<J extends readonly ComponentType[] = readonly ComponentType[]> = {
     down: readonly [ComponentRef, readonly [...J]];
 };
-export type InjectElement = ComponentType | TargetInject;
+export type InjectElement = ComponentType | TargetInject | TargetsInject;
 export type InjectTuple = readonly InjectElement[];
 export type FanInjectElement = InjectElement | DownInject;
 export type FanInjectTuple = readonly FanInjectElement[];
 export type ResolvedInjectTerm = EID | {
     target: readonly [EID, readonly EID[]];
+} | {
+    targets: readonly [EID, readonly EID[]];
 } | {
     down: readonly [EID, readonly EID[]];
 };
-export type InjectSnapshot = readonly (ComponentInstance | undefined)[];
-export type InjectSnapshotTypes = readonly (EID | undefined)[];
 /** Resolves the component instance type for one injected component class. */
 type ResolvedComponentInstance<T> = T extends ComponentType ? InstanceType<T> : never;
 type OptionalResolvedComponentInstances<J extends readonly ComponentType[]> = {
     [K in keyof J]: InstanceType<J[K]> | undefined;
 };
-type MaybeResolvedInjectElement<T, R extends ComponentType[]> = T extends ComponentType ? [MaybeRequired<T, R>] : T extends TargetInject<infer J> ? OptionalResolvedComponentInstances<J> : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
-type RequiredResolvedInjectElement<T> = T extends ComponentType ? [ResolvedComponentInstance<T>] : T extends TargetInject<infer J> ? OptionalResolvedComponentInstances<J> : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
+type OptionalResolvedTargetProjection<P> = P extends typeof Entity ? Entity | undefined : P extends ComponentType ? InstanceType<P> | undefined : never;
+type OptionalResolvedTargetProjections<P> = P extends readonly TargetInjectProjection[] ? {
+    [K in keyof P]: OptionalResolvedTargetProjection<P[K]>;
+} : [OptionalResolvedTargetProjection<P>];
+type ResolvedTargetsProjection<P> = P extends typeof Entity ? Entity : P extends ComponentType ? InstanceType<P> | undefined : never;
+/** One projected row produced by a {@link TargetsInject}. */
+export type ResolvedTargetsRow<P> = P extends readonly TargetInjectProjection[] ? {
+    readonly [K in keyof P]: ResolvedTargetsProjection<P[K]>;
+} : readonly [ResolvedTargetsProjection<P>];
+/** The single array-valued callback slot produced by a {@link TargetsInject}. */
+export type ResolvedTargets<P> = ReadonlyArray<ResolvedTargetsRow<P>>;
+export type InjectedValue = ComponentInstance | Entity | ReadonlyArray<readonly (ComponentInstance | Entity | undefined)[]> | undefined;
+export type InjectSource = Entity | readonly Entity[] | undefined;
+export type InjectSnapshot = {
+    readonly values: readonly InjectedValue[];
+    readonly src: readonly InjectSource[];
+};
+type MaybeResolvedInjectElement<T, R extends ComponentType[]> = T extends ComponentType ? [MaybeRequired<T, R>] : T extends TargetInject<infer P> ? OptionalResolvedTargetProjections<P> : T extends TargetsInject<infer P> ? [ResolvedTargets<P>] : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
+type RequiredResolvedInjectElement<T> = T extends ComponentType ? [ResolvedComponentInstance<T>] : T extends TargetInject<infer P> ? OptionalResolvedTargetProjections<P> : T extends TargetsInject<infer P> ? [ResolvedTargets<P>] : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
 export type MaybeResolvedInjectTuple<J extends FanInjectTuple, R extends ComponentType[]> = J extends readonly [infer First, ...infer Rest extends FanInjectTuple] ? [...MaybeResolvedInjectElement<First, R>, ...MaybeResolvedInjectTuple<Rest, R>] : [];
 export type RequiredResolvedInjectTuple<J extends InjectTuple> = J extends readonly [
     infer First,
@@ -33,10 +73,18 @@ export type RequiredResolvedInjectTuple<J extends InjectTuple> = J extends reado
 ] ? [...RequiredResolvedInjectElement<First>, ...RequiredResolvedInjectTuple<Rest>] : [];
 export declare function mapInject(world: World, inject: readonly FanInjectElement[]): ResolvedInjectTerm[];
 export declare function injectArity(inject: readonly ResolvedInjectTerm[]): number;
-export declare function getInjected(e: Entity, inject: readonly ResolvedInjectTerm[], requireDirectComponents: boolean, out: (ComponentInstance | undefined)[], snapshot?: InjectSnapshot): void;
-export declare function getInjectedWithSrc(e: Entity, inject: readonly ResolvedInjectTerm[], out: (ComponentInstance | undefined)[], src: (Entity | undefined)[], requireDirectComponents?: boolean, exitSnapshot?: InjectSnapshot): void;
-export declare function directInjectEids(inject: readonly ResolvedInjectTerm[]): EID[];
-export declare function directInjectSnapshotTypes(inject: readonly ResolvedInjectTerm[]): InjectSnapshotTypes | undefined;
+export declare function getInjected(e: Entity, inject: readonly ResolvedInjectTerm[], requireDirectComponents: boolean, out: InjectedValue[]): void;
+export declare function getInjectedWithSrc(e: Entity, inject: readonly ResolvedInjectTerm[], out: InjectedValue[], src: InjectSource[], requireDirectComponents?: boolean): void;
+/** Capture a detached injection tuple and its source tuple for deferred callback replay. */
+export declare function snapshotInjected(e: Entity, inject: readonly ResolvedInjectTerm[], arity: number): InjectSnapshot;
+export declare function replayInjectedSnapshot(inject: readonly ResolvedInjectTerm[], snapshot: InjectSnapshot, requireDirectComponents: boolean, out: InjectedValue[]): void;
+export declare function replayInjectedSnapshotWithSrc(inject: readonly ResolvedInjectTerm[], snapshot: InjectSnapshot, requireDirectComponents: boolean, out: InjectedValue[], src: InjectSource[]): void;
+/**
+ * Component eids whose changes can alter a resolved tuple: directly injected
+ * component eids plus the relationship eid of every `target` / `targets` term.
+ * Callers watch these to re-sort or re-key when a tuple input changes.
+ */
+export declare function injectWatchEids(inject: readonly ResolvedInjectTerm[]): EID[];
 /**
  * Per-iteration cursor passed to `each` / `forEach` / `enter` / `exit` /
  * `update` / `orderBy` callbacks when the caller opts in by passing `Iter` as
@@ -61,11 +109,12 @@ export declare class Iter {
     /**
      * Source entity for each injected component, in the same order as the
      * resolved tuple: the visited entity for a directly-injected component, the
-     * relationship target for a `target`-injected one, or the specific child for
+     * relationship target for a `target`-injected one, the target array for a
+     * `targets`-injected one, or the specific child for
      * a `down`-injected one (`undefined` when the entity has no such relationship,
      * target, or — for `down` — when the slot is unfilled).
      */
-    readonly src: (Entity | undefined)[];
+    readonly src: InjectSource[];
     constructor(arity: number);
 }
 export declare function wantsIter(x: unknown): x is typeof Iter;
@@ -74,7 +123,7 @@ export type FanInjectCallbackOptions<J extends FanInjectTuple = FanInjectTuple>
     inject: readonly [...J];
 };
 export type FanInjectCallbackArg<J extends FanInjectTuple = FanInjectTuple> = readonly [...J] | FanInjectCallbackOptions<J>;
-export type InjectedCallback = (eOrIt: Entity | Iter, resolved: readonly (ComponentInstance | undefined)[]) => void;
+export type InjectedCallback = (eOrIt: Entity | Iter, resolved: readonly InjectedValue[]) => void;
 /**
  * Iterate `entities`, resolving injected components per the `forEach` /
  * `each` argument grammar (bare callback, `[components]`, or