@vworlds/vecs 1.0.24 → 1.0.26

package/dist/util/ordered_set.js

@@ -2,9 +2,14 @@
  * A `Set<T>` whose iteration order is determined by a comparator instead of
  * insertion order.
  *
- * Backed by a sorted array. Insertions and lookups are `O(log n)` (binary
- * search) plus the cost of an array splice on `add`. Removal uses identity
- * lookup because sorted values may be mutable.
+ * Backed by a sorted array plus a side `Set<T>` for O(1) membership checks.
+ * Insertions are `O(log n)` (binary search) plus the cost of an array splice.
+ * Removal uses identity lookup because sorted values may be mutable.
+ *
+ * The backing array can go stale relative to the comparator: callers mark it
+ * dirty with {@link markDirty} when data the comparator reads has changed.
+ * The next order-dependent read re-sorts the whole array in place before
+ * returning. `has` is unaffected by dirtiness — it always checks the side set.
  *
  * Used by `Query.orderBy` to keep matched entities in a user-defined order so
  * iteration in `forEach` and `each` walks them sorted.
@@ -16,6 +21,8 @@
 export class OrderedSet {
     constructor(compare) {
         this._items = [];
+        this._members = new Set();
+        this._dirty = false;
         this._compare = compare;
     }
     /**
@@ -36,6 +43,14 @@ export class OrderedSet {
         }
         return lo;
     }
+    /** Re-sort the backing array in place when {@link markDirty} was called. */
+    _ensureSorted() {
+        if (!this._dirty) {
+            return;
+        }
+        this._items.sort(this._compare);
+        this._dirty = false;
+    }
     /** Number of elements currently stored. */
     get size() {
         return this._items.length;
@@ -46,48 +61,52 @@ export class OrderedSet {
     }
     /**
      * Insert `value` at the position determined by the comparator. No-op when
-     * an element compares equal to `value`.
+     * `value` is already a member.
      *
      * @param value - Element to insert.
      */
     add(value) {
-        const i = this._bisect(value);
-        if (i < this._items.length && this._compare(this._items[i], value) === 0) {
+        if (this._members.has(value)) {
             return this;
         }
+        this._ensureSorted();
+        const i = this._bisect(value);
         this._items.splice(i, 0, value);
+        this._members.add(value);
         return this;
     }
-    /** Remove `value` by identity, then insert it at its current sort position. */
-    reSort(value) {
-        const i = this._items.indexOf(value);
-        if (i === -1) {
-            return this;
-        }
-        this._items.splice(i, 1);
-        return this.add(value);
+    /**
+     * Mark the backing array stale. The next order-dependent read re-sorts it
+     * with the comparator before returning.
+     */
+    markDirty() {
+        this._dirty = true;
     }
     /**
-     * Return `true` when an element comparing equal to `value` is in the set.
+     * Return `true` when `value` is a member of the set, regardless of sort
+     * state. O(1) identity lookup against the side membership set.
      *
      * @param value - Element to look up.
      */
     has(value) {
-        const i = this._bisect(value);
-        return i < this._items.length && this._compare(this._items[i], value) === 0;
+        return this._members.has(value);
     }
     /** Remove `value` by identity. Returns `true` if an element was removed. */
     delete(value) {
+        if (!this._members.delete(value)) {
+            return false;
+        }
         const i = this._items.indexOf(value);
         if (i !== -1) {
             this._items.splice(i, 1);
-            return true;
         }
-        return false;
+        return true;
     }
     /** Remove every element. */
     clear() {
         this._items.length = 0;
+        this._members.clear();
+        this._dirty = false;
     }
     /**
      * Visit each element in sorted order.
@@ -97,26 +116,31 @@ export class OrderedSet {
      * @param thisArg - Optional `this` binding for the callback.
      */
     forEach(callbackfn, thisArg) {
+        this._ensureSorted();
         for (const item of this._items) {
             callbackfn.call(thisArg, item, item, this);
         }
     }
     /** Iterator over elements in sorted order. */
     [Symbol.iterator]() {
+        this._ensureSorted();
         return this._items[Symbol.iterator]();
     }
     /** Iterator yielding `[value, value]` pairs in sorted order. */
     *entries() {
+        this._ensureSorted();
         for (const item of this._items) {
             yield [item, item];
         }
     }
     /** Iterator over elements in sorted order. */
     keys() {
+        this._ensureSorted();
         return this._items[Symbol.iterator]();
     }
     /** Iterator over elements in sorted order. */
     values() {
+        this._ensureSorted();
         return this._items[Symbol.iterator]();
     }
 }

package/dist/util/ordered_set.js.map

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

package/dist/world/world.deferred.js

@@ -50,7 +50,9 @@ export class Deferred extends Queries {
         switch (cmd.kind) {
             case 0 /* CommandKind.CreateEntity */:
                 this._entities.set(cmd.entity.eid, cmd.entity);
+                this._deferredEntities.delete(cmd.entity.eid);
                 this._notifyEntityCreated(cmd.entity);
+                cmd.onCreate?.(cmd.entity);
                 return;
             case 1 /* CommandKind.Set */:
                 cmd.entity._set(cmd.meta, cmd.props);

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

@@ -3,7 +3,14 @@ import { Entity, type EID } from "../entity/index.js";
 import { Deferred } from "./world.deferred.js";
 import type { World } from "./world.js";
 export declare class Entities extends Deferred {
-    /** Return the entity with id `eid`, creating it if it does not yet exist. */
+    /**
+     * Return the entity with id `eid`, creating it if it does not yet exist.
+     *
+     * In deferred mode, a newly created entity remains hidden from collections
+     * and queries until flush, but numeric lookups (`getEntity(eid)`,
+     * `entity(eid)`) and repeated `getOrCreateEntity(eid)` calls in the same
+     * 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. */
     getEntity(this: World, ref: ComponentRef | string): Entity | undefined;

package/dist/world/world.entities.js

@@ -2,19 +2,36 @@ import { Entity, Identity } from "../entity/index.js";
 import { Deferred } from "./world.deferred.js";
 const RESERVED_EID = 0;
 export class Entities extends Deferred {
-    /** Return the entity with id `eid`, creating it if it does not yet exist. */
+    /**
+     * Return the entity with id `eid`, creating it if it does not yet exist.
+     *
+     * In deferred mode, a newly created entity remains hidden from collections
+     * and queries until flush, but numeric lookups (`getEntity(eid)`,
+     * `entity(eid)`) and repeated `getOrCreateEntity(eid)` calls in the same
+     * deferred scope return that same pending entity.
+     */
     getOrCreateEntity(eid, onCreateCallback) {
         if (eid === RESERVED_EID) {
             throw new Error(`Entity eid ${eid} is reserved`);
         }
         let e = this._entities.get(eid);
+        if (!e && this.deferred) {
+            e = this._deferredEntities.get(eid);
+        }
         if (!e) {
             this._reserveEid(eid);
             e = new Entity(this, eid);
-            this._entities.set(eid, e);
-            this._notifyEntityCreated(e);
-            if (onCreateCallback) {
-                onCreateCallback(e);
+            if (this.deferred) {
+                // Mirror `_entity`: in deferred mode the entity is not registered or
+                // made visible to queries until the queue drains. The reservation above
+                // still happens eagerly so the id cannot be handed out again meanwhile.
+                this._deferredEntities.set(eid, e);
+                this._enqueue({ kind: 0 /* CommandKind.CreateEntity */, entity: e, onCreate: onCreateCallback });
+            }
+            else {
+                this._entities.set(eid, e);
+                this._notifyEntityCreated(e);
+                onCreateCallback?.(e);
             }
         }
         return e;
@@ -31,7 +48,8 @@ export class Entities extends Deferred {
             if (ref === RESERVED_EID) {
                 throw new Error(`Entity eid ${ref} is reserved`);
             }
-            return this._entities.get(ref);
+            const entity = this._entities.get(ref);
+            return entity ?? (this.deferred ? this._deferredEntities.get(ref) : undefined);
         }
         return ref.world === this && this._entities.get(ref.eid) === ref ? ref : undefined;
     }
@@ -85,6 +103,7 @@ export class Entities extends Deferred {
         const eid = this._entityPool.alloc();
         const e = new Constructor(this, eid);
         if (this.deferred) {
+            this._deferredEntities.set(eid, e);
             this._enqueue({ kind: 0 /* CommandKind.CreateEntity */, entity: e });
         }
         else {

package/dist/world/world.entities.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.entities.js","sourceRoot":"","sources":["../../src/world/world.entities.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAA8B,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpC,6EAA6E;IACtE,iBAAiB,CAAc,GAAQ,EAAE,gBAAsC;QACpF,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,gBAAgB,EAAE,CAAC;gBACrB,gBAAgB,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,2DAA2D;IACpD,SAAS,CAAc,GAA0B;QACtD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrF,CAAC;IAQM,MAAM,CAAc,GAA2B;QACpD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YACpC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,sDAAsD,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,2DAA2D;IACpD,gBAAgB;QACrB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;gBAClC,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC7C,IAAI,aAAa,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtD,SAAS;gBACX,CAAC;gBACD,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACvB,SAAS,EAAE,CAAC;YACd,CAAC;YACD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED,kEAAkE;IACxD,OAAO,CAAgC,WAA2B;QAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,kCAA0B,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}
+{"version":3,"file":"world.entities.js","sourceRoot":"","sources":["../../src/world/world.entities.ts"],"names":[],"mappings":"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"}

package/dist/world/world.js

@@ -1,5 +1,6 @@
 import { SilenceSource } from "../modules/relationships.js";
 import { IdentityModule } from "../modules/identity.js";
+import { ImplementsModule } from "../modules/implements.js";
 import { PipelineModule } from "../modules/pipeline.js";
 import { RelationshipsModule } from "../modules/relationships.js";
 import { SingletonModule } from "../modules/singleton.js";
@@ -33,7 +34,13 @@ export class World extends Pipeline {
         this.component(SilenceSource).onRemove((entity) => entity.get(Query)?._clearSilence());
         this.component(Query).onRemove((_entity, query) => query.destroy());
         this.component(System).onRemove((_entity, system) => system.destroy());
-        [IdentityModule, SingletonModule, RelationshipsModule, PipelineModule].forEach((mod) => this.module(mod));
+        [
+            IdentityModule,
+            ImplementsModule,
+            SingletonModule,
+            RelationshipsModule,
+            PipelineModule,
+        ].forEach((mod) => this.module(mod));
     }
 }
 //# sourceMappingURL=world.js.map

package/dist/world/world.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/world/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,CAAC,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CACrF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CACjB,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/world/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QACvF,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE;YACE,cAAc;YACd,gBAAgB;YAChB,eAAe;YACf,mBAAmB;YACnB,cAAc;SACf,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/world/world.queries.js

@@ -2,6 +2,7 @@ import { isQueryConfig } from "../dsl.js";
 import { Filter } from "../filter.js";
 import { Query } from "../query/index.js";
 import { getCachedTerm, getTerm, notifyComponentAdded, notifyComponentChanged, notifyComponentRemoved, notifyEntityCreated, notifyEntityDestroyed, } from "../terms/build.js";
+import { ArrayMap } from "../util/array_map.js";
 import { Storage } from "./world.storage.js";
 export class Queries extends Storage {
     constructor() {
@@ -13,7 +14,7 @@ export class Queries extends Storage {
         /** @internal Canonical DSL key -> live term. */
         this._termCache = new Map();
         /** @internal Component eid -> pinned component leaf term. */
-        this._componentTerms = new Map();
+        this._componentTerms = new ArrayMap();
         /** @internal True while the world is driving one logical frame. */
         this._frameInProgress = false;
         /** @internal True while the world is auto-building pending queries. */
@@ -66,6 +67,10 @@ export class Queries extends Storage {
     _getCachedTerm(q) {
         return getCachedTerm(this, q);
     }
+    /** @internal Return a cached term for a precomputed canonical DSL key, without creating one. */
+    _getCachedTermByKey(key) {
+        return this._termCache.get(key);
+    }
     /** @internal Drive the component leaf for a newly attached component. */
     _notifyComponentAdded(ceid, entity) {
         notifyComponentAdded(this, ceid, entity);

package/dist/world/world.queries.js.map

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

package/dist/world/world.storage.d.ts

@@ -1,7 +1,7 @@
 import type { Entity } from "../entity/index.js";
-import { type ReadonlyArrayMap } from "../util/array_map.js";
+import { type ReadonlyIterableArrayMap } from "../util/array_map.js";
 import { Pools } from "./world.pools.js";
 export declare class Storage extends Pools {
     /** Read-only view of the live entities, keyed by entity id. */
-    get entities(): ReadonlyArrayMap<Entity>;
+    get entities(): ReadonlyIterableArrayMap<Entity>;
 }

package/dist/world/world.storage.js

@@ -1,4 +1,4 @@
-import { ArrayMap } from "../util/array_map.js";
+import { ArrayMap, IterableArrayMap } from "../util/array_map.js";
 import { Pools } from "./world.pools.js";
 export class Storage extends Pools {
     constructor() {
@@ -6,12 +6,14 @@ export class Storage extends Pools {
         /**
          * @internal Entity id -> entity. Owns every live entity.
          *
-         * Backed by an {@link ArrayMap} rather than a `Map`: entity ids are dense
+         * Backed by an {@link IterableArrayMap} rather than a `Map`: entity ids are dense
          * pooled integers, so array indexing beats hashing on the lookups that run
          * per component during teardown (`world.entity(componentEid)` in
          * `Entity._destroy`) and on every `world.entity(eid)` resolution.
          */
-        this._entities = new ArrayMap();
+        this._entities = new IterableArrayMap();
+        /** @internal Entity id -> entity queued for deferred creation, not query-visible yet. */
+        this._deferredEntities = new ArrayMap();
     }
     /** Read-only view of the live entities, keyed by entity id. */
     get entities() {
@@ -20,6 +22,7 @@ export class Storage extends Pools {
     /** @internal Remove an entity from the world's entity map (called by `Entity._destroy`). */
     _unregisterEntity(entity) {
         this._entities.delete(entity.eid);
+        this._deferredEntities.delete(entity.eid);
         this._poolFor(entity.eid).free(entity.eid);
     }
 }

package/dist/world/world.storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"world.storage.js","sourceRoot":"","sources":["../../src/world/world.storage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAyB,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,MAAM,OAAO,OAAQ,SAAQ,KAAK;IAAlC;;QACE;;;;;;;WAOG;QACO,cAAS,GAAG,IAAI,QAAQ,EAAU,CAAC;IAY/C,CAAC;IAVC,+DAA+D;IAC/D,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,4FAA4F;IACrF,iBAAiB,CAAC,MAAc;QACrC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF"}
+{"version":3,"file":"world.storage.js","sourceRoot":"","sources":["../../src/world/world.storage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAiC,MAAM,sBAAsB,CAAC;AACjG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,MAAM,OAAO,OAAQ,SAAQ,KAAK;IAAlC;;QACE;;;;;;;WAOG;QACO,cAAS,GAAG,IAAI,gBAAgB,EAAU,CAAC;QAErD,yFAAyF;QAC/E,sBAAiB,GAAG,IAAI,QAAQ,EAAU,CAAC;IAavD,CAAC;IAXC,+DAA+D;IAC/D,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,4FAA4F;IACrF,iBAAiB,CAAC,MAAc;QACrC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/docs/README.md

@@ -0,0 +1,50 @@
+# vecs Documentation
+
+Single-topic guides for `@vworlds/vecs`. Each guide moves from concept to how-to to a woven
+reference, and every example uses the real public API. The exhaustive per-symbol reference is the
+JSDoc on the source in `lib/vecs/src/` — read it in your IDE; these guides carry the concepts,
+the idioms, and the reference tables you reach for while designing.
+
+## Reading order
+
+Read in this order the first time through:
+
+1. [Getting started](./getting-started.md) — install, first world, first system, first tick.
+2. [Concepts](./concepts.md) — the mental model: world, entity, component, system, query.
+3. [Execution model](./execution-model.md) — phases, the pipeline, deferred mutation, reactive
+   routing. Read this before designing anything non-trivial.
+4. Subsystem guides, in any order:
+   - [Components](./components.md) — registration, hooks, exclusivity, cleanup policies,
+     interfaces, singletons.
+   - [Entities](./entities.md) — creation, lookup, the component API, lifecycle.
+   - [Systems](./systems.md) — membership, reactive callbacks, `each`/`run`, cadence, injection.
+   - [Queries and filters](./queries-and-filters.md) — the query DSL, live queries, one-shot
+     filters, grouped queries, `Bitset`.
+   - [Relationships](./relationships.md) — entity-to-entity links, hierarchy, cleanup cascades.
+   - [Modules](./modules.md) — packaging features, composition, the built-in modules.
+5. [Design guide](./design-guide.md) — opinionated patterns and anti-patterns distilled from real
+   designs. Read it once you know the machinery.
+6. [Utilities](./utilities.md) — helper classes exported by `@vworlds/vecs` but not part of the ECS
+   lifecycle model.
+
+Keep the [Glossary](./glossary.md) at hand for terminology.
+
+## Map
+
+| Guide                                              | Covers                                                                                       |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| [getting-started.md](./getting-started.md)         | A runnable tutorial from `npm install` to a ticking world.                                   |
+| [concepts.md](./concepts.md)                       | The core vocabulary and how the pieces relate.                                               |
+| [execution-model.md](./execution-model.md)         | `world.progress`, the 8 built-in phases, deferred commands, flush boundaries, event routing. |
+| [components.md](./components.md)                   | `world.component`, hooks, exclusive groups, `CleanupPolicy`, `Implements`, `Singleton`.      |
+| [entities.md](./entities.md)                       | `world.entity`, `add`/`set`/`get`/`remove`/`destroy`, deferred read semantics.               |
+| [systems.md](./systems.md)                         | `world.system`, `with`/`without`, `enter`/`update`/`exit`, `each`/`run`, tick sources.       |
+| [queries-and-filters.md](./queries-and-filters.md) | `QueryDSL`, `Query`, `Filter`, `groupBy`, `ignoreSource`.                                    |
+| [relationships.md](./relationships.md)             | `Relationship`, `ChildOf`/`DependsOn`, `parent`/`children`, `Traversable`, cascades.         |
+| [modules.md](./modules.md)                         | `Module<Config>`, `world.module`, composition, built-in modules.                             |
+| [design-guide.md](./design-guide.md)               | Patterns, anti-patterns, and a Phaser render-layer case study.                               |
+| [utilities.md](./utilities.md)                     | Public helper classes: `Events`, `ArrayMap`, `IterableArrayMap`, plus `Bitset` cross-ref.    |
+| [glossary.md](./glossary.md)                       | ECS and vecs terminology.                                                                    |
+
+Networking (wire encoding with `@type`, protocol component ordering, replication) lives in the
+`@vworlds/vecs-wire` and `@vworlds/vecs-protocol` packages and is only cross-referenced here.