@vworlds/vecs 1.0.49 → 1.0.51

package/README.md

@@ -59,6 +59,8 @@ world.progress(performance.now(), 16); // call once per frame
 
 ## Documentation
 
+For Node clients that need replicated Phaser poses, see [Headless clients](../vecs-phaser-client/README.md#headless-clients).
+
 The full documentation lives in [`docs/`](./docs/README.md). Recommended reading order:
 
 1. [Getting started](./docs/getting-started.md) — install to first ticking world.

package/dist/modules/snapshot_types.d.ts

@@ -52,12 +52,14 @@ export declare class OnSnapshot extends Relationship {
 }
 /**
  * Default snapshot policy: construct a fresh instance of the component class
- * and clone the source instance's own enumerable fields onto it.
+ * and deep-copy the source instance's own enumerable fields onto it.
  *
- * Shallow, and therefore exactly as aliasing-sensitive as `set`: a component
- * holding a nested object shares it with the source until something copies it.
- * A type that must not carry runtime handles across worlds needs its own
- * policy — see {@link CustomSnapshot}.
+ * The copy covers primitives, arrays, plain objects, `Map`, `Set`, `Date`,
+ * `ArrayBuffer` and typed arrays, so the destination never aliases a nested
+ * value of the source. Anything else (a class instance, a function, a symbol)
+ * throws at capture with the component and field path. A type that holds such
+ * a value, or that must not carry runtime handles across worlds, needs its own
+ * policy — see {@link CustomSnapshot} and {@link DontSnapshot}.
  */
 export declare class ClonePublic {
 }

package/dist/modules/snapshot_types.js

@@ -48,12 +48,14 @@ export class OnSnapshot extends Relationship {
 }
 /**
  * Default snapshot policy: construct a fresh instance of the component class
- * and clone the source instance's own enumerable fields onto it.
+ * and deep-copy the source instance's own enumerable fields onto it.
  *
- * Shallow, and therefore exactly as aliasing-sensitive as `set`: a component
- * holding a nested object shares it with the source until something copies it.
- * A type that must not carry runtime handles across worlds needs its own
- * policy — see {@link CustomSnapshot}.
+ * The copy covers primitives, arrays, plain objects, `Map`, `Set`, `Date`,
+ * `ArrayBuffer` and typed arrays, so the destination never aliases a nested
+ * value of the source. Anything else (a class instance, a function, a symbol)
+ * throws at capture with the component and field path. A type that holds such
+ * a value, or that must not carry runtime handles across worlds, needs its own
+ * policy — see {@link CustomSnapshot} and {@link DontSnapshot}.
  */
 export class ClonePublic {
 }

package/dist/modules/snapshot_types.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot_types.js","sourceRoot":"","sources":["../../src/modules/snapshot_types.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,uBAAuB;AACvB,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,4BAA4B;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAoBpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,UAAW,SAAQ,YAAY;IAA5C;;QACE;;;WAGG;QACI,YAAO,GAAgC,SAAS,CAAC;QAExD;;;WAGG;QACI,gBAAW,GAAoC,SAAS,CAAC;IAClE,CAAC;CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAW;CAAG;AAE3B;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;CAAG;AAE5B;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;CAAG;AAkB9B,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAA2B,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAA2B,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,MAA0B,EAC1B,OAAyB,EACzB,WAAiC;IAEjC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;IAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACvC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAClC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;QACxB,OAAO,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QACxD,WAAW,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KACjE,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,IAAmB;IACtE,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,CAA2B,CAAC;IAC7F,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,CAAC;QAC5E,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,CAAC;QACvD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,WAAW,CAAC,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,KAAK,CAAC,IAAI,mEAAmE,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,WAAW,EAAE,WAAW,CAAC,WAAW;KACrC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"snapshot_types.js","sourceRoot":"","sources":["../../src/modules/snapshot_types.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,uBAAuB;AACvB,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,4BAA4B;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAoBpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,UAAW,SAAQ,YAAY;IAA5C;;QACE;;;WAGG;QACI,YAAO,GAAgC,SAAS,CAAC;QAExD;;;WAGG;QACI,gBAAW,GAAoC,SAAS,CAAC;IAClE,CAAC;CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;CAAG;AAE3B;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;CAAG;AAE5B;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;CAAG;AAkB9B,+EAA+E;AAC/E,MAAM,CAAC,MAAM,YAAY,GAA2B,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAA2B,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,MAA0B,EAC1B,OAAyB,EACzB,WAAiC;IAEjC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;IAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACvC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAClC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;QACxB,OAAO,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QACxD,WAAW,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KACjE,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,IAAmB;IACtE,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,CAA2B,CAAC;IAC7F,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,CAAC;QAC5E,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,CAAC;QACvD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,WAAW,CAAC,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,KAAK,CAAC,IAAI,mEAAmE,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,WAAW,EAAE,WAAW,CAAC,WAAW;KACrC,CAAC;AACJ,CAAC"}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -27,12 +27,5 @@
     "type": "git",
     "url": "https://github.com/vworlds/vecs",
     "directory": "lib/vecs"
-  },
-  "lint-staged": {
-    "*.ts": [
-      "prettier --write",
-      "eslint --fix"
-    ],
-    "*.md": "prettier --write"
   }
 }

package/dist/world/world.d.ts

@@ -11,6 +11,8 @@ import { type WorldOptions } from "./world.base.js";
  * 2. **Build the pipeline** — attach systems to phase entities with
  *    `DependsOn`, or call {@link setPipeline} with a custom query spec.
  * 3. **Run loop** — call {@link progress} once per frame.
+ * 4. **Dispose** — call {@link dispose} when the world is finished, so the
+ *    `remove` hooks of the components its entities carry release what they own.
  *
  * ## Deferred mode
  *

package/dist/world/world.disposal.d.ts

@@ -0,0 +1,69 @@
+import { Transfers } from "./world.transfers.js";
+import type { World } from "./world.js";
+/**
+ * World teardown. It is a layer of its own rather than a method of `World`, because the layers
+ * below pass `this` to parameters typed `World`, which only holds while `World` adds no members
+ * to `Pipeline`.
+ */
+export declare class Disposal extends Transfers {
+    /** `true` once {@link dispose} has started: what makes it idempotent and safe to re-enter. */
+    private _disposeStarted;
+    /**
+     * End the world's life: destroy every entity the application and its modules created, so the
+     * `remove` hooks of the components they carry release what those components own (render
+     * objects, handles, timers). Call it when the world is finished — a scene or route change, a
+     * hot reload — and drop the reference afterwards.
+     *
+     * Each entity goes through the ordinary destroy path, as if it had received
+     * {@link Entity.destroy}: every component's `remove` hook fires exactly once, cleanup policies
+     * and relationship cascades (`ChildOf`, `OwnedTarget`, `CleanupPolicy.Delete`) run as they
+     * always do, and an entity a cascade or a hook has already destroyed is skipped, never
+     * destroyed twice.
+     *
+     * ## What stays
+     *
+     * The infrastructure the world needs to stay coherent is not destroyed:
+     *
+     * - component and module entities (every {@link Component}),
+     * - the entities behind queries and systems (they carry the {@link Query} component), and
+     * - phase entities (they carry the {@link Phase} component).
+     *
+     * What those entities hold stays too: data stored on a component entity (a singleton set with
+     * {@link set}) and any entity they still carry as a component key, which cannot be destroyed
+     * while it is in use. Release such data yourself. {@link clearAllEntities} is the full wipe,
+     * infrastructure included.
+     *
+     * ## Order
+     *
+     * No order is specified among unrelated entities, so do not make a hook depend on one. The one
+     * guarantee is that an entity used as a component key is destroyed after every entity that
+     * carries it, because destroying it earlier would throw under the default cleanup policy.
+     *
+     * ## Pending commands
+     *
+     * Commands queued by an enclosing deferred scope are neither flushed early nor discarded: they
+     * run first, in order, and the destruction follows them in the same queue, so a hook still fires
+     * once per component instance however it was removed. An entity whose creation is still queued
+     * is created, then destroyed. At top level nothing is queued and `dispose()` returns with the
+     * application's entities gone. Called from a system, a hook or a {@link defer} block, it queues
+     * the destruction like any `destroy()` in that situation, and the destruction completes when
+     * the queue next drains: right after the running system, or at the end of the `defer` block.
+     *
+     * ## After disposal
+     *
+     * A disposed world must not be used again. Nothing enforces it — no other method checks, so
+     * `entity()` and `progress()` stay as cheap as ever — but the world has no application state
+     * left to run on. Calling `dispose()` again, from a hook included, does nothing. A hook that
+     * creates entities while the world is being disposed leaves them behind. A system's `exit`
+     * callback only queues its event, and a disposed world never runs the system again, so release
+     * resources in `remove` hooks, which fire during the call. A hook that throws propagates out of
+     * the call and leaves the world partial, as it does from any destroy: treat it as a programming
+     * error.
+     */
+    dispose(this: World): void;
+    /**
+     * The entities {@link dispose} destroys, in an order that lets every destroy succeed: those the
+     * application created, with each one used as a component key after its carriers.
+     */
+    private _destroyOrder;
+}

package/dist/world/world.disposal.js

@@ -0,0 +1,146 @@
+import { Component } from "../component.js";
+import { Phase } from "../modules/pipeline.js";
+import { Query } from "../query/index.js";
+import { Transfers } from "./world.transfers.js";
+/**
+ * World teardown. It is a layer of its own rather than a method of `World`, because the layers
+ * below pass `this` to parameters typed `World`, which only holds while `World` adds no members
+ * to `Pipeline`.
+ */
+export class Disposal extends Transfers {
+    constructor() {
+        super(...arguments);
+        /** `true` once {@link dispose} has started: what makes it idempotent and safe to re-enter. */
+        this._disposeStarted = false;
+    }
+    /**
+     * End the world's life: destroy every entity the application and its modules created, so the
+     * `remove` hooks of the components they carry release what those components own (render
+     * objects, handles, timers). Call it when the world is finished — a scene or route change, a
+     * hot reload — and drop the reference afterwards.
+     *
+     * Each entity goes through the ordinary destroy path, as if it had received
+     * {@link Entity.destroy}: every component's `remove` hook fires exactly once, cleanup policies
+     * and relationship cascades (`ChildOf`, `OwnedTarget`, `CleanupPolicy.Delete`) run as they
+     * always do, and an entity a cascade or a hook has already destroyed is skipped, never
+     * destroyed twice.
+     *
+     * ## What stays
+     *
+     * The infrastructure the world needs to stay coherent is not destroyed:
+     *
+     * - component and module entities (every {@link Component}),
+     * - the entities behind queries and systems (they carry the {@link Query} component), and
+     * - phase entities (they carry the {@link Phase} component).
+     *
+     * What those entities hold stays too: data stored on a component entity (a singleton set with
+     * {@link set}) and any entity they still carry as a component key, which cannot be destroyed
+     * while it is in use. Release such data yourself. {@link clearAllEntities} is the full wipe,
+     * infrastructure included.
+     *
+     * ## Order
+     *
+     * No order is specified among unrelated entities, so do not make a hook depend on one. The one
+     * guarantee is that an entity used as a component key is destroyed after every entity that
+     * carries it, because destroying it earlier would throw under the default cleanup policy.
+     *
+     * ## Pending commands
+     *
+     * Commands queued by an enclosing deferred scope are neither flushed early nor discarded: they
+     * run first, in order, and the destruction follows them in the same queue, so a hook still fires
+     * once per component instance however it was removed. An entity whose creation is still queued
+     * is created, then destroyed. At top level nothing is queued and `dispose()` returns with the
+     * application's entities gone. Called from a system, a hook or a {@link defer} block, it queues
+     * the destruction like any `destroy()` in that situation, and the destruction completes when
+     * the queue next drains: right after the running system, or at the end of the `defer` block.
+     *
+     * ## After disposal
+     *
+     * A disposed world must not be used again. Nothing enforces it — no other method checks, so
+     * `entity()` and `progress()` stay as cheap as ever — but the world has no application state
+     * left to run on. Calling `dispose()` again, from a hook included, does nothing. A hook that
+     * creates entities while the world is being disposed leaves them behind. A system's `exit`
+     * callback only queues its event, and a disposed world never runs the system again, so release
+     * resources in `remove` hooks, which fire during the call. A hook that throws propagates out of
+     * the call and leaves the world partial, as it does from any destroy: treat it as a programming
+     * error.
+     */
+    dispose() {
+        if (this._disposeStarted) {
+            return;
+        }
+        this._disposeStarted = true;
+        // The destroys are queued commands, as `Entity.destroy()` makes them in a deferred scope, so a
+        // queue that is already filling runs ahead of them. At top level this scope drains them now.
+        this.defer(() => {
+            for (const entity of this._destroyOrder()) {
+                this._enqueue({ kind: 4 /* CommandKind.Destroy */, entity });
+            }
+        });
+    }
+    /**
+     * The entities {@link dispose} destroys, in an order that lets every destroy succeed: those the
+     * application created, with each one used as a component key after its carriers.
+     */
+    _destroyOrder() {
+        // `getEntity` rather than `entity`: `clearAllEntities()` unregisters these components.
+        const queryEid = this.getEntity(Query)?.eid;
+        const phaseEid = this.getEntity(Phase)?.eid;
+        const isInfrastructure = (entity) => entity instanceof Component ||
+            (queryEid !== undefined && entity.has(queryEid)) ||
+            (phaseEid !== undefined && entity.has(phaseEid));
+        const entities = this._entities.values();
+        // In a deferred scope an entity created earlier is only queued, not registered yet. Its
+        // creation runs ahead of the destroy that is queued after it.
+        for (const command of this._commandQueue) {
+            if (command.kind === 0 /* CommandKind.CreateEntity */ &&
+                !command.entity.destroyed &&
+                this._entities.get(command.entity.eid) !== command.entity) {
+                entities.push(command.entity);
+            }
+        }
+        return carriersFirst(entities.filter((entity) => !isInfrastructure(entity)), isInfrastructure);
+    }
+}
+/**
+ * Order `entities` so that an entity used as a component key follows every entity that carries it.
+ *
+ * A key destroyed while still carried throws under the default cleanup policy, so carriers go
+ * first. A key that something outside `entities` carries, which is infrastructure in practice, or
+ * that is caught in a cycle, cannot be ordered and is left out: destroying it would throw or strip
+ * the infrastructure.
+ */
+function carriersFirst(entities, isInfrastructure) {
+    const ordered = [];
+    const keys = new Set();
+    for (const entity of entities) {
+        if (entity.instanceCount() === 0) {
+            ordered.push(entity);
+        }
+        else {
+            keys.add(entity);
+        }
+    }
+    let progressed = keys.size > 0;
+    while (progressed) {
+        progressed = false;
+        for (const key of keys) {
+            if (!isCarried(key, keys, isInfrastructure)) {
+                ordered.push(key);
+                keys.delete(key);
+                progressed = true;
+            }
+        }
+    }
+    return ordered;
+}
+/** Whether `key` is still carried by another key that waits to be ordered, or by infrastructure. */
+function isCarried(key, waiting, isInfrastructure) {
+    for (const carrier of key.meta._carriers ?? []) {
+        if (carrier !== key && (waiting.has(carrier) || isInfrastructure(carrier))) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=world.disposal.js.map

package/dist/world/world.disposal.js.map

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

package/dist/world/world.js

@@ -19,6 +19,8 @@ import { Pipeline } from "./world.pipeline.js";
  * 2. **Build the pipeline** — attach systems to phase entities with
  *    `DependsOn`, or call {@link setPipeline} with a custom query spec.
  * 3. **Run loop** — call {@link progress} once per frame.
+ * 4. **Dispose** — call {@link dispose} when the world is finished, so the
+ *    `remove` hooks of the components its entities carry release what they own.
  *
  * ## Deferred mode
  *

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,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,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3E;YACE,cAAc;YACd,gBAAgB;YAChB,eAAe;YACf,mBAAmB;YACnB,2EAA2E;YAC3E,sEAAsE;YACtE,qDAAqD;YACrD,cAAc;YACd,cAAc;SACf,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,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,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACjC,YAAmB,UAAwB,EAAE;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3E;YACE,cAAc;YACd,gBAAgB;YAChB,eAAe;YACf,mBAAmB;YACnB,2EAA2E;YAC3E,sEAAsE;YACtE,qDAAqD;YACrD,cAAc;YACd,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.pipeline.d.ts

@@ -2,8 +2,8 @@ import { type QuerySpec } from "../dsl.js";
 import { Query } from "../query/index.js";
 import { System } from "../system.js";
 import type { WorldOptions } from "./world.base.js";
-import { Transfers } from "./world.transfers.js";
-export declare class Pipeline extends Transfers {
+import { Disposal } from "./world.disposal.js";
+export declare class Pipeline extends Disposal {
     constructor(options?: WorldOptions);
     /** Open a new frame and evaluate every registered tick source once. */
     beginFrame(delta: number): void;

package/dist/world/world.pipeline.js

@@ -1,7 +1,7 @@
 import { System } from "../system.js";
 import { ALWAYS_TICK_SOURCE } from "../timer.js";
-import { Transfers } from "./world.transfers.js";
-export class Pipeline extends Transfers {
+import { Disposal } from "./world.disposal.js";
+export class Pipeline extends Disposal {
     constructor(options = {}) {
         super(options);
         /** @internal Flat system execution pipeline, rebuilt from `_pipelineQuery`. */

package/dist/world/world.pipeline.js.map

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

package/docs/README.md

@@ -16,7 +16,8 @@ Read in this order the first time through:
 4. Subsystem guides, in any order:
    - [Components](./components.md) — registration, hooks, traits, exclusivity, cleanup policies,
      interfaces, singletons.
-   - [Entities](./entities.md) — creation, lookup, the component API, relationship targets, lifecycle.
+   - [Entities](./entities.md) — creation, lookup, the component API, relationship targets, lifecycle,
+     disposing a world.
    - [Systems](./systems.md) — membership, reactive callbacks, callback options, `each`/`run`, cadence,
      component and relationship injection.
    - [Queries and filters](./queries-and-filters.md) — the query DSL, live queries, one-shot
@@ -35,13 +36,15 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 
 ## Map
 
+For Node clients that need replicated Phaser poses, see [Headless clients](../../vecs-phaser-client/README.md#headless-clients).
+
 | 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)                   | Component registration, hooks, traits, exclusivity, cleanup, aliases, and singletons.        |
-| [entities.md](./entities.md)                       | Entity creation, component mutation, relationship targets, lifecycle, deferred reads.        |
+| [entities.md](./entities.md)                       | Entity creation, mutation, relationship targets, lifecycle, disposal, deferred reads.        |
 | [systems.md](./systems.md)                         | `world.system`, callbacks, injection, ordering, cadence, and tick sources.                   |
 | [queries-and-filters.md](./queries-and-filters.md) | `QueryDSL`, `Query`, `Filter`, `groupBy`, `ignoreSource`.                                    |
 | [relationships.md](./relationships.md)             | Relationships, target creation, projection and ownership, hierarchy, traversal, and cleanup. |
@@ -56,7 +59,9 @@ sessions, and the client world) lives in the `@vworlds/vecs-wire`, `@vworlds/vec
 `@vworlds/vecs-server`, and `@vworlds/vecs-client` packages:
 
 - [Remote procedure calls](../../vecs-protocol/docs/rpc.md) — the call channel and typed errors.
+- [State diffs](../../vecs-protocol/docs/state-diffs.md) — what a diff carries, the order a client
+  applies it in, and how a reused entity id stays unambiguous.
 - [Sessions and caller context](../../vecs-server/docs/sessions.md) — per-connection RPC context,
   `closeSession`, and exactly-once teardown.
-- [Client world](../../vecs-client/docs/client-world.md) — replication, `invoke`/`listen`, and
-  disposal.
+- [Client world](../../vecs-client/docs/client-world.md) — replication, render time,
+  `invoke`/`listen`, and disposal.

package/docs/components.md

@@ -69,8 +69,22 @@ Entity ids are drawn from configurable pools. The defaults
 Pass `idPools` to the `World` constructor to change ranges (each entry is an `IdPoolConfig` with
 `name`, `min`, optional `max`, and optional `reuseWaitFrames`). Freed ids wait
 `reuseWaitFrames` frames (default `DEFAULT_ID_REUSE_WAIT_FRAMES = 16`) before reuse, so an id
-released this frame is not immediately recycled. `world.peekNextEid(poolName)` returns the next id
-a pool would allocate without reserving it. Id 0 is reserved.
+released this frame is not immediately recycled. A frame is one `beginFrame()`, so one
+`progress()`; a wait of `0` frees the id at once. Once the wait is over, allocation hands out free
+ids before never-used ones, lowest first, so a released id is recycled by one of the next entities
+created. A `ClientWorld` sets the wait to `0` for the ids of replicated entities and keeps the
+default for its local ones. A `ServerWorld` allocates its replicated entities from the `entity` pool,
+and holds a freed id for at least `historyFrames + 1` frames (65 by default) whatever the wait
+asks for, so the frame that removed an entity has left every session's history before its id comes
+back (see [Reusing entity ids](../../vecs-server/docs/sessions.md#reusing-entity-ids)). The
+`networkEntityReuseWaitFrames` option of the networked worlds sets the wait of the pool that holds
+the replicated entities: `entity` for a server, `network_entity` for a client. A diff that removes
+an entity and snapshots a new one under the same id is read in a fixed order, which is how a client
+tells the two apart (see [State diffs](../../vecs-protocol/docs/state-diffs.md)). A recycled id is
+why a stored id is not a safe link between entities
+(see [Link with edges, not stored ids](./relationships.md#link-with-edges-not-stored-ids)).
+`world.peekNextEid(poolName)` returns the next id a pool would allocate without reserving it. Id 0
+is reserved.
 
 ## Hooks: component and relationship edges
 
@@ -103,6 +117,26 @@ command is applied (see [Execution model](./execution-model.md#reactive-routing)
 resource management and cross-cutting reactions that aren't worth a system; use systems when the
 reaction belongs to a phase.
 
+`remove` also fires when the owning entity is destroyed, and `entity.destroyed` is already `true`
+inside the hook. A dying entity takes no writes: `add`, `set`, `remove`, `modified` and `attach`
+are dropped without an error, and `ensure` throws. Releasing a resource needs no check. A hook that
+also writes to its own entity must skip the write when `entity.destroyed`, and that guard is the
+right one here (relationship hooks follow the same rule, see
+[Relationships — edge hooks](./relationships.md#edge-hooks)):
+
+```ts
+class Shield {}
+class Stats {
+  armor = 0;
+}
+
+world.component(Shield).on("remove", (entity) => {
+  if (!entity.destroyed) {
+    entity.ensure(Stats, (stats) => (stats.armor -= 10)); // throws on a dying entity
+  }
+});
+```
+
 Multiple handlers may be registered for the same event: they fire in registration
 order. Call `on(event, handler)` to append, `on(event, handler, true)` to
 prepend, and `off(event, handler)` to remove a handler by reference. All three
@@ -129,6 +163,7 @@ world.component(Orange).set(Implements, { interfaces: [Fruit] });
 | `Traversable`     | Exclusive relationships                      | Maintains hierarchy depth for cascade ordering                               |
 | `OwnedTarget`     | Exclusive relationships other than `ChildOf` | Owns each explicit target through `ChildOf` and destructive edge replacement |
 | `OneOf`           | Relationships                                | Constrains each target to be a direct `ChildOf` child of a declared parent   |
+| `With`            | A component and a target of the same kind    | Adding the component also adds the target (the same targets, for edges)      |
 
 Traits declare policy; their built-in modules install the hooks and maintain the metadata that
 enforce it. Configure traits in feature-module setup rather than opportunistically inside systems.
@@ -142,6 +177,11 @@ Do not assume all traits have the same lifecycle:
   `ChildOf` child of the declared parent.
 - `Traversable` backfills existing relationship instances.
 - Setting or removing `Implements` recomputes interface aliases.
+- Add `With` before the component is in use, as `world.component(X).add(With, world.component(Y))`.
+  It is irrevocable, both must be plain components or both relationships, and it only brings `Y`
+  along: an existing `Y` is left as it is, and removing `X` does not remove `Y`. On a `ClientWorld`,
+  a network removal of `Y` is skipped while `X` is on the entity (see
+  [Applying a frame](../../vecs-client/docs/client-world.md#applying-a-frame)).
 
 Treat traits as setup policy unless their documentation explicitly supports runtime changes. Before
 writing custom component-type bookkeeping, check whether an existing trait already expresses the

package/docs/design-guide.md

@@ -133,11 +133,12 @@ entity.attach(obj); // the GameObject is now a component, keyed by its class
 world.component(Phaser.GameObjects.Arc).on("remove", (_entity, obj) => obj.destroy());
 ```
 
-`onRemove` (below) releases the resource whenever it leaves — whether removed explicitly or
-because the entity was destroyed. When several resource types should share one cleanup hook or be
-queried together, give them a common **interface** with `Implements` (see §7 and the §10 case
-study). A plain wrapper component (`class Handle { obj }`) is still fine when you need extra fields
-beside the resource.
+`onRemove` (below) releases the resource whenever it leaves — whether removed explicitly,
+because the entity was destroyed, or because the world was disposed (`world.dispose()` destroys
+every entity the application created; see [Disposing a world](./entities.md#disposing-a-world)).
+When several resource types should share one cleanup hook or be queried together, give them a
+common **interface** with `Implements` (see §7 and the §10 case study). A plain wrapper component
+(`class Handle { obj }`) is still fine when you need extra fields beside the resource.
 
 ### Component lifecycle hooks: `onAdd` / `onSet` / `onRemove`
 
@@ -176,6 +177,7 @@ world.component(Orange).set(Implements, { interfaces: [Fruit] });
 | `Traversable`     | An exclusive relationship hierarchy needs depth or cascade ordering                |
 | `OwnedTarget`     | An exclusive relationship owns its explicitly added target                         |
 | `OneOf`           | A relationship's targets must be direct children of a declared parent (enum-style) |
+| `With`            | Adding one component should bring another along, as a companion it does not own    |
 
 Traits declare policy; modules implement it through hooks and metadata. Configure them in module
 setup, not inside systems. Lifecycle differs by trait: `OwnedTarget` and `Singleton` are setup-time
@@ -183,6 +185,18 @@ policy, `Traversable` backfills, and `Implements` recomputes declarations. Do no
 dynamically removable. See the [Components guide](./components.md#component-traits-policy-on-component-entities)
 for the full model and custom-trait guidance.
 
+`With` is a pair-form trait: `world.component(Motion).add(With, world.component(Position))` adds a
+`Position` whenever a `Motion` is added. It only brings the companion along: removing `Motion` does
+not remove `Position`, and a `Position` the entity already holds is left as it is. A networked
+client has one more rule, because the server decides what a client replicates but the client decides
+what it derives. **`ClientWorld.apply` skips a network removal of a component that another
+component present on the entity brings through `With`**, so a server can swap the source of a
+client-local component in one diff, say a streamed `Position` for a dead-reckoned `Motion`, and the
+entity never goes without it: no `remove` hook fires, and the queries and `DrawBy` children that
+match on it never see it leave. A bringer that the same diff sets counts as present. The entity-destroy
+path is unaffected, and a relationship is removed as sent (see
+[Applying a frame](../../vecs-client/docs/client-world.md#applying-a-frame)).
+
 ### Exclusive component groups
 
 `world.setExclusiveComponents(A, B, C)` declares a mutually exclusive set: setting one
@@ -268,6 +282,23 @@ classes or DSL objects (`{ all: [...] }`, `{ any: [...] }`, `{ parent: X }`, `{
 > `.with(...)`, `.without(...)`, and `.update(C)` own membership. `.update(C)` watches change events
 > and also requires `C`, so `.with(A).update(C)` matches entities carrying both `A` and `C`.
 
+**`.without` is not free.** `.without(X)` is `.with({ not: X })`: a `not` term holds every live
+entity that lacks `X`, a world-sized set, and the query intersects it with its positive terms. The
+exclusion does not run over the positive terms' candidates. Vecs seeds that set with one scan of
+the world when the term is first built, then adds each new entity to it, removes each destroyed
+entity from it, and flips an entity in or out when `X` is added to it or removed from it. Changes
+to `X`'s data cost nothing. The term is shared by every query that excludes the same `X`, so the
+upkeep is paid once per distinct exclusion, plus one membership check per query that uses it.
+
+- Add `.without(X)` only when the exclusion is needed, and put positive terms next to it: they keep
+  the query's members and callbacks small. A query made only of `.without` terms tracks every
+  entity in the world.
+- The creation pattern `.with(NewShape).without(Phaser.GameObjects.NewKind).enter(...)` relies on
+  that narrowing. The positive term limits the members to the few entities that just got
+  `NewShape`, while the exclusion keeps those that already have a display object from entering.
+
+Details: [Queries and filters](./queries-and-filters.md#the-cost-of-not-and-without).
+
 ### Reactive callbacks: `enter` / `update` / `exit`
 
 - **`enter`** — fires once when an entity _becomes_ a member. Use it for one-time setup
@@ -281,6 +312,14 @@ classes or DSL objects (`{ all: [...] }`, `{ any: [...] }`, `{ parent: X }`, `{
   Its injected components are read from a **snapshot captured at exit time**, so they're still
   resolvable even though they're being removed.
 
+**Repeated writes in one tick.** Vecs never merges `update` events, so a callback fires once per
+routed write. `entity.modified(C)` and `entity.getMut(C)` coalesce through the entity's dirty bit:
+repeated calls before the queued command drains give one `update`. Each `entity.set(C, …)` queues
+its own command and routes its own `update`, so three `set` calls give three callbacks. Write in
+place plus `modified` (or `getMut`) to get one callback per tick, or compare before `set`. When
+producers already use `modified`/`getMut`, do not add a defensive per-tick dedupe or batching layer
+on the consumer side. See [Systems](./systems.md#repeated-writes-in-one-tick).
+
 Choose `onEnter: true` by asking who owns the initial value:
 
 - Use **`onEnter: true`** for projection / sync callbacks: copying ECS data into a runtime object,
@@ -338,7 +377,8 @@ Components listed in the inject tuple but **not** guaranteed by `.with(...)` res
 ### `each` vs reactive — don't scan when you can react
 
 - **`.each([...], cb)`** iterates **every matching entity every tick**. Use it only when you
-  genuinely need a per-frame sweep over all members.
+  genuinely need a per-frame sweep over all members. An `.each` must justify running every tick: a
+  body that returns early for most members is a reactive system or a narrower query in disguise.
 - **Reactive `enter`/`update`/`exit`** fire only on change. For "copy A→B when A changes,"
   reactive `.update(A)` touches _nothing_ on idle entities, where `.each` would scan them all.
 
@@ -350,6 +390,28 @@ Components listed in the inject tuple but **not** guaranteed by `.with(...)` res
 .with(PhysicsPosition, RenderPosition).update(PhysicsPosition, (e, p) => e.set(RenderPosition, { x: p.x, y: p.y }));
 ```
 
+When the work really is per-tick (a held input, a cooldown, a charge), narrow the query with a tag
+or component that exists **only while the work is live**, instead of sweeping every candidate and
+returning early. A reactive `update` on the intent adds and removes the marker:
+
+```ts
+// ❌ visits every shooter every tick; most return at once
+.with(Weapon).each([Weapon], (e, [w]) => { if (!e.has(TriggerHeld)) return; /* fire */ });
+
+// ✅ the cadence system matches only entities that are firing right now
+world.system("TriggerIntent").with(Weapon).update(FireIntent, (e, intent) =>
+  intent.held ? e.add(Firing) : e.remove(Firing));
+world.system("Fire").with(Weapon, Firing).interval(0.1).each([Weapon], (e, [w]) => { /* fire */ });
+```
+
+For a countdown, do not write a bespoke "tick every timer" system over all entities. Vecs has no
+per-entity timer component: `interval`, `rate` and `tickSource` (see below) throttle _systems_.
+Model the window as an owned helper entity, an `Exclusive` + `OwnedTarget` relationship target that
+carries the deadline (see [Owned target entities](#owned-target-entities-entity-valued-properties)).
+Its presence is the window: an `.each` over the helper entities visits only open windows, and
+destroying a helper ends its window and removes the edge through the relationship's cleanup policy,
+so no remove hook or flag is needed.
+
 ### `run` and `interval`
 
 - **`.run(cb)`** — a system with no per-entity query; the body runs once per tick. For
@@ -702,6 +764,11 @@ The lifecycle follows from the relationship and trait:
 | `player.remove(Inventory)`            | Destroys every current target                                             |
 | Destroy `player`                      | `ChildOf` destroys the inventory                                          |
 
+Prefer this to a component field that holds the child entity, with an `onRemove` hook that destroys
+it. Every operation that drops the edge destroys the child, and destroying the child directly
+removes the edge, so the owner needs no hook and holds nothing that can go stale (see
+[Link with edges, not stored ids](./relationships.md#link-with-edges-not-stored-ids)).
+
 Inside deferred execution, keep and mutate the target you created; the queued edge is not visible
 through `target` until flush:
 
@@ -749,6 +816,9 @@ system after whatever produces the entity/companion.
 | A god component with many optional fields                              | Split into small single-purpose components; absence encodes "not applicable."                                                                        |
 | A large nested `inventory`, `brain`, or progression object             | Use an owned target entity when the subobject needs its own components, systems, and lifecycle.                                                      |
 | A side `Map<ownerEid, SubsystemState>`                                 | Create a target entity and add an explicit edge; use `Exclusive` + `OwnedTarget` only for destructive ownership.                                     |
+| An `eid` or `Entity` stored in a component field as a link             | A relationship edge: vecs cleans it up; a stored eid can name another entity once reused ([why](./relationships.md#link-with-edges-not-stored-ids)). |
+| A component field holding a child entity, destroyed in `onRemove`      | `Exclusive` + `OwnedTarget`: dropping the edge destroys the child; no hook, no stale field ([§7](#owned-target-entities-entity-valued-properties)).  |
+| `entity.destroyed` guards on an entity looked up from a stored link    | A missing edge: replace the link. Keep guards for event buffers and dying-entity hooks ([why](./relationships.md#link-with-edges-not-stored-ids)).   |
 | `OwnedTarget` on `CurrentEnemy`, `InCell`, `Team`, or shared state     | Use a normal relationship; replacing or removing an owned edge destroys its target.                                                                  |
 | One owned target used as a collection                                  | Use multiple child/item entities; owned targets model zero-or-one aggregates.                                                                        |
 | Duplicated `enter` + `update` doing the same thing                     | One `update({ watch: C, onEnter: true })` when update owns initialization.                                                                           |
@@ -774,11 +844,28 @@ system after whatever produces the entity/companion.
   replicate a networked component. A writer that runs every tick and copies a value into a networked
   or watched component (simulation output, a derived pose) should compare first and write only when
   the value changed (see §7). An in-place assignment without `modified` notifies nobody.
+- **`getMut` marks the component modified even without a callback and even if you write nothing.**
+  Calling it every tick fires `onSet`, `update` watchers and replication every tick. Read with `get`;
+  call `getMut` only when a change is intended (see
+  [`getMut` and `ensure`](./entities.md#getmut-and-ensure-mutating-in-place)).
 - **A callback that always uses a component should inject it, not `get` it.** `entity.get(C)` is for
   a component that is conditionally needed and rarely required (see §4).
 - **Membership is fixed by `.with(...)` / `.without(...)` / `.update(C)`;** `update(C)` watches `C`
   and requires it.
+- **A system's `enter` reaches only entities still in its query when the system drains.** One that
+  left or died first gets neither `enter` nor the paired `exit`, and one that leaves and re-enters
+  within a drain gets `enter`, `exit`, `enter`, so keep `enter` setup and `exit` teardown symmetric
+  (see [`.enter`](./systems.md#entercallback--enterinject-callback--enteroptions-callback)).
 - **`exit` retains injected references captured at exit** (components are not deep-cloned).
+- **A `remove` hook also fires while the entity is being destroyed,** with `entity.destroyed`
+  already `true`. A dying entity takes no writes (`add`, `set`, `remove`, `modified` and `attach` are
+  dropped, `ensure` throws), so a hook that writes to its own entity guards on `entity.destroyed`.
+  That guard is legitimate; elsewhere a `destroyed` check usually signals a missing edge (see §8 and
+  [Hooks](./components.md#hooks-component-and-relationship-edges)).
+- **Release resources in `remove` hooks, not in a system's `exit` callback.** `world.dispose()`
+  runs the hooks during the call, but a system's `exit` callback only queues its event, and a
+  disposed world never runs the system again (see
+  [Disposing a world](./entities.md#disposing-a-world)).
 - **Within a phase, order = registration order;** across phases, the spine guarantees order. Don't
   use registration order for cross-module correctness — use phases.
 - **Networked component order = wire protocol.** Reordering breaks the protocol.
@@ -789,6 +876,9 @@ system after whatever produces the entity/companion.
   ordering; `hasTarget(R, target)` tests one edge.
 - **Relationship edges are explicit.** Add with `add(R, target)`, remove one with
   `remove(R, target)`, and remove all with `remove(R)`. Do not use `set` for target storage.
+- **Relationship removal hooks differ in scope.** `on("targetRemove")` fires once per removed edge;
+  `on("remove")` fires once, when the relationship component itself leaves, with no targets left on
+  the instance (see [Edge hooks](./relationships.md#edge-hooks)).
 - **Relationship cardinality and component exclusivity are different.** Add the `Exclusive` trait
   to a relationship for at-most-one target; use `setExclusiveComponents` for mutually exclusive
   component types.
@@ -810,6 +900,42 @@ system after whatever produces the entity/companion.
   explicitly, and during deferred execution keep that entity instead of re-reading `target(R)`
   before flush.
 - **`world.module(M)` runs `init` once.** Re-registering with a different config throws.
+- **vecs-phaser: a `DrawBy` child follows only its parent's `Position`.** It turns with the parent
+  only with `InheritRotation`, which makes the resolver derive its `Rotation` every frame, so
+  writing `Rotation` on a tagged child has no effect (see
+  [Turning with the parent](../../vecs-phaser-client/README.md#turning-with-the-parent)).
+- **vecs-phaser: `DrawBy` and `DrawIn` use `CleanupPolicy.Remove`,** so destroying a display parent
+  detaches its children instead of destroying them, unlike `ChildOf`, which deletes them. A display
+  child that must die with its parent also needs `ChildOf` to it, or must be its owned target (see
+  [Destroying the display parent](../../vecs-phaser-client/README.md#destroying-the-display-parent)).
+- **vecs-physics, vecs-phaser-server: pose writes are change-only.** `set` hooks and `update` systems
+  on the physics and render pose fire when the pose changed, not on every step; to visit every body
+  every step, iterate with `each` (see
+  [Pose Updates Fire Only When The Pose Changes](../../vecs-physics/docs/systems-and-phases.md#pose-updates-fire-only-when-the-pose-changes)).
+- **vecs-phaser-server: game code owns the physics pose; the render pose is protocol-private.** On
+  the server, read and write the physics `Position` and `Rotation` of every entity, including one
+  without a `Body`. The render `Position` and `Rotation` and the dead-reckoning `Motion` and
+  `MotionParams` are wire encodings of that pose that only the sync systems write: a `DeadReckoned`
+  body has no render pose at all, and adding one throws (see
+  [Dead reckoning](../../vecs-phaser-server/README.md#dead-reckoning)).
+- **vecs-phaser-server: switch `DeadReckoned` on a change of state, and keep a constantly driven body
+  streamed.** The tag may be added or removed at any time, so a body can be dead reckoned while it
+  drifts and streamed while joints, thrust or a tow drive it (a driven body diverges from its
+  prediction every step and would cost a baseline of about 27 bytes per step against about 22 for a
+  streamed pose update). Toggle it when the state changes, not every frame: each switch costs a
+  baseline one way and a pose update the other, and clients blend the hand-off over `blendMs`. A
+  render pose or `Motion` created or switched late in a frame, in `PRE_STORE`, `ON_STORE` or an RPC
+  handler, is still synced from the physics pose before the frame is recorded (see
+  [Switching at runtime](../../vecs-phaser-server/README.md#switching-at-runtime)).
+- **vecs-client: attach a `ClientWorld` socket only after `socket.connect()` resolves,** so no ack
+  precedes the data channel (`connectDgram` does this). Pending `invoke` calls reject with
+  `RPC_CLOSED_CODE` on disconnect or `dispose` (see
+  [Connecting](../../vecs-client/docs/client-world.md#connecting) and
+  [Disconnection and disposal](../../vecs-client/docs/client-world.md#disconnection-and-disposal)).
+- **vecs-physics: component fields hold plain data,** never Box2D wrappers or other class
+  instances. `set` accepts them, but snapshot capture (`snapshotSubtree`, `moveSubtree`) rejects
+  non-plain values (see
+  [Keep Component Fields Plain Data](../../vecs-physics/docs/components.md#keep-component-fields-plain-data)).
 
 ---
 

package/docs/entities.md

@@ -39,7 +39,8 @@ setting `entity.name` writes the `Identity` component, and duplicate names are l
 `world.entities` is a read-only view of every live entity keyed by id, and `world.clearAllEntities()`
 destroys **every** entity in the world — ordinary entities first, then component entities once
 their carriers are gone. It is a full wipe (systems and phases are backed by entities too); use it
-for end-of-session teardown, not selective resets.
+for end-of-session teardown, not selective resets. To destroy only what the application created
+and keep the world's own entities, see [Disposing a world](#disposing-a-world).
 
 ## The component API
 
@@ -95,6 +96,14 @@ e.getMut(Velocity, (vel) => {
 });
 ```
 
+`getMut` marks the component modified whenever it is present, with or without a callback and whether
+or not you assign anything: the callback form marks it after the callback returns, and the
+callback-free form marks it before it returns the instance, so even a read-only use notifies. The
+mark fires `onSet`, routes an `update` event to every system watching the component and replicates a
+networked component (repeated marks before the queue drains coalesce into one). A `getMut` that runs
+every tick therefore does all of that every tick. Read with `get`, and call `getMut` only when a
+change is intended. When the component is absent, `getMut` returns `undefined` and marks nothing.
+
 Use `ensure` when absence should mean "create with defaults, then mutate":
 
 ```ts
@@ -174,6 +183,66 @@ and policy surface as a registered class, and `keyEntity.on("add" / "set" / "rem
 "targetRemove", handler)` registers its lifecycle handlers directly. This is how tag-like,
 runtime-created component types work without declaring a class.
 
+## Disposing a world
+
+When you are finished with a world — a scene or route change, a hot reload — call
+`world.dispose()` and drop the reference. It destroys every entity the application and its modules
+created, so the `remove` hook of each component they carry runs and releases what the component
+owns: a render object, a handle, a timer.
+
+```ts
+class Handle {
+  public released = false;
+}
+
+world.component(Handle).on("remove", (_entity, handle) => {
+  handle.released = true; // release the resource here
+});
+
+const handle = new Handle();
+world.entity().attach(handle);
+
+world.dispose();
+handle.released; // true
+```
+
+Each entity goes through the ordinary destroy path. Every `remove` hook fires once,
+[cleanup policies and cascades](./relationships.md#cleanup-when-a-target-dies) run as for any
+`destroy()`, and an entity that a `ChildOf` or `OwnedTarget` cascade, or a hook, has already
+destroyed is skipped instead of destroyed twice.
+
+`dispose()` leaves the world's infrastructure in place, because the world needs it to stay
+coherent. It recognizes it as follows (`lib/vecs/src/world/world.disposal.ts`):
+
+| Infrastructure                | Recognized by                                                 |
+| ----------------------------- | ------------------------------------------------------------- |
+| Component and module entities | They are `Component` instances; `Module` extends `Component`. |
+| Query and system entities     | They carry the `Query` component.                             |
+| Phase entities                | They carry the `Phase` component.                             |
+
+What those entities hold stays with them: data stored on a component entity (a singleton set with
+`world.set`) and any entity they still carry as a [component key](#entities-as-component-keys),
+which cannot be destroyed while it is in use. Release those yourself; their `remove` hooks do not
+run. `clearAllEntities()` is the full wipe that takes the infrastructure too.
+
+- **Order.** Among unrelated entities the order is unspecified, so do not make a hook depend on it.
+  An entity used as a component key is destroyed after every entity that carries it, because
+  destroying it first would throw under the default cleanup policy.
+- **Pending commands.** `dispose()` neither flushes the command queue early nor discards it. Commands
+  queued ahead of it run first, in order, and the destruction follows in the same queue, so each
+  hook fires once however the component left. At top level nothing is queued, and `dispose()`
+  returns with the entities gone. Inside a system, a hook or a `defer` block the world is
+  [deferred](./execution-model.md#deferred-mutation-and-flush-boundaries), so `dispose()` queues the
+  destruction as `destroy()` does, and it completes when the queue next drains. An entity whose
+  creation is still queued is created, then destroyed.
+- **After disposal.** A disposed world must not be used again. Nothing enforces it — no other method
+  checks, so `entity()` and `progress()` keep their cost. Calling `dispose()` again, or from a hook
+  during the teardown, does nothing. An entity that a `remove` hook creates during the teardown is
+  left behind, so do not spawn from teardown hooks. A system's `exit` callback only queues its event,
+  and a disposed world never runs the system again; release resources in `remove` hooks, as
+  [Resources as components](./design-guide.md#resources-as-components-hold-non-ecs-objects)
+  recommends.
+
 ## Relationships, in brief
 
 `e.target(Rel)` returns one current target, `e.targets(Rel)` a readonly snapshot of every target,

package/docs/execution-model.md

@@ -162,7 +162,7 @@ component:
   their next run (`lib/vecs/src/system.ts`). So systems react to change without scanning, and they
   react _in their own phase slot_, in event arrival order.
 
-Three routing rules worth memorizing:
+Four routing rules worth memorizing:
 
 - **`update(C)` is change-only unless you opt into entry.** When an entity enters a system,
   `{ onEnter: true }` update watchers push an `update` event for already-present watched components.
@@ -173,8 +173,9 @@ Three routing rules worth memorizing:
   objects are not deep-cloned.
 - **`enter` is drain-time truthful.** A system only receives `enter` when the entity is still a
   member when that system runs. If it left before the inbox drains, vecs drops both that queued
-  `enter` and its paired `exit`; an entity that re-enters before draining receives the ordered
-  lifecycle events for its final membership.
+  `enter` and its paired `exit`; an entity that re-enters before draining is a member again, so the
+  queued events replay in order as `enter`, `exit`, `enter`. The details are in
+  [Systems — `.enter`](./systems.md#entercallback--enterinject-callback--enteroptions-callback).
 - **In-place mutation needs `modified`.** Assigning to component fields directly notifies no one.
   Call `entity.modified(C)` (or use `set` / `getMut` / `ensure`) to route the change.
 

package/docs/glossary.md

@@ -38,6 +38,10 @@ behavior. [Components](./components.md).
 queued as commands; `flush` drains the queue at the scope boundary (after each system in the
 pipeline). [Execution model](./execution-model.md#deferred-mutation-and-flush-boundaries).
 
+**Dispose** — `world.dispose()`: end a world's life by destroying every entity the application and
+its modules created, so their components' `remove` hooks run. The infrastructure (component,
+module, query, system, and phase entities) stays. [Entities](./entities.md#disposing-a-world).
+
 **Entity** — a unique numeric id (`eid`) owned by a world, with a set of components attached.
 [Entities](./entities.md).
 

package/docs/queries-and-filters.md

@@ -44,6 +44,31 @@ evaluates it against each entity pointing at the candidate and also matches when
 queries and systems. `target` / `parent` are fully reactive to edge changes and target-side changes
 — see [Relationships](./relationships.md#querying-through-relationships).
 
+### The cost of `not` and `.without`
+
+`.without(X)` is `.with({ not: X })` (`lib/vecs/src/query/query.ts`, `without`), and `.with` merges
+into `{ all: [...] }`. A `not` term is built from the world term plus `X`'s term and holds every live
+entity that lacks `X` (`lib/vecs/src/terms/not_term.ts`). It is a world-sized set, independent of
+the query's positive terms, and the `all` term intersects it with them.
+
+| Event                               | Effect on a `not X` term                                                      |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| Term built (first use)              | One scan of the whole world seeds the set (`term.ts`, `_initializeFromWorld`) |
+| Entity created or destroyed         | Added to or removed from the set (`world_term.ts`, `entityCreated`)           |
+| `X` added to or removed from entity | The entity leaves or re-enters the set                                        |
+| `X` data modified                   | Nothing (`not_term.ts`, `onTermRefresh` is a no-op)                           |
+
+Terms are cached by canonical key, so the upkeep is paid once per distinct exclusion, not once per
+query. Each query that uses it adds one membership check per change of the set, and the positive
+term comes first, so most checks stop there.
+
+- Use `.without` only when the exclusion is needed, and pair it with positive terms that keep the
+  query's members small. A query with only `.without` terms tracks every entity in the world, so
+  its `enter` fires for each created entity.
+- The creation pattern `.with(NewShape).without(Phaser.GameObjects.NewKind).enter(...)` depends on
+  this: the positive term limits the members, and the exclusion drops the few that already hold the
+  object.
+
 ### `QuerySpec`: adding `cascade` and `hint`
 
 Anywhere a DSL is accepted, you can pass the object form

package/docs/relationships.md

@@ -33,6 +33,36 @@ again is idempotent. Target ordering is not a public contract.
 storage. For a non-exclusive relationship, do not use `target(ref)` as a stable selection policy.
 Use `hasTarget(ref, target)` to test one edge without allocating a snapshot.
 
+## Link with edges, not stored ids
+
+Link one entity to another with a relationship edge, not with an `eid` or an `Entity` kept in a
+component field (`ownerEid = 0`, `target: Entity | undefined`). The world maintains an edge. It
+cannot maintain a field:
+
+- **A stored eid can come to name another entity.** A destroyed entity's id is reused once its
+  pool's `reuseWaitFrames` have passed: 16 frames by default, `0` for replicated entities on a
+  `ClientWorld`, and at least `historyFrames + 1` on a `ServerWorld` (see
+  [Id pools](./components.md#id-pools)). Allocation hands out free ids before
+  never-used ones, so one of the next entities created takes it. Until an entity does,
+  `world.getEntity(id)` returns `undefined`; from then on it returns that live, unrelated entity and
+  the stale id looks valid.
+- **A stored `Entity` dangles.** Reuse never makes it name another entity, because a destroyed
+  `Entity` stays `destroyed`, but nothing clears the field when the entity dies. Writes through it
+  are dropped and `ensure` throws.
+- **An edge is cleaned up for you.** When the target is destroyed, `onDeleteTarget` removes the edge
+  or destroys the source (see [Cleanup when a target dies](#cleanup-when-a-target-dies)). The
+  reverse index (`children`), `target` and `parent` queries, `groupBy` and network replication work
+  on edges only.
+- **A field does not cross worlds.** `snapshotSubtree` and `moveSubtree` remap relationship targets
+  onto the destination's new ids. An eid field is copied as is and names the wrong entity there; an
+  `Entity` field makes capture throw (see [Snapshot policies](./snapshots.md#snapshot-policies)).
+
+A `destroyed` check on an entity you looked up from a stored link is therefore a symptom of a
+missing edge: replace the link, not only the check. The guard stays right where a reference is
+deliberately short-lived: payloads in per-step event buffers (the `other` entity in `vecs-physics`
+contact events), and hooks that run while an entity or an edge target is being destroyed (see
+[Edge hooks](#edge-hooks) and [component hooks](./components.md#hooks-component-and-relationship-edges)).
+
 ## Built-in relationships
 
 | Class           | Purpose                                                                                                                    |
@@ -192,6 +222,26 @@ calls `onRemove`. An exclusive replacement calls `onTargetRemove` for the old ta
 relationship-dependent query updates, but do not call `onSet`; `onSet` is reserved for ordinary
 relationship data changed through `set`.
 
+Pick the removal hook by scope:
+
+- `on("targetRemove", handler)` runs once for **each** removed edge: `remove(R, target)`, the
+  displaced edge of an `Exclusive` replacement, and every edge when the whole relationship goes away
+  (the final edge, `remove(R)`, or destroying the source).
+- `on("remove", handler)` runs **once**, when the relationship component itself leaves the entity.
+  It does not run when one of several edges is removed or an `Exclusive` edge is replaced. The
+  relationship instance it receives holds no targets any more, so use `targetRemove` to learn which
+  targets went.
+
+When the whole relationship goes away, `source.has(R)` is already `false` inside both hooks. When
+only one of several edges goes, `source.has(R)` stays `true` and `source.hasTarget(R, removed)` is
+`false`.
+
+Destroying either end of an edge runs these hooks too, so `source.destroyed` or `target.destroyed`
+can already be `true` inside them; both are under `Delete` cleanup. The target of an `OwnedTarget`
+edge is destroyed before the public hook runs on every path. A dying end takes no writes (see
+[Hooks](./components.md#hooks-component-and-relationship-edges)), so a handler that writes to
+`source` or `target` guards on `destroyed`.
+
 Register handlers with `on("targetAdd", handler)` and `on("targetRemove", handler)`; remove them
 with `off(event, handler)`. Multiple handlers may be registered for the same event and fire in
 registration order. Framework traits install separate internal `targetPolicyAdd` /
@@ -227,6 +277,11 @@ attached: removing it throws, and only world teardown (`clearAllEntities`) bypas
 the same contract as `Traversable` and `OneOf`. Do not share an owned target between
 sources because either owner can destroy it when its edge is removed.
 
+An owned target replaces the field-plus-hook pattern, where a component field holds the child
+entity and an `onRemove` hook destroys it. The edge is the field: every path that drops it destroys
+the child, and destroying the child directly removes the edge from its owner. There is no hook to
+write and no stale reference to guard.
+
 ## Cleanup when a target dies
 
 What happens to each incoming edge when its target entity is destroyed is governed by the

package/docs/snapshots.md

@@ -83,8 +83,11 @@ class Position {
 ```
 
 `Position` has no policy, so it uses **`ClonePublic`**: a fresh instance with the source instance's
-own enumerable fields copied over. That is the same shallow copy `set` performs, and it is exactly
-as aliasing-sensitive — a component holding a nested object shares it until something copies it.
+own enumerable fields copied over, deeply. The copy covers primitives, arrays, plain objects, `Map`,
+`Set`, `Date`, `ArrayBuffer` and typed arrays, so the destination never aliases a nested value of
+the source. Anything else, such as a class instance, a function or a symbol, is not plain data:
+capture throws with the component and field path instead of sharing it across worlds. A component
+that holds one declares `CustomSnapshot` or `DontSnapshot` (below).
 
 ### `DontSnapshot`
 

package/docs/systems.md

@@ -44,6 +44,7 @@ the full query DSL (operator semantics in
 .with({ parent: Body })                                   // ChildOf target has Body
 ```
 
+`.without` is not free: see [its cost](./queries-and-filters.md#the-cost-of-not-and-without).
 Multiple `with` calls merge with `all`. The `source` / `children` operators are non-reactive and
 rejected by systems — they are filter-only (see
 [Queries and filters](./queries-and-filters.md#filters-one-shot-scans)).
@@ -89,10 +90,15 @@ Fires once when an entity starts matching the system:
 .enter({ inject: [Position, Sprite] }, (e, [pos, sprite]) => sprite.setPosition(pos.x, pos.y))
 ```
 
-The callback runs only if the entity is still a member when this system drains its inbox. If it
-left or was destroyed first, vecs drops the queued `enter` and its paired `exit`; do not add a
-`destroyed` guard to normal `enter` setup code. If it leaves and re-enters before draining, the
-callback receives the ordered lifecycle transitions.
+The callback runs only if the entity is still a member when this system drains its inbox, at the top
+of its next run. The inbox replays in arrival order, so:
+
+- An entity that left the query or was destroyed first gets no `enter`, and in a system that
+  registers both callbacks no paired `exit` either. Do not add a `destroyed` guard to normal `enter`
+  setup code. A system with only `exit` has no `enter` to pair, so it still gets that `exit`.
+- An entity that leaves and re-enters before the drain is a member again, so the system gets
+  `enter`, `exit`, `enter` (just `exit`, `enter` when it had already entered in an earlier drain).
+  Keep `enter` setup and `exit` teardown symmetric so the second `enter` starts from a clean state.
 
 For systems, injected values and `Iter.src` are captured when entry is routed and replayed from that
 snapshot when the system next drains its inbox.
@@ -126,6 +132,25 @@ Use `.update(C, ...)` by itself when `C` is the membership shape and watched val
 A query or system can register only one `update(C, ...)` callback for each component. A duplicate
 registration throws instead of replacing the existing callback.
 
+#### Repeated writes in one tick
+
+Each routed write is one `update` event, and a system's inbox replays its events in arrival order
+without merging any (`lib/vecs/src/system.ts`, `_pushUpdate` and the drain loop in
+`_runDeferred`). What differs is how many events a write routes:
+
+| Write                      | Events routed for `C` in one drain window                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `entity.set(C, …)` × n     | n: every call queues its own command and fires its own `onSet` and `update`                      |
+| `entity.modified(C)` × n   | 1: the first call sets the dirty bit, the command clears it when it runs, later calls are no-ops |
+| `entity.getMut(C, cb)` × n | 1: it marks modified through the same dirty bit                                                  |
+
+Coalescing needs a queued command, so it applies to calls made while commands are deferred (inside
+system callbacks); outside them `modified` applies immediately. To get one callback per tick, write
+in place and call `modified` (or use `getMut`), or compare before `set` and skip equal values. Do
+not add a per-tick dedupe or batching step in the consumer when producers already use
+`modified`/`getMut`. Source: `lib/vecs/src/entity/entity.components.ts` (`_markModified`, `set`,
+`_notifyRaw`).
+
 ### `.exit(callback)` / `.exit(inject, callback)` / `.exit(options, callback)`
 
 Fires when an entity stops matching (component removed, or entity destroyed). Directly injected
@@ -144,7 +169,9 @@ object remain visible:
 ### `.each(components, callback)` / `.each(options, callback)`
 
 Fires every tick the system runs, once per tracked entity, regardless of change. Use it only for
-genuinely per-frame sweeps — when reacting to change suffices, prefer `update` (see
+genuinely per-frame sweeps — when reacting to change suffices, prefer `update`. An `.each` must
+justify running every tick, and when it does, narrow `.with(...)` to a tag that exists only while
+the work is live (see
 [Design guide](./design-guide.md#each-vs-reactive--dont-scan-when-you-can-react)):
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -27,12 +27,5 @@
     "type": "git",
     "url": "https://github.com/vworlds/vecs",
     "directory": "lib/vecs"
-  },
-  "lint-staged": {
-    "*.ts": [
-      "prettier --write",
-      "eslint --fix"
-    ],
-    "*.md": "prettier --write"
   }
 }

package/skills/vecs/SKILL.md

@@ -40,6 +40,10 @@ Before implementing, identify:
 - The state represented by each component and whether absence has meaning.
 - Which component transition creates, updates, or removes related state or resources.
 - Whether the work should react through `enter`, `update`, or `exit` rather than scan every frame.
+  An `.each` must justify running every tick; when it does, narrow its query with a tag that exists
+  only while the work is live (for example a `Firing` tag that a reactive `update` on the intent
+  adds and removes) instead of looping over every candidate and returning early.
+  ([`each` vs reactive](../../docs/design-guide.md#each-vs-reactive--dont-scan-when-you-can-react))
 - Which phase owns the work and what earlier or later phase it must order against.
 - Whether a multi-target relationship, an `Exclusive` relationship, an explicitly created owned
   target, a grouped query, or an attached resource expresses the lifecycle better than imperative
@@ -65,6 +69,69 @@ Check the design guide before introducing:
 If the requested design conflicts with a documented vecs invariant, explain the conflict and use
 the documented pattern unless the user explicitly chooses otherwise.
 
+## Known Gotchas
+
+Agents trip on these vecs behaviors repeatedly. Design guide sections 8 and 9 list them with the
+other anti-patterns and pitfalls; each rule below links to the detail.
+
+- Do not call `getMut` per tick unless a change is intended. It marks the component modified even
+  without a callback and even if nothing is written, which fires `update` watchers and replication.
+  Read with `get`. ([`getMut`](../../docs/entities.md#getmut-and-ensure-mutating-in-place))
+- `.without(X)` does not filter the positive terms' candidates: it keeps a world-sized "not X" set,
+  updated on every entity create and destroy and every `X` add or remove, and intersects it with
+  them. Use it only when needed, after positive terms that keep the members small; a query with only
+  `.without` terms tracks the whole world.
+  ([Cost of `.without`](../../docs/queries-and-filters.md#the-cost-of-not-and-without))
+- `entity.modified(C)` and `getMut(C)` coalesce into one `update` per drain; every `entity.set(C, …)`
+  routes its own, and the system inbox never merges events. Write in place plus `modified`, or
+  compare before `set`, and do not add per-tick dedupe batches when producers use `modified`/`getMut`.
+  ([Repeated writes](../../docs/systems.md#repeated-writes-in-one-tick))
+- A system's `enter` reaches only entities still in its query when the system drains. An entity
+  that left the query or died first gets neither `enter` nor the paired `exit`, and a re-entry
+  within one drain gives `enter`, `exit`, `enter`, so keep setup and teardown symmetric.
+  ([`.enter`](../../docs/systems.md#entercallback--enterinject-callback--enteroptions-callback))
+- Create relationship edges with `add(Rel, target)` and read them with `target()` / `targets()`.
+  React to the relationship component being removed with `on("remove")` and to each removed edge
+  with `on("targetRemove")`. `OwnedTarget` needs `Exclusive` and an explicitly created target, and
+  destroys that target when its edge is removed.
+  ([Edge hooks](../../docs/relationships.md#edge-hooks),
+  [Owned targets](../../docs/relationships.md#owned-targets))
+- Link entities with relationship edges, never with an `eid` or `Entity` kept in a component field.
+  A destroyed entity's eid is reused after `reuseWaitFrames` (16 frames by default, 0 for replicated
+  entities on a `ClientWorld`), so a stale eid can name an unrelated entity. A stored `Entity`
+  dangles, and snapshots copy an eid unchanged and reject an `Entity`.
+  ([Link with edges, not stored ids](../../docs/relationships.md#link-with-edges-not-stored-ids))
+- Prefer `Exclusive` + `OwnedTarget` to a component field that holds a child entity. Removing or
+  replacing the edge destroys the child and destroying the child removes the edge, so no remove hook
+  is needed. ([Owned targets](../../docs/relationships.md#owned-targets))
+- A `remove` hook also fires while its entity is being destroyed, with `entity.destroyed` already
+  `true`. A dying entity drops `add`, `set`, `remove`, `modified` and `attach` writes and `ensure`
+  throws, so guard a hook's writes to its own entity with `entity.destroyed`; that guard is
+  legitimate. ([Hooks](../../docs/components.md#hooks-component-and-relationship-edges))
+- A `destroyed` check outside per-step event buffers and hooks on a dying entity or edge target
+  usually means a link that should be a relationship edge. Replace the link, not only add the check.
+  ([Link with edges, not stored ids](../../docs/relationships.md#link-with-edges-not-stored-ids))
+- `@vworlds/vecs-phaser`: a `DrawBy` child turns with its parent only with `InheritRotation`. The
+  resolver derives a tagged child's `Rotation` every frame, so writing `Rotation` on it has no
+  effect; set `InheritRotation.angle` instead.
+  ([Turning with the parent](../../../vecs-phaser-client/README.md#turning-with-the-parent))
+- `@vworlds/vecs-phaser`: `DrawBy` and `DrawIn` use `CleanupPolicy.Remove`, so destroying a display
+  parent detaches its children and leaves them alive, unlike `ChildOf`. Add `ChildOf` to the parent,
+  or make the child an owned target, when it must die with the parent.
+  ([Destroying the display parent](../../../vecs-phaser-client/README.md#destroying-the-display-parent))
+- `@vworlds/vecs-physics` and `@vworlds/vecs-phaser-server`: pose `set` hooks and `update` systems
+  on the physics and render pose fire only when the pose changes. To visit every body every step,
+  iterate with `each`.
+  ([Pose updates](../../../vecs-physics/docs/systems-and-phases.md#pose-updates-fire-only-when-the-pose-changes))
+- `@vworlds/vecs-client`: attach a `ClientWorld` socket only after `socket.connect()`, so no ack
+  precedes the data channel (`connectDgram` does this). Pending `invoke` calls reject with
+  `RPC_CLOSED_CODE` on disconnect or dispose.
+  ([Connecting](../../../vecs-client/docs/client-world.md#connecting),
+  [Disconnection and disposal](../../../vecs-client/docs/client-world.md#disconnection-and-disposal))
+- `@vworlds/vecs-physics` components hold plain data only, never Box2D wrappers or other class
+  instances: snapshot capture rejects non-plain values.
+  ([Plain data](../../../vecs-physics/docs/components.md#keep-component-fields-plain-data))
+
 ## Implement And Verify
 
 1. Reuse existing components and modules where their semantics match; do not reuse them merely