@vworlds/vecs 1.0.45 → 1.0.47

package/dist/modules/relationship_types.js

@@ -17,20 +17,84 @@ export class DependsOn extends Relationship {
 export class SilenceSource extends Relationship {
 }
 /**
- * Marker component that makes every target of a relationship a `ChildOf` child
+ * Pair-form trait: attaching `(With, Y)` to a component `X` makes adding `X`
+ * to an entity automatically add `Y` as well.
+ *
+ * Plain form — `X` and `Y` are both non-relationship components:
+ *
+ * ```ts
+ * world.component(Armor);
+ * world.component(Helmet).add(With, world.component(Armor));
+ * const e = world.entity().add(Helmet); // e also has Armor
+ * ```
+ *
+ * Relationship form — `X` and `Y` are both relationships; the same target is
+ * propagated:
+ *
+ * ```ts
+ * world.component(OwnedBy);
+ * world.component(WornBy).add(With, world.component(OwnedBy));
+ * const wearer = world.entity();
+ * const e = world.entity().add(WornBy, wearer); // e also has (OwnedBy, wearer)
+ * ```
+ *
+ * `With` is irrevocable and rejects attach while `X` is already in use, so
+ * configure it during world setup before any entity carries `X`.
+ */
+export class With extends Relationship {
+}
+/**
+ * Pair-form trait constraining the targets of a relationship to direct
+ * children (via {@link ChildOf}) of a specified parent entity.
+ *
+ * Self/enum form — the relationship's own entity is the parent. A faction
+ * diplomacy alignment enum is a natural fit: every `Alignment` target must be
+ * a declared alignment value.
+ *
+ * ```ts
+ * class Alignment extends Relationship {}
+ * const alignment = world.component(Alignment).add(OneOf, world.component(Alignment));
+ * const good = world.entity().childOf(alignment);
+ * const evil = world.entity().childOf(alignment);
+ * const weather = world.entity();
+ * world.entity().add(Alignment, good);    // ok: good is a child of Alignment
+ * world.entity().add(Alignment, weather); // throws: weather is not a child of Alignment
+ * ```
+ *
+ * Other-parent form — a different entity is the parent:
+ *
+ * ```ts
+ * class ResidesIn extends Relationship {}
+ * class Region extends Relationship {}
+ * world.component(ResidesIn).add(OneOf, world.component(Region));
+ * const forest = world.entity().childOf(world.component(Region));
+ * const weather = world.entity();
+ * world.entity().add(ResidesIn, forest);  // ok: forest is a child of Region
+ * world.entity().add(ResidesIn, weather); // throws: weather is not a child of Region
+ * ```
+ *
+ * `OneOf` is irrevocable and rejects attach while the relationship is already
+ * in use, so configure it during world setup before any entity carries an
+ * edge through the relationship.
+ */
+export class OneOf extends Relationship {
+}
+/** Marker trait restricting a relationship to one target. */
+export class Exclusive {
+}
+/**
+ * Marker component that makes every explicit target of a relationship a `ChildOf` child
  * of the relationship source.
  *
  * Add during world setup, before creating relationship instances:
  *
  * ```ts
  * world.component(Inventory).add(OwnedTarget);
- * player.add(Inventory); // creates an owned target
+ * player.add(Inventory, inventory);
  * ```
  *
- * Adding the relationship creates a target when none was supplied. Retargeting
- * destroys the displaced target, and removing the relationship destroys its
- * current target. Configure owner lifecycle hooks before attaching this trait;
- * the trait wraps them and runs ownership behavior first.
+ * The relationship must also carry {@link Exclusive}. Removing or replacing an
+ * edge destroys its target.
  */
 export class OwnedTarget {
 }

package/dist/modules/relationship_types.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationship_types.js","sourceRoot":"","sources":["../../src/modules/relationship_types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,0CAA0C;AAC1C,MAAM,OAAO,OAAQ,SAAQ,YAAY;CAAG;AAE5C,+CAA+C;AAC/C,MAAM,OAAO,SAAU,SAAQ,YAAY;CAAG;AAE9C;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;CAAG;AAElD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,WAAW;CAAG;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,WAAW;IAAxB;QACE,+CAA+C;QAC/C,WAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,CAAC;CAAA"}
+{"version":3,"file":"relationship_types.js","sourceRoot":"","sources":["../../src/modules/relationship_types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,0CAA0C;AAC1C,MAAM,OAAO,OAAQ,SAAQ,YAAY;CAAG;AAE5C,+CAA+C;AAC/C,MAAM,OAAO,SAAU,SAAQ,YAAY;CAAG;AAE9C;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;CAAG;AAElD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,IAAK,SAAQ,YAAY;CAAG;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,KAAM,SAAQ,YAAY;CAAG;AAE1C,6DAA6D;AAC7D,MAAM,OAAO,SAAS;CAAG;AAEzB;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,WAAW;CAAG;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,WAAW;IAAxB;QACE,+CAA+C;QAC/C,WAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,CAAC;CAAA"}

package/dist/modules/relationships.d.ts

@@ -1,5 +1,5 @@
 import { Module } from "../module.js";
-export { ChildOf, DependsOn, OwnedTarget, SilenceSource, Traversable, } from "./relationship_types.js";
+export { ChildOf, DependsOn, Exclusive, OneOf, OwnedTarget, SilenceSource, Traversable, With, } from "./relationship_types.js";
 /**
  * Built-in world module that registers the `ChildOf` relationship and
  * maintains ownership and depth tracking policies for relationship traits.
@@ -9,16 +9,26 @@ export { ChildOf, DependsOn, OwnedTarget, SilenceSource, Traversable, } from "./
  * destroying a parent recursively destroys the children that target it through
  * `ChildOf` (custom relationships default to `Remove`).
  *
- * When a relationship component entity has `Traversable` attached, the module
- * installs `onAdd`, `onSet`, and `onRemove` hooks on that relationship so that
- * every entity's depth is updated when the relationship is added, retargeted,
- * or removed.
+ * `Traversable` requires `Exclusive`. The module wraps target-edge hooks on a
+ * traversable relationship so every entity's depth is updated when its edge is
+ * added, replaced, or removed.
  *
  * When a relationship component entity has `OwnedTarget` attached, the module
- * wraps its hooks so adding the relationship creates a target when needed,
- * every target becomes a `ChildOf` child of its source, and targets are
- * destroyed when displaced or removed. Configure this trait after the
- * relationship's owner hooks and before creating relationship instances.
+ * wraps its target-edge hooks so every explicitly added target becomes a
+ * `ChildOf` child of its source and is destroyed when displaced or removed.
+ * `OwnedTarget` requires `Exclusive` and never creates a target implicitly.
+ *
+ * `OneOf` constrains the targets of a relationship to direct `ChildOf`
+ * children of a specified parent entity. Attach during setup as
+ * `relationship.add(OneOf, parent)`; the module installs a per-edge policy that
+ * rejects targets whose `ChildOf` parent is not the declared parent. `OneOf`
+ * is irrevocable once attached.
+ *
+ * `OwnedTarget` and `Traversable` are irrevocable once attached: both
+ * `entity.remove(Trait)` and `entity.attach(newInstance)` throw, and the world
+ * must be discarded after the throw. Teardown bypasses these guards —
+ * `Entity._destroy` does not fire `_onPolicyRemove` — so `clearAllEntities`
+ * can still tear down worlds with these traits configured.
  *
  * Depth is computed by walking `entity.target(relEid)` to the root. When an
  * entity's depth changes, every descendant is recursively recomputed.
@@ -27,4 +37,16 @@ export declare class RelationshipsModule extends Module {
     init(): void;
     private _cascadeUpdate;
     private _depthOf;
+    /**
+     * Make a pair-form trait irrevocable: removing an edge of `trait` throws
+     * once attached.
+     *
+     * Teardown fires `targetPolicyRemove` from two paths: `_detachRelationship`
+     * on the trait carrier (after `carrier._destroyed = true`) and the cleanup
+     * cascade when the pair target is destroyed (buffered via `_cleanupIncoming`
+     * → `_removeTarget`, where the carrier is still alive but the target is
+     * already gone). Skip the irrevocability guard in either case; see the
+     * teardown contract in the class JSDoc.
+     */
+    private _forbidPairTraitRemoval;
 }

package/dist/modules/relationships.js

@@ -1,7 +1,7 @@
 import { CleanupPolicy } from "../component_meta.js";
 import { Module } from "../module.js";
-import { ChildOf, OwnedTarget, Traversable } from "./relationship_types.js";
-export { ChildOf, DependsOn, OwnedTarget, SilenceSource, Traversable, } from "./relationship_types.js";
+import { ChildOf, DependsOn, Exclusive, OneOf, OwnedTarget, SilenceSource, Traversable, With, } from "./relationship_types.js";
+export { ChildOf, DependsOn, Exclusive, OneOf, OwnedTarget, SilenceSource, Traversable, With, } from "./relationship_types.js";
 /**
  * Built-in world module that registers the `ChildOf` relationship and
  * maintains ownership and depth tracking policies for relationship traits.
@@ -11,16 +11,26 @@ export { ChildOf, DependsOn, OwnedTarget, SilenceSource, Traversable, } from "./
  * destroying a parent recursively destroys the children that target it through
  * `ChildOf` (custom relationships default to `Remove`).
  *
- * When a relationship component entity has `Traversable` attached, the module
- * installs `onAdd`, `onSet`, and `onRemove` hooks on that relationship so that
- * every entity's depth is updated when the relationship is added, retargeted,
- * or removed.
+ * `Traversable` requires `Exclusive`. The module wraps target-edge hooks on a
+ * traversable relationship so every entity's depth is updated when its edge is
+ * added, replaced, or removed.
  *
  * When a relationship component entity has `OwnedTarget` attached, the module
- * wraps its hooks so adding the relationship creates a target when needed,
- * every target becomes a `ChildOf` child of its source, and targets are
- * destroyed when displaced or removed. Configure this trait after the
- * relationship's owner hooks and before creating relationship instances.
+ * wraps its target-edge hooks so every explicitly added target becomes a
+ * `ChildOf` child of its source and is destroyed when displaced or removed.
+ * `OwnedTarget` requires `Exclusive` and never creates a target implicitly.
+ *
+ * `OneOf` constrains the targets of a relationship to direct `ChildOf`
+ * children of a specified parent entity. Attach during setup as
+ * `relationship.add(OneOf, parent)`; the module installs a per-edge policy that
+ * rejects targets whose `ChildOf` parent is not the declared parent. `OneOf`
+ * is irrevocable once attached.
+ *
+ * `OwnedTarget` and `Traversable` are irrevocable once attached: both
+ * `entity.remove(Trait)` and `entity.attach(newInstance)` throw, and the world
+ * must be discarded after the throw. Teardown bypasses these guards —
+ * `Entity._destroy` does not fire `_onPolicyRemove` — so `clearAllEntities`
+ * can still tear down worlds with these traits configured.
  *
  * Depth is computed by walking `entity.target(relEid)` to the root. When an
  * entity's depth changes, every descendant is recursively recomputed.
@@ -29,50 +39,61 @@ export class RelationshipsModule extends Module {
     init() {
         const world = this.world;
         const childOf = world.component(ChildOf);
+        const dependsOn = world.component(DependsOn);
+        const exclusive = world.component(Exclusive);
         const ownedTarget = world.component(OwnedTarget);
-        const traversable = world.component(Traversable);
+        const silenceSource = world.component(SilenceSource);
+        const traversableTrait = world.component(Traversable);
+        const withTrait = world.component(With);
+        const oneOfTrait = world.component(OneOf);
         childOf.meta.onDeleteTarget = CleanupPolicy.Delete;
-        ownedTarget.onAdd((rel) => {
+        exclusive.meta.on("policyAdd", (relationship) => {
+            if (!relationship.meta.isRelationship) {
+                throw new Error("Exclusive can only be added to a Relationship component");
+            }
+            if (relationship.meta.usageCount > 0) {
+                throw new Error("Exclusive cannot be added or removed while the relationship is in use");
+            }
+            relationship.meta.relationshipExclusive = true;
+        });
+        exclusive.meta.on("policyRemove", (relationship) => {
+            if (relationship.has(OwnedTarget) || relationship.has(Traversable)) {
+                throw new Error("Exclusive cannot be removed while a dependent relationship trait exists");
+            }
+            if (relationship.meta.usageCount > 0) {
+                throw new Error("Exclusive cannot be added or removed while the relationship is in use");
+            }
+            relationship.meta.relationshipExclusive = false;
+        });
+        ownedTarget.meta.on("policyAdd", (rel) => {
             if (!rel.meta.isRelationship) {
                 throw new Error("OwnedTarget can only be added to a Relationship component");
             }
             if (rel === childOf) {
                 throw new Error("OwnedTarget cannot be added to ChildOf");
             }
-            const onAdd = rel.onAdd();
-            const onSet = rel.onSet();
-            const onRetarget = rel.onRetarget();
-            const onRemove = rel.onRemove();
-            rel
-                .onAdd((source, component) => {
-                const relationship = component;
-                relationship.target ?? (relationship.target = world.entity());
-                relationship.target.childOf(source);
-                onAdd?.(source, component);
-            })
-                .onSet((source, relationship) => {
-                relationship.target.childOf(source);
-                onSet?.(source, relationship);
-            })
-                .onRetarget((source, oldTarget, newTarget) => {
-                oldTarget.destroy();
-                onRetarget?.(source, oldTarget, newTarget);
-            })
-                .onRemove((source, relationship) => {
-                relationship.target.destroy();
-                onRemove?.(source, relationship);
-            });
+            if (!rel.has(Exclusive)) {
+                throw new Error("OwnedTarget requires Exclusive");
+            }
+            rel.meta.on("targetPolicyAdd", (source, _relationship, target) => target.add(ChildOf, source));
+            rel.meta.on("targetPolicyRemove", (_source, _relationship, target) => target.destroy());
         });
-        traversable.onAdd((rel, traversable) => {
+        ownedTarget.meta.on("policyRemove", () => {
+            throw new Error("OwnedTarget cannot be removed once added");
+        });
+        traversableTrait.meta.on("policyAdd", (rel, component) => {
+            if (!rel.meta.isRelationship) {
+                throw new Error("Traversable can only be added to a Relationship component");
+            }
+            if (!rel.has(Exclusive)) {
+                throw new Error("Traversable requires Exclusive");
+            }
+            const traversable = component;
             const relEid = rel.eid;
-            rel
-                .onAdd((entity) => {
+            rel.meta.on("targetPolicyAdd", (entity) => {
                 this._cascadeUpdate(entity, relEid, traversable);
-            })
-                .onSet((entity) => {
-                this._cascadeUpdate(entity, relEid, traversable);
-            })
-                .onRemove((entity) => {
+            });
+            rel.meta.on("targetPolicyRemove", (entity) => {
                 traversable.depths.delete(entity);
                 for (const child of entity._childrenByEid(relEid) ?? []) {
                     this._cascadeUpdate(child, relEid, traversable);
@@ -84,7 +105,43 @@ export class RelationshipsModule extends Module {
                 }
             });
         });
-        childOf.add(Traversable);
+        traversableTrait.meta.on("policyRemove", () => {
+            throw new Error("Traversable cannot be removed once added");
+        });
+        withTrait.meta.on("targetPolicyAdd", (xEntity, _withRelationship, yEntity) => {
+            const xMeta = xEntity.meta;
+            const yMeta = yEntity.meta;
+            if (xMeta.isRelationship !== yMeta.isRelationship) {
+                throw new Error("With: the component and its target must both be relationships or both be plain components");
+            }
+            if (xMeta.usageCount > 0) {
+                throw new Error("With cannot be added while the target component is in use");
+            }
+            if (xMeta.isRelationship) {
+                xMeta.on("targetPolicyAdd", (source, _rel, target) => source.add(yEntity, target));
+            }
+            else {
+                xMeta.on("policyAdd", (entity) => entity.add(yEntity));
+            }
+        });
+        this._forbidPairTraitRemoval(withTrait, "With");
+        oneOfTrait.meta.on("targetPolicyAdd", (rel, _oneOf, parent) => {
+            if (!rel.meta.isRelationship) {
+                throw new Error("OneOf can only be added to a Relationship component");
+            }
+            if (rel.meta.usageCount > 0) {
+                throw new Error("OneOf cannot be added while the relationship is in use");
+            }
+            rel.meta.on("targetPolicyAdd", (_source, _relationship, target) => {
+                if (target.parent !== parent) {
+                    throw new Error(`OneOf: target ${target.eid} is not a child of entity ${parent.eid}`);
+                }
+            });
+        });
+        this._forbidPairTraitRemoval(oneOfTrait, "OneOf");
+        childOf.add(Exclusive).add(Traversable);
+        dependsOn.add(Exclusive).add(Traversable);
+        silenceSource.add(Exclusive);
     }
     _cascadeUpdate(entity, relEid, traversable, visited = new Set()) {
         if (visited.has(entity)) {
@@ -116,5 +173,24 @@ export class RelationshipsModule extends Module {
         }
         return this._depthOf(parent, relEid, traversable, visited) + 1;
     }
+    /**
+     * Make a pair-form trait irrevocable: removing an edge of `trait` throws
+     * once attached.
+     *
+     * Teardown fires `targetPolicyRemove` from two paths: `_detachRelationship`
+     * on the trait carrier (after `carrier._destroyed = true`) and the cleanup
+     * cascade when the pair target is destroyed (buffered via `_cleanupIncoming`
+     * → `_removeTarget`, where the carrier is still alive but the target is
+     * already gone). Skip the irrevocability guard in either case; see the
+     * teardown contract in the class JSDoc.
+     */
+    _forbidPairTraitRemoval(trait, name) {
+        trait.meta.on("targetPolicyRemove", (carrier, _trait, target) => {
+            if (carrier.destroyed || target.destroyed) {
+                return;
+            }
+            throw new Error(`${name} cannot be removed once added`);
+        });
+    }
 }
 //# sourceMappingURL=relationships.js.map

package/dist/modules/relationships.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.js","sourceRoot":"","sources":["../../src/modules/relationships.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE5E,OAAO,EACL,OAAO,EACP,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,MAAM;IACtC,IAAI;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QACjD,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAEjD,OAAO,CAAC,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC;QAEnD,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,EAAQ,EAAE;YAC9B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;YAC/E,CAAC;YACD,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC5D,CAAC;YAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;YAEhC,GAAG;iBACA,KAAK,CAAC,CAAC,MAAc,EAAE,SAAS,EAAQ,EAAE;gBACzC,MAAM,YAAY,GAAG,SAAyB,CAAC;gBAC/C,YAAY,CAAC,MAAM,KAAnB,YAAY,CAAC,MAAM,GAAK,KAAK,CAAC,MAAM,EAAE,EAAC;gBACvC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC7B,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,MAAc,EAAE,YAAY,EAAQ,EAAE;gBAC3C,YAA6B,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACtD,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAChC,CAAC,CAAC;iBACD,UAAU,CAAC,CAAC,MAAc,EAAE,SAAiB,EAAE,SAAiB,EAAQ,EAAE;gBACzE,SAAS,CAAC,OAAO,EAAE,CAAC;gBACpB,UAAU,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAC7C,CAAC,CAAC;iBACD,QAAQ,CAAC,CAAC,MAAc,EAAE,YAAY,EAAQ,EAAE;gBAC9C,YAA6B,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChD,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;QAEH,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,WAAW,EAAQ,EAAE;YAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC;YAEvB,GAAG;iBACA,KAAK,CAAC,CAAC,MAAc,EAAE,EAAE;gBACxB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;YACnD,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,MAAc,EAAE,EAAE;gBACxB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;YACnD,CAAC,CAAC;iBACD,QAAQ,CAAC,CAAC,MAAc,EAAE,EAAE;gBAC3B,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAElC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;oBACxD,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC,CAAC,CAAC;YAEL,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;gBAChC,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAEO,cAAc,CACpB,MAAc,EACd,MAAW,EACX,WAAwB,EACxB,UAAU,IAAI,GAAG,EAAU;QAE3B,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEpB,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;QACxF,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACxD,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAEO,QAAQ,CACd,MAAc,EACd,MAAW,EACX,WAAwB,EACxB,OAAoB;QAEpB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/C,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEpB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACtD,OAAO,WAAW,GAAG,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;CACF"}
+{"version":3,"file":"relationships.js","sourceRoot":"","sources":["../../src/modules/relationships.ts"],"names":[],"mappings":"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"}

package/dist/modules/singleton.js

@@ -23,12 +23,12 @@ export class Singleton {
  */
 export class SingletonModule extends Module {
     init() {
-        this.world.component(Singleton).onAdd((target) => {
+        this.world.component(Singleton).on("add", (target) => {
             const targetMeta = target.meta;
             if (targetMeta.usageCount !== 0) {
                 throw new Error(`Cannot make component ${targetMeta.Class.name} singleton; ${targetMeta.usageCount} instance(s) already exist`);
             }
-            targetMeta.onAdd((entity) => {
+            targetMeta.on("add", (entity) => {
                 if (entity !== target || targetMeta.usageCount !== 1) {
                     throw new Error(`Cannot add singleton component ${targetMeta.Class.name} to entity ${entity.eid}; singleton instance is entity ${target.eid}`);
                 }

package/dist/modules/singleton.js.map

@@ -1 +1 @@
-{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/modules/singleton.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,SAAS;CAAG;AAEzB;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM;IAClC,IAAI;QACT,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,MAAc,EAAQ,EAAE;YAC7D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC;YAC/B,IAAI,UAAU,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,CAAC,KAAK,CAAC,IAAI,eAAe,UAAU,CAAC,UAAU,4BAA4B,CAC/G,CAAC;YACJ,CAAC;YAED,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC1B,IAAI,MAAM,KAAK,MAAM,IAAI,UAAU,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;oBACrD,MAAM,IAAI,KAAK,CACb,kCAAkC,UAAU,CAAC,KAAK,CAAC,IAAI,cAAc,MAAM,CAAC,GAAG,kCAAkC,MAAM,CAAC,GAAG,EAAE,CAC9H,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/modules/singleton.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,SAAS;CAAG;AAEzB;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM;IAClC,IAAI;QACT,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,MAAc,EAAQ,EAAE;YACjE,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC;YAC/B,IAAI,UAAU,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,CAAC,KAAK,CAAC,IAAI,eAAe,UAAU,CAAC,UAAU,4BAA4B,CAC/G,CAAC;YACJ,CAAC;YAED,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE;gBAC9B,IAAI,MAAM,KAAK,MAAM,IAAI,UAAU,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;oBACrD,MAAM,IAAI,KAAK,CACb,kCAAkC,UAAU,CAAC,KAAK,CAAC,IAAI,cAAc,MAAM,CAAC,GAAG,kCAAkC,MAAM,CAAC,GAAG,EAAE,CAC9H,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/modules/snapshot.d.ts

@@ -0,0 +1,26 @@
+import { Module } from "../module.js";
+export { type ResolvedSnapshotPolicy, type SnapshotCapture, type SnapshotMaterialize, type SnapshotPolicyType, ClonePublic, CustomSnapshot, DontSnapshot, OnSnapshot, _declareSnapshotPolicy, _resolveSnapshotPolicy, } from "./snapshot_types.js";
+/**
+ * Built-in world module that registers the `OnSnapshot` trait and its policy
+ * values.
+ *
+ * Registered automatically by every {@link World}. `OnSnapshot` is an
+ * `Exclusive` pair-form trait restricted with {@link OneOf} to its own policy
+ * children, so a component entity always names exactly one policy:
+ * {@link ClonePublic} (the default), {@link DontSnapshot}, or
+ * {@link CustomSnapshot}.
+ *
+ * A policy may be declared, changed, or revoked at any time. It does not have to
+ * precede the component's first carrier, because a capture *binds* the
+ * materializer it resolved: {@link World.snapshotSubtree} stores that function
+ * in each record, so a snapshot always restores the way it was captured and a
+ * later policy declaration cannot retroactively change one.
+ *
+ * The module also marks vecs' own world-bound component types
+ * {@link DontSnapshot}: a
+ * live {@link Query} or {@link System} owns live membership, pending events, and
+ * pipeline slots, so it can never be reconstructed in another world.
+ */
+export declare class SnapshotModule extends Module {
+    init(): void;
+}

package/dist/modules/snapshot.js

@@ -0,0 +1,45 @@
+// `SnapshotModule` installs the `OnSnapshot` trait's runtime invariants. The
+// trait, its policy values, and the declaration helpers live in
+// `snapshot_types.ts`, which is dependency-light on purpose: `component.ts`
+// imports it, so it must not reach back through `module.ts`.
+import { Module } from "../module.js";
+import { Query } from "../query/index.js";
+import { System } from "../system.js";
+import { Exclusive, OneOf } from "./relationship_types.js";
+import { ClonePublic, CustomSnapshot, DontSnapshot, OnSnapshot } from "./snapshot_types.js";
+export { ClonePublic, CustomSnapshot, DontSnapshot, OnSnapshot, _declareSnapshotPolicy, _resolveSnapshotPolicy, } from "./snapshot_types.js";
+/**
+ * Built-in world module that registers the `OnSnapshot` trait and its policy
+ * values.
+ *
+ * Registered automatically by every {@link World}. `OnSnapshot` is an
+ * `Exclusive` pair-form trait restricted with {@link OneOf} to its own policy
+ * children, so a component entity always names exactly one policy:
+ * {@link ClonePublic} (the default), {@link DontSnapshot}, or
+ * {@link CustomSnapshot}.
+ *
+ * A policy may be declared, changed, or revoked at any time. It does not have to
+ * precede the component's first carrier, because a capture *binds* the
+ * materializer it resolved: {@link World.snapshotSubtree} stores that function
+ * in each record, so a snapshot always restores the way it was captured and a
+ * later policy declaration cannot retroactively change one.
+ *
+ * The module also marks vecs' own world-bound component types
+ * {@link DontSnapshot}: a
+ * live {@link Query} or {@link System} owns live membership, pending events, and
+ * pipeline slots, so it can never be reconstructed in another world.
+ */
+export class SnapshotModule extends Module {
+    init() {
+        const world = this.world;
+        const onSnapshot = world.component(OnSnapshot);
+        world.component(ClonePublic).childOf(onSnapshot);
+        world.component(DontSnapshot).childOf(onSnapshot);
+        world.component(CustomSnapshot).childOf(onSnapshot);
+        onSnapshot.add(OneOf, onSnapshot);
+        onSnapshot.add(Exclusive);
+        world.component(Query).snapshotPolicy(DontSnapshot);
+        world.component(System).snapshotPolicy(DontSnapshot);
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/modules/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/modules/snapshot.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,gEAAgE;AAChE,4EAA4E;AAC5E,6DAA6D;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE5F,OAAO,EAKL,WAAW,EACX,cAAc,EACd,YAAY,EACZ,UAAU,EACV,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,cAAe,SAAQ,MAAM;IACjC,IAAI;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAE/C,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACjD,KAAK,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAClD,KAAK,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAEpD,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAClC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE1B,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QACpD,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/modules/snapshot_types.d.ts

@@ -0,0 +1,85 @@
+import type { ComponentInstance } from "../component_meta.js";
+import { Relationship } from "../component_meta.js";
+/**
+ * Captures one live component instance into detached, world-agnostic data.
+ *
+ * The returned value is stored in the snapshot and handed back to
+ * {@link SnapshotMaterialize} verbatim, so it must not reference the source
+ * world, its entities, or any mutable instance the source still holds.
+ */
+export type SnapshotCapture = (instance: ComponentInstance) => unknown;
+/**
+ * Constructs one destination-owned component instance from previously captured
+ * data. The returned instance must be freshly constructed and belong to no
+ * other entity.
+ */
+export type SnapshotMaterialize = (data: unknown) => ComponentInstance;
+/**
+ * Built-in pair-form trait declaring how {@link World.snapshotSubtree} captures
+ * one component type.
+ *
+ * The trait is attached to the **component entity**, not to ordinary entities,
+ * and its target selects the policy. It is exclusive, one-of
+ * {@link OneOf | restricted to its own children}. Configure it through the
+ * owning module; declarations affect future captures, while each existing
+ * snapshot retains the materializer bound at its capture time.
+ *
+ * ```ts
+ * // Declare "this type never crosses worlds" (resources, live queries, engines).
+ * world.component(PhysicsEngine).snapshotPolicy(DontSnapshot);
+ *
+ * // Declare a bespoke capture that drops runtime handles.
+ * world.component(Body).snapshotPolicy(CustomSnapshot, {
+ *   capture: (body) => ({ ...body, _bodyId: undefined }),
+ *   materialize: (data) => Object.assign(new Body(), data),
+ * });
+ * ```
+ *
+ * A type with no {@link OnSnapshot} edge uses {@link ClonePublic}, so ordinary
+ * plain-data components need no declaration at all.
+ */
+export declare class OnSnapshot extends Relationship {
+    /**
+     * Capture hook for the {@link CustomSnapshot} policy. `undefined` for every
+     * other policy.
+     */
+    capture: SnapshotCapture | undefined;
+    /**
+     * Materialize hook for the {@link CustomSnapshot} policy. `undefined` for
+     * every other policy.
+     */
+    materialize: SnapshotMaterialize | undefined;
+}
+/**
+ * Default snapshot policy: construct a fresh instance of the component class
+ * and clone 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}.
+ */
+export declare class ClonePublic {
+}
+/**
+ * Snapshot policy declaring that a component type never crosses worlds.
+ *
+ * Use it for attached resources and other instances whose identity is bound to
+ * a single world: live queries and systems, engine handles, socket sessions.
+ * A snapshot silently omits an unselected `DontSnapshot` type, but *selecting*
+ * one explicitly is a preflight error, so a caller cannot silently lose state
+ * it asked for.
+ */
+export declare class DontSnapshot {
+}
+/**
+ * Snapshot policy delegating capture and materialization to the owner.
+ *
+ * Register it with {@link Component.snapshotPolicy}, passing the `capture` and
+ * `materialize` callbacks; the callbacks are stored on that component entity's
+ * own {@link OnSnapshot} edge, so each component type keeps a separate policy.
+ */
+export declare class CustomSnapshot {
+}
+/** The policy values accepted by {@link Component.snapshotPolicy}. */
+export type SnapshotPolicyType = typeof ClonePublic | typeof CustomSnapshot | typeof DontSnapshot;