@vworlds/vecs 1.0.48 → 1.0.50

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.48",
+  "version": "1.0.50",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

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
@@ -41,7 +42,7 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 | [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. |
@@ -58,5 +59,5 @@ sessions, and the client world) lives in the `@vworlds/vecs-wire`, `@vworlds/vec
 - [Remote procedure calls](../../vecs-protocol/docs/rpc.md) — the call channel and typed errors.
 - [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,14 @@ 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 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 +109,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

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`
 
@@ -305,7 +306,8 @@ Choose `onEnter: true` by asking who owns the initial value:
 
 ### Injection
 
-Pull components into the callback instead of `entity.get()`-ing them by hand:
+**Inject every component a system callback always uses.** Pull it into the callback instead of
+`entity.get()`-ing it by hand:
 
 ```ts
 .enter([Arc], (entity, [arc]) => { /* … */ })
@@ -314,6 +316,23 @@ Pull components into the callback instead of `entity.get()`-ing them by hand:
 .each([Position, Velocity], (entity, [pos, vel]) => { /* … */ })
 ```
 
+Use `entity.get(C)` only for a component that is conditionally needed and rarely required: a read on
+a branch most calls never take, where resolving the component for every call would be waste.
+
+Why:
+
+- **The signature states the inputs.** What a callback reads sits next to the `.with(...)` that
+  guarantees it, not in the body.
+- **No dead guards.** A component guaranteed by `.with(...)` is injected as non-nullable, so there
+  is no `undefined` to check. `get` returns `Readonly<C> | undefined`, which invites an
+  `if (c !== undefined)` that tells the next reader the component might be missing when the query
+  says it cannot be. An injected instance is also the live, mutable one: a callback that writes in
+  place and calls `entity.modified(C)` (see §7) needs no cast.
+- **Resolved once.** Injection resolves a component's id when the callback is registered;
+  `entity.get(C)` resolves the class on every call. In an `exit` callback injection matters more
+  still: it reads the snapshot captured when the entity left, while a `get` at replay time can find
+  the component already removed.
+
 Components listed in the inject tuple but **not** guaranteed by `.with(...)` resolve as
 `T | undefined` (the types reflect this) — guard them; the ones in `.with` are always present.
 
@@ -328,7 +347,7 @@ Components listed in the inject tuple but **not** guaranteed by `.with(...)` res
 // ❌ scans every body every tick, even if it didn't move
 .with(PhysicsPosition, RenderPosition).each([...], (e, [...]) => { if (changed) e.set(...) });
 
-// ✅ fires only when physics actually moved the body
+// ✅ fires only when physics actually moved the body (compare before writing a networked B: see §7)
 .with(PhysicsPosition, RenderPosition).update(PhysicsPosition, (e, p) => e.set(RenderPosition, { x: p.x, y: p.y }));
 ```
 
@@ -396,15 +415,28 @@ export class PhaserServerModule extends Module<undefined> {
       .system("phaser.sync.position")
       .with(PhysicsPosition, RenderPosition)
       .phase(POST_UPDATE)
-      .update({ watch: PhysicsPosition, onEnter: true }, (e, p) =>
-        e.set(RenderPosition, { x: p.x, y: p.y })
+      .update(
+        { watch: PhysicsPosition, onEnter: true, inject: [RenderPosition] },
+        (e, p, [render]) => {
+          if (render.x !== p.x || render.y !== p.y) {
+            render.x = p.x;
+            render.y = p.y;
+            e.modified(RenderPosition);
+          }
+        }
       );
     world
       .system("phaser.sync.rotation")
       .with(PhysicsRotation, RenderRotation)
       .phase(POST_UPDATE)
-      .update({ watch: PhysicsRotation, onEnter: true }, (e, r) =>
-        e.set(RenderRotation, { angle: r.angle })
+      .update(
+        { watch: PhysicsRotation, onEnter: true, inject: [RenderRotation] },
+        (e, r, [render]) => {
+          if (render.angle !== r.angle) {
+            render.angle = r.angle;
+            e.modified(RenderRotation);
+          }
+        }
       );
   }
 }
@@ -583,14 +615,31 @@ rebinds. No teardown system, no special-casing anywhere.
 
 Copy `A → B`, gated on both existing (so you never _create_ `B`, you only keep an existing `B` in
 sync — pure-ECS: the owner decides whether `B` exists). Use `{ onEnter: true }` when `B` must reflect
-the current `A` as soon as the entity enters the sync system:
+the current `A` as soon as the entity enters the sync system, inject `B` (the `.with(...)` guarantees
+it, so it is non-nullable, see §4), and write only when `B` differs from `A`:
 
 ```ts
-.with(PhysicsPosition, RenderPosition).update({ watch: PhysicsPosition, onEnter: true }, (e, p) =>
-  e.set(RenderPosition, { x: p.x, y: p.y })
+.with(PhysicsPosition, RenderPosition).update(
+  { watch: PhysicsPosition, onEnter: true, inject: [RenderPosition] },
+  (e, p, [render]) => {
+    if (render.x !== p.x || render.y !== p.y) {
+      render.x = p.x;
+      render.y = p.y;
+      e.modified(RenderPosition);
+    }
+  }
 );
 ```
 
+Every write is a modification, even with an equal value: both `set` and `modified` fire `onSet`,
+route `update` events to every watching system and replicate a networked component. So a sync into a
+networked or watched `B` compares before it writes. The injected `B` is the live instance, so assign
+into it and call `entity.modified(B)`: that has the same effects as `set` without the props literal
+and the deferred copy, and a second event for the same entity in one drain finds the first write
+applied and writes nothing. Always pair an in-place write with `modified`: assignment alone notifies
+nobody, so hooks, watchers and replication never see it. Use `set` when you do not hold the instance,
+or when the write should create the component.
+
 Leave `onEnter: true` off (or set `onEnter: false`) only when a separate `.enter(...)` already initializes `B`,
 or when the callback is intentionally "future changes only."
 
@@ -654,6 +703,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:
 
@@ -701,12 +755,16 @@ 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.                                                                           |
 | One system trying to act in two phases                                 | Split into two systems, one per phase.                                                                                                               |
 | Custom phases for app/render logic                                     | Use the standard taxonomy; only engine modules insert phases.                                                                                        |
 | `.each` scanning every entity to detect change                         | Reactive `.update(C)` — fires only on change.                                                                                                        |
+| `entity.get(C)` for a component the callback always uses               | Inject it (`inject: [C]`); keep `get` for a component that is conditionally needed and rarely required.                                              |
 | Treating target storage as component data                              | Use `add(Rel, target)` / `remove(Rel, target)` and read with `target` / `targets` / `hasTarget`; target storage is private.                          |
 | A `registerFooSystem(world)` wrapper per system                        | Declare the system inline in the module's `init`.                                                                                                    |
 
@@ -720,9 +778,33 @@ system after whatever produces the entity/companion.
 - **`update(C)` is change-only by default.** Add `{ onEnter: true }` for projection/sync callbacks
   that must apply the current watched value on entry; leave it off for mutation-only callbacks or
   when `.enter(...)` already owns initialization.
+- **A write marks the component modified, even with an equal value.** `set`, and an in-place
+  assignment followed by `modified`, fire `onSet`, route `update` events to every watching system and
+  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.
@@ -733,6 +815,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.
@@ -754,6 +839,33 @@ 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` 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-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/relationships.md

@@ -33,6 +33,35 @@ 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, and `0` for replicated entities on a
+  `ClientWorld` (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 +221,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 +276,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

@@ -89,10 +89,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.
@@ -189,6 +194,9 @@ an options object with `inject`, resolved per entity and passed as a typed tuple
 .each({ inject: [Position, Sprite] }, (e, [pos, sprite]) => { ... })
 ```
 
+Inject every component a callback always uses, and keep `entity.get` for one that is only
+conditionally needed (see [Design guide](./design-guide.md#injection)).
+
 Nullability follows membership: components guaranteed by `with` (or `hint`) are non-nullable;
 anything else resolves as `T | undefined` — guard it. (`enter`/`exit` injection requires the
 direct components to be present and throws otherwise; list only components your predicate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/skills/vecs/SKILL.md

@@ -65,6 +65,60 @@ 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))
+- 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