@vworlds/vecs 1.0.45 → 1.0.46

package/dist/terms/term.js

@@ -25,6 +25,8 @@ export class Term {
         this._entities = new Set();
         this._destroyed = false;
         this._childUnsubscribes = [];
+        /** Consumers that may act on a refresh while no membership event is in flight. */
+        this._quiescentRefreshConsumers = 0;
     }
     get count() {
         return this._entities.size;
@@ -72,13 +74,19 @@ export class Term {
             throw new Error(`Cannot subscribe to destroyed ${this.kind} term`);
         }
         this._consumers.add(consumer);
+        const refreshesWhileQuiescent = consumer.onTermRefresh !== undefined && consumer._refreshesOnlyInFlight !== true;
+        if (refreshesWhileQuiescent) {
+            this._quiescentRefreshConsumers++;
+        }
         let active = true;
         return () => {
             if (!active) {
                 return;
             }
             active = false;
-            this._consumers.delete(consumer);
+            if (this._consumers.delete(consumer) && refreshesWhileQuiescent) {
+                this._quiescentRefreshConsumers--;
+            }
             if (!this._pinned && this._consumers.size === 0) {
                 this.destroy();
             }
@@ -98,29 +106,57 @@ export class Term {
         }
         this._destroyed = true;
         this._consumers.clear();
+        this._quiescentRefreshConsumers = 0;
         while (this._childUnsubscribes.length > 0) {
             this._childUnsubscribes.pop()();
         }
         this._entities.clear();
         this._onDestroy(this);
     }
-    /** @internal Emit an enter event and add entity; no-op if already present. */
+    /**
+     * @internal Emit an enter event and add entity; no-op if already present.
+     *
+     * The world's `_termEmitDepth` counts the delivery as in flight from the
+     * membership change until every consumer has seen it.
+     */
     _add(entity) {
         if (this._entities.has(entity)) {
             return;
         }
-        this._entities.add(entity);
-        this._emit(0 /* TermEventKind.Enter */, entity);
+        const world = this.world;
+        world._termEmitDepth++;
+        try {
+            this._entities.add(entity);
+            this._emit(0 /* TermEventKind.Enter */, entity);
+        }
+        finally {
+            world._termEmitDepth--;
+        }
     }
-    /** @internal Emit an exit event and remove entity; no-op if not present. */
+    /** @internal Emit an exit event and remove entity; no-op if not present. Counted like {@link _add}. */
     _delete(entity) {
-        if (!this._entities.delete(entity)) {
-            return;
+        const world = this.world;
+        world._termEmitDepth++;
+        try {
+            if (this._entities.delete(entity)) {
+                this._emit(1 /* TermEventKind.Exit */, entity);
+            }
+        }
+        finally {
+            world._termEmitDepth--;
         }
-        this._emit(1 /* TermEventKind.Exit */, entity);
     }
-    /** @internal Propagate a refresh hint to all consumers (both channels). */
+    /**
+     * @internal Propagate a refresh hint to all consumers (both channels).
+     *
+     * Skipped when no membership event is in flight and every consumer either
+     * has no `onTermRefresh` or only acts on one while an event is in flight: no
+     * consumer would do anything.
+     */
     _emitRefresh(entity) {
+        if (this._quiescentRefreshConsumers === 0 && this.world._termEmitDepth === 0) {
+            return;
+        }
         this._consumers.forEach((consumer) => consumer.onTermRefresh?.(entity));
     }
     /** @internal Register an additional cleanup callback run during `destroy`. */
@@ -153,13 +189,24 @@ export class Term {
      */
     _setChildren(children) {
         this._children.push(...children);
+        const refreshesOnlyInFlight = this._childRefreshesOnlyInFlight();
         children.forEach((child) => {
             this._childUnsubscribes.push(child.subscribe({
                 onTermEvent: (kind, entity) => this._onChildEvent(kind, entity, child),
                 onTermRefresh: (entity) => this._onChildRefresh(entity, child),
+                _refreshesOnlyInFlight: refreshesOnlyInFlight,
             }));
         });
     }
+    /**
+     * @internal Whether {@link _onChildRefresh} only acts while a membership
+     * event is in flight. Terms whose membership depends on child membership
+     * alone (`all`, `any`, `not`) return `true`, which lets a child skip
+     * delivering refreshes to them while the world is quiescent.
+     */
+    _childRefreshesOnlyInFlight() {
+        return false;
+    }
     /**
      * @internal Default child membership-event handler: forward to
      * `onTermEvent`. Composite terms (e.g. `TargetTerm`) override this to
@@ -174,7 +221,9 @@ export class Term {
      * Most composites delegate to `onTermRefresh` which defaults to `_sync`.
      * Subclasses that only want to react to *specific* child kinds (e.g.
      * `PredicateTerm` reacting only to component-kind children) override this
-     * to filter before calling `_sync`.
+     * to filter before calling `_sync`. `AllTerm` and `AnyTerm`, whose membership
+     * depends only on their children's membership, ignore refreshes unless a
+     * membership event is still in flight.
      */
     _onChildRefresh(entity, _child) {
         this.onTermRefresh(entity);

package/dist/terms/term.js.map

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

package/dist/util/array_map.d.ts

@@ -47,21 +47,37 @@ export declare class ArrayMap<T> {
  * An iterable `Map<number, T>` substitute backed by dense entries plus sparse indexes.
  *
  * Use this when callers need fast `forEach` or `values` over present entries.
- * Random access resolves `key -> dense index` through {@link ArrayMap}, then
- * indexes into `_items`; iteration walks the dense `_items` array directly.
+ * Random access reads the entry's dense position from a sparse slot array
+ * indexed by key, then reads the value from the dense value array; iteration
+ * walks the dense key and value arrays directly.
  *
- * Deletes keep `_items` dense by moving the last value into the removed slot
- * and updating the moved value's stored index.
+ * Deletes keep the dense arrays dense by moving the last entry into the removed
+ * position and updating the moved entry's slot.
  *
- * Compared with {@link ArrayMap}, this costs extra memory for tuple storage and
- * an index map, and `delete`/new `set` do more bookkeeping. In return, iteration
- * is dense and does not scan sparse holes.
+ * Compared with {@link ArrayMap}, this costs extra memory for the dense arrays,
+ * and `delete`/new `set` do more bookkeeping. In return, iteration is dense and
+ * does not scan sparse holes.
+ *
+ * Trade-off: the dense arrays grow by `push`, so V8 cannot pretenure the entries
+ * the way it pretenured the per-entry `[key, value]` literals of the previous
+ * layout. A fresh process that creates tens of thousands of long-lived entities
+ * in bulk and then destroys them is slower for it: 3–17% to create and 19–35%
+ * to destroy 65,536 two-component entities. The gap comes from allocation-site
+ * pretenuring, not extra work, and it reverses under
+ * `node --no-allocation-site-pretenuring`. Lookups take two loads instead of
+ * four, and the layout took about 9% off the steady-state tick of
+ * `bench/sector-tick.ts`; `bench/README.md` has the measurements.
  *
  * @typeParam T - Value type stored in the map.
  */
 export declare class IterableArrayMap<T> {
-    private readonly _indices;
-    private readonly _items;
+    /**
+     * Key -> dense position + 1. Holes and `0` mean "absent", so the array only
+     * ever holds small integers and lookups stay on V8's fast SMI elements path.
+     */
+    private readonly _slots;
+    private readonly _keys;
+    private readonly _values;
     /** The number of entries currently in the map. */
     get size(): number;
     /**
@@ -95,12 +111,27 @@ export declare class IterableArrayMap<T> {
      * @param callback - Invoked with `(value, key, map)` for each entry.
      */
     forEach(callback: (value: T, key: number, map: IterableArrayMap<T>) => void): void;
+    /**
+     * Visit every present entry tolerating deletion of the **current** entry
+     * from inside the callback.
+     *
+     * `delete` swaps the last entry into the vacated slot, which the plain
+     * {@link IterableArrayMap.forEach} would skip. This variant re-visits the
+     * slot after the callback returns when a new entry has been swapped in, so
+     * the swapped-in entry is visited next. Deleting the last entry (no swap,
+     * slot just pops out of bounds) is detected via a length check.
+     *
+     * Only deletion of the current entry is safe. A callback that deletes a
+     * *different* (lower-indexed) entry will still cause that swapped-in entry
+     * to be skipped — callers that mutate other slots must keep using a
+     * snapshot.
+     */
+    forEachSafe(callback: (value: T, key: number, map: IterableArrayMap<T>) => void): void;
     /**
      * Return an iterator over `[key, value]` entries in dense item order.
      *
-     * Entries are backed by the map's internal storage for speed. Treat them as
-     * immutable; mutating them through casts or plain JavaScript can corrupt the
-     * map's key index.
+     * Each entry is a fresh pair read from the map's current contents as the
+     * iterator advances.
      */
     entries(): IterableIterator<readonly [number, T]>;
     /** Return an iterator over `[key, value]` entries in dense item order. */

package/dist/util/array_map.js

@@ -70,26 +70,42 @@ export class ArrayMap {
  * An iterable `Map<number, T>` substitute backed by dense entries plus sparse indexes.
  *
  * Use this when callers need fast `forEach` or `values` over present entries.
- * Random access resolves `key -> dense index` through {@link ArrayMap}, then
- * indexes into `_items`; iteration walks the dense `_items` array directly.
+ * Random access reads the entry's dense position from a sparse slot array
+ * indexed by key, then reads the value from the dense value array; iteration
+ * walks the dense key and value arrays directly.
  *
- * Deletes keep `_items` dense by moving the last value into the removed slot
- * and updating the moved value's stored index.
+ * Deletes keep the dense arrays dense by moving the last entry into the removed
+ * position and updating the moved entry's slot.
  *
- * Compared with {@link ArrayMap}, this costs extra memory for tuple storage and
- * an index map, and `delete`/new `set` do more bookkeeping. In return, iteration
- * is dense and does not scan sparse holes.
+ * Compared with {@link ArrayMap}, this costs extra memory for the dense arrays,
+ * and `delete`/new `set` do more bookkeeping. In return, iteration is dense and
+ * does not scan sparse holes.
+ *
+ * Trade-off: the dense arrays grow by `push`, so V8 cannot pretenure the entries
+ * the way it pretenured the per-entry `[key, value]` literals of the previous
+ * layout. A fresh process that creates tens of thousands of long-lived entities
+ * in bulk and then destroys them is slower for it: 3–17% to create and 19–35%
+ * to destroy 65,536 two-component entities. The gap comes from allocation-site
+ * pretenuring, not extra work, and it reverses under
+ * `node --no-allocation-site-pretenuring`. Lookups take two loads instead of
+ * four, and the layout took about 9% off the steady-state tick of
+ * `bench/sector-tick.ts`; `bench/README.md` has the measurements.
  *
  * @typeParam T - Value type stored in the map.
  */
 export class IterableArrayMap {
     constructor() {
-        this._indices = new ArrayMap();
-        this._items = [];
+        /**
+         * Key -> dense position + 1. Holes and `0` mean "absent", so the array only
+         * ever holds small integers and lookups stay on V8's fast SMI elements path.
+         */
+        this._slots = [];
+        this._keys = [];
+        this._values = [];
     }
     /** The number of entries currently in the map. */
     get size() {
-        return this._items.length;
+        return this._keys.length;
     }
     /**
      * Insert or replace the value at `key`.
@@ -98,14 +114,14 @@ export class IterableArrayMap {
      * @param value - Value to store.
      */
     set(key, value) {
-        const existingIndex = this._indices.get(key);
-        if (existingIndex !== undefined) {
-            this._items[existingIndex] = [key, value];
+        const slot = this._slots[key];
+        if (slot > 0) {
+            this._values[slot - 1] = value;
             return;
         }
-        const index = this._items.length;
-        this._indices.set(key, index);
-        this._items.push([key, value]);
+        this._keys.push(key);
+        this._values.push(value);
+        this._slots[key] = this._keys.length;
     }
     /**
      * Retrieve the value stored at `key`, or `undefined` if no entry exists.
@@ -113,8 +129,8 @@ export class IterableArrayMap {
      * @param key - Non-negative integer key.
      */
     get(key) {
-        const index = this._indices.get(key);
-        return index === undefined ? undefined : this._items[index][1];
+        const slot = this._slots[key];
+        return slot > 0 ? this._values[slot - 1] : undefined;
     }
     /**
      * Return `true` when an entry exists at `key`.
@@ -122,7 +138,7 @@ export class IterableArrayMap {
      * @param key - Non-negative integer key.
      */
     has(key) {
-        return this._indices.has(key);
+        return this._slots[key] > 0;
     }
     /**
      * Remove the entry at `key`. Does nothing if no entry exists there.
@@ -130,19 +146,22 @@ export class IterableArrayMap {
      * @param key - Non-negative integer key.
      */
     delete(key) {
-        const index = this._indices.get(key);
-        if (index === undefined) {
+        const slot = this._slots[key];
+        if (!(slot > 0)) {
             return;
         }
-        const lastIndex = this._items.length - 1;
-        if (index !== lastIndex) {
-            const lastItem = this._items[lastIndex];
-            this._items[index] = lastItem;
-            const lastKey = lastItem[0];
-            this._indices.set(lastKey, index);
+        const keys = this._keys;
+        const values = this._values;
+        const lastIndex = keys.length - 1;
+        if (slot - 1 !== lastIndex) {
+            const lastKey = keys[lastIndex];
+            keys[slot - 1] = lastKey;
+            values[slot - 1] = values[lastIndex];
+            this._slots[lastKey] = slot;
         }
-        this._items.pop();
-        this._indices.delete(key);
+        keys.pop();
+        values.pop();
+        this._slots[key] = 0;
     }
     /**
      * Visit every present entry in dense item order.
@@ -150,21 +169,50 @@ export class IterableArrayMap {
      * @param callback - Invoked with `(value, key, map)` for each entry.
      */
     forEach(callback) {
-        const items = this._items;
-        for (let i = 0; i < items.length; i++) {
-            const [key, value] = items[i];
-            callback(value, key, this);
+        const keys = this._keys;
+        const values = this._values;
+        for (let i = 0; i < keys.length; i++) {
+            callback(values[i], keys[i], this);
+        }
+    }
+    /**
+     * Visit every present entry tolerating deletion of the **current** entry
+     * from inside the callback.
+     *
+     * `delete` swaps the last entry into the vacated slot, which the plain
+     * {@link IterableArrayMap.forEach} would skip. This variant re-visits the
+     * slot after the callback returns when a new entry has been swapped in, so
+     * the swapped-in entry is visited next. Deleting the last entry (no swap,
+     * slot just pops out of bounds) is detected via a length check.
+     *
+     * Only deletion of the current entry is safe. A callback that deletes a
+     * *different* (lower-indexed) entry will still cause that swapped-in entry
+     * to be skipped — callers that mutate other slots must keep using a
+     * snapshot.
+     */
+    forEachSafe(callback) {
+        const keys = this._keys;
+        const values = this._values;
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            callback(values[i], key, this);
+            if (i < keys.length && keys[i] !== key) {
+                i--;
+            }
         }
     }
     /**
      * Return an iterator over `[key, value]` entries in dense item order.
      *
-     * Entries are backed by the map's internal storage for speed. Treat them as
-     * immutable; mutating them through casts or plain JavaScript can corrupt the
-     * map's key index.
+     * Each entry is a fresh pair read from the map's current contents as the
+     * iterator advances.
      */
-    entries() {
-        return this._items.values();
+    *entries() {
+        const keys = this._keys;
+        const values = this._values;
+        for (let i = 0; i < keys.length; i++) {
+            yield [keys[i], values[i]];
+        }
     }
     /** Return an iterator over `[key, value]` entries in dense item order. */
     [Symbol.iterator]() {
@@ -172,12 +220,13 @@ export class IterableArrayMap {
     }
     /** Return every present value in dense item order. */
     values() {
-        return this._items.map(([, value]) => value);
+        return this._values.slice();
     }
     /** Remove all entries and reset {@link size} to zero. */
     clear() {
-        this._indices.clear();
-        this._items.length = 0;
+        this._slots.length = 0;
+        this._keys.length = 0;
+        this._values.length = 0;
     }
 }
 //# sourceMappingURL=array_map.js.map

package/dist/util/array_map.js.map

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

package/dist/util/dense_set.js

@@ -68,6 +68,32 @@ export class DenseSet {
             callbackfn.call(thisArg, items[i], items[i], this);
         }
     }
+    /**
+     * Visit each element (current order) tolerating deletion of the **current**
+     * element from inside the callback.
+     *
+     * `delete` swaps the last element into the vacated slot, which the plain
+     * {@link DenseSet.forEach} would skip. This variant holds the index after
+     * the callback returns when a new element has been swapped in, so the
+     * swapped-in value is visited next. Deleting the last element (no swap,
+     * slot just pops out of bounds) is detected via a length check so the
+     * previous slot is never re-processed.
+     *
+     * Only deletion of the current element is safe. A callback that deletes a
+     * *different* (lower-indexed) member will still cause that swapped-in
+     * element to be skipped — callers that mutate other slots must keep using
+     * a snapshot.
+     */
+    forEachSafe(callbackfn, thisArg) {
+        const items = this._items;
+        for (let i = 0; i < items.length; i++) {
+            const cur = items[i];
+            callbackfn.call(thisArg, cur, cur, this);
+            if (i < items.length && items[i] !== cur) {
+                i--;
+            }
+        }
+    }
     /** Iterator over elements in current order. */
     [Symbol.iterator]() {
         return this._items[Symbol.iterator]();

package/dist/util/dense_set.js.map

@@ -1 +1 @@
-{"version":3,"file":"dense_set.js","sourceRoot":"","sources":["../../src/util/dense_set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,QAAQ;IAArB;QACmB,WAAM,GAAQ,EAAE,CAAC;QACjB,UAAK,GAAG,IAAI,GAAG,EAAa,CAAC;IA+EhD,CAAC;IA7EC,2CAA2C;IAC3C,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,mEAAmE;IACnE,IAAW,CAAC,MAAM,CAAC,WAAW,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,6CAA6C;IACtC,GAAG,CAAC,KAAQ;QACjB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8CAA8C;IACvC,GAAG,CAAC,KAAQ;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,KAAQ;QACpB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAG,CAAC;QAChC,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4BAA4B;IACrB,KAAK;QACV,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,yEAAyE;IAClE,OAAO,CAAC,UAAsD,EAAE,OAAiB;QACtF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,+CAA+C;IACxC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,gDAAgD;IACzC,CAAC,OAAO;QACb,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,+CAA+C;IACxC,IAAI;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,+CAA+C;IACxC,MAAM;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxC,CAAC;CACF"}
+{"version":3,"file":"dense_set.js","sourceRoot":"","sources":["../../src/util/dense_set.ts"],"names":[],"mappings":"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"}

package/dist/world/world.base.js

@@ -16,6 +16,18 @@ export class Base {
          * removals, and destroy cleanup can delete stale entries safely.
          */
         this._identityIndexedNames = new WeakMap();
+        /**
+         * @internal Entity of the system currently running, or `undefined` outside a
+         * system. Stamped onto every command at enqueue time so the originating
+         * system survives until the command is routed (see {@link System._run}).
+         */
+        this._currentSource = undefined;
+        /**
+         * @internal Source entity of the command currently being applied. Read by
+         * {@link Query._notifyModified} to silence updates from ignored sources;
+         * cleared once the command queue drains.
+         */
+        this._routingSource = undefined;
     }
 }
 //# sourceMappingURL=world.base.js.map

package/dist/world/world.base.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.base.js","sourceRoot":"","sources":["../../src/world/world.base.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,IAAI;IAAjB;QACE;;;;WAIG;QACa,mBAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3D;;;WAGG;QACa,uBAAkB,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE/D;;;WAGG;QACa,0BAAqB,GAAG,IAAI,OAAO,EAAkB,CAAC;IAexE,CAAC;CAAA"}
+{"version":3,"file":"world.base.js","sourceRoot":"","sources":["../../src/world/world.base.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,IAAI;IAAjB;QACE;;;;WAIG;QACa,mBAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3D;;;WAGG;QACa,uBAAkB,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE/D;;;WAGG;QACa,0BAAqB,GAAG,IAAI,OAAO,EAAkB,CAAC;QAEtE;;;;WAIG;QACI,mBAAc,GAAuB,SAAS,CAAC;QAEtD;;;;WAIG;QACI,mBAAc,GAAuB,SAAS,CAAC;IACxD,CAAC;CAAA"}

package/dist/world/world.d.ts

@@ -20,6 +20,13 @@ import { type WorldOptions } from "./world.base.js";
  * deferred scope; user code can wrap arbitrary blocks with
  * {@link beginDefer} / {@link endDefer} or {@link defer}. {@link flush}
  * drains the queue at top level.
+ *
+ * ## Cross-world transfer
+ *
+ * {@link snapshotSubtree}, {@link restoreSubtree}, and {@link moveSubtree}
+ * capture and recreate an entity forest in a second world. They reject calls
+ * while either world is deferred, because cross-world scheduling is the
+ * application's job.
  */
 export declare class World extends Pipeline {
     constructor(options?: WorldOptions);

package/dist/world/world.deferred.js

@@ -8,6 +8,17 @@ export class Deferred extends Queries {
         this._deferredDepth = 0;
         /** @internal `true` while {@link _processCommandQueue} is iterating, to avoid re-entrant drains. */
         this._draining = false;
+        /**
+         * @internal Buffered cleanup actions scheduled by `Entity._cleanupIncoming`.
+         *
+         * `undefined` outside an active `_destroy` cascade. The outermost `_destroy`
+         * call lazily allocates the scope, recursive `_destroy` calls append to the
+         * same scope, and the outermost call drains it to empty before returning.
+         * Set back to `undefined` during each flush pass so recursive destroys
+         * triggered by the flush buffer into a fresh scope and are drained by the
+         * outer `while` loop.
+         */
+        this._deletionScope = undefined;
     }
     /** `true` while the world is in deferred mode. */
     get deferred() {
@@ -69,6 +80,12 @@ export class Deferred extends Queries {
             case 5 /* CommandKind.Attach */:
                 cmd.entity._attach(cmd.meta, cmd.component);
                 return;
+            case 6 /* CommandKind.AddTarget */:
+                cmd.entity._addTarget(cmd.meta, cmd.target);
+                return;
+            case 7 /* CommandKind.RemoveTarget */:
+                cmd.entity._removeTarget(cmd.meta, cmd.target);
+                return;
         }
     }
     /** @internal Drain the top-level command queue in arrival order. */

package/dist/world/world.deferred.js.map

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

package/dist/world/world.entities.d.ts

@@ -12,13 +12,24 @@ export declare class Entities extends Deferred {
      * deferred scope return that same pending entity.
      */
     getOrCreateEntity(this: World, eid: EID, onCreateCallback?: (e: Entity) => void): Entity;
-    /** Look up an entity by component ref or identity name. */
+    /**
+     * Look up an entity by component ref or identity name.
+     *
+     * A foreign `Entity` (one whose `world` is not this world) throws: passing an
+     * entity from another world is a programming error, not a miss. An `Entity`
+     * whose world matches but whose eid is unknown (e.g. after destruction)
+     * returns `undefined`.
+     */
     getEntity(this: World, ref: ComponentRef | string): Entity | undefined;
     /** Create a new entity with an auto-assigned id. */
     entity(this: World): Entity;
     /** Look up an existing entity by identity name, creating it if absent. */
     entity(this: World, ref: string): Entity;
-    /** Look up an existing entity by component ref. */
+    /**
+     * Look up an existing entity by component ref.
+     *
+     * A foreign `Entity` ref throws (see {@link getEntity}).
+     */
     entity(this: World, ref: ComponentRef): Entity;
     /** Destroy every entity currently tracked by the world. */
     clearAllEntities(): void;