@vworlds/vecs 1.0.44 → 1.0.46

package/docs/components.md

@@ -5,8 +5,9 @@ exclusivity, cleanup policies, interface aliases, and singletons.
 
 ## Components are plain data classes
 
-A component is an ordinary class with field initializers and a no-argument constructor. It does
-not inherit from a vecs base class — vecs instantiates it with `new ComponentClass()`:
+An ordinary component is a class with field initializers and a no-argument constructor. Relationship
+components are the exception: they extend `Relationship` so vecs can recognize their private edge
+storage. Vecs instantiates either form with `new ComponentClass()`:
 
 ```ts
 class Position {
@@ -71,27 +72,30 @@ Pass `idPools` to the `World` constructor to change ranges (each entry is 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.
 
-## Hooks: `onAdd`, `onSet`, `onRemove`, `onRetarget`
+## Hooks: component and relationship edges
 
 The `Component` entity exposes lifecycle hooks fired for every entity carrying the component:
 
 ```ts
 world
   .component(Sprite)
-  .onAdd((entity, sprite) => sprite.initialize(scene, entity))
-  .onSet((entity, sprite) => sprite.syncToScene(entity))
-  .onRemove((entity, sprite) => sprite.destroy(scene, entity));
+  .on("add", (entity, sprite) => sprite.initialize(scene, entity))
+  .on("set", (entity, sprite) => sprite.syncToScene(entity))
+  .on("remove", (entity, sprite) => sprite.destroy(scene, entity));
 ```
 
-| Hook       | Fires when…                                                                                                                                               |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `onAdd`    | The component is first attached (`add`, or `set` on an entity that lacked it).                                                                            |
-| `onSet`    | `entity.set(C, props)` applies data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` / `ensure` marks it dirty. |
-| `onRemove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                                        |
+| Hook     | Fires when…                                                                                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `add`    | The component is first attached (`add`, or `set` on an entity that lacked an ordinary component).                                                                  |
+| `set`    | `entity.set(C, props)` applies ordinary data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` / `ensure` marks it dirty. |
+| `remove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                                                 |
 
-Relationship component entities additionally expose `onRetarget`. It fires after an existing
-relationship changes to a different target, once `target` and `children` already reflect the new
-reverse-index state. Initial assignment, same-target `set`, and removal do not fire it.
+Relationship component entities additionally expose the `targetAdd` and `targetRemove` events. Both
+receive `(source, relationshipInstance, target)` after the edge and reverse index reach their new
+state. An exclusive replacement fires `targetRemove` for the old edge before `targetAdd` for
+the new edge. Adding or removing edges never fires `set`; it is reserved for ordinary fields on
+an existing relationship. See [Relationships — edge hooks](./relationships.md#edge-hooks) for the
+full ordering.
 
 Handlers receive `(entity, componentInstance)` — component instances do not carry entity
 references, so the entity is passed explicitly. Hooks fire synchronously when the corresponding
@@ -99,6 +103,11 @@ 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.
 
+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
+return the component entity for chaining.
+
 ## Component traits: policy on component entities
 
 Registered components are themselves entities. Attach a configuration component to a component
@@ -107,24 +116,30 @@ components **component traits**:
 
 ```ts
 world.component(Gravity).add(Singleton);
-world.component(Inventory).add(OwnedTarget);
-world.component(ChildOf).add(Traversable);
+world.component(Inventory).add(Exclusive).add(OwnedTarget);
+world.component(ChildOf).add(Traversable); // ChildOf is already Exclusive
 world.component(Orange).set(Implements, { interfaces: [Fruit] });
 ```
 
-| Trait/declaration | Applies to                         | Effect                                                               |
-| ----------------- | ---------------------------------- | -------------------------------------------------------------------- |
-| `Singleton`       | Concrete components                | Allows at most one carrier entity                                    |
-| `Implements`      | Non-relationship components        | Exposes concrete data through abstract aliases                       |
-| `Traversable`     | Relationships                      | Maintains hierarchy depth for cascade ordering                       |
-| `OwnedTarget`     | Relationships other than `ChildOf` | Owns the active target through `ChildOf` and destructive replacement |
+| Trait/declaration | Applies to                                   | Effect                                                                       |
+| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| `Singleton`       | Concrete components                          | Allows at most one carrier entity                                            |
+| `Implements`      | Non-relationship components                  | Exposes concrete data through abstract aliases                               |
+| `Exclusive`       | Relationships                                | Restricts the relationship to one target with atomic replacement             |
+| `Traversable`     | Exclusive relationships                      | Maintains hierarchy depth for cascade ordering                               |
+| `OwnedTarget`     | Exclusive relationships other than `ChildOf` | Owns each explicit target through `ChildOf` and destructive edge replacement |
+| `OneOf`           | Relationships                                | Constrains each target to be a direct `ChildOf` child of a declared parent   |
 
 Traits declare policy; their built-in modules install the hooks and maintain the metadata that
 enforce it. Configure traits in feature-module setup rather than opportunistically inside systems.
 Do not assume all traits have the same lifecycle:
 
 - Add `Singleton` before component instances exist.
-- Add `OwnedTarget` before relationship instances exist; it does not backfill.
+- Add `Exclusive` before relationship instances exist. `OwnedTarget` and `Traversable` require it.
+- Add `OwnedTarget` before relationship instances exist; it never creates a target implicitly and
+  does not replace public edge hooks.
+- Add `OneOf` before relationship instances exist; it rejects every target that is not a direct
+  `ChildOf` child of the declared parent.
 - `Traversable` backfills existing relationship instances.
 - Setting or removing `Implements` recomputes interface aliases.
 
@@ -139,8 +154,10 @@ class Audited {}
 
 class AuditModule extends Module {
   public init(): void {
-    this.world.component(Audited).onAdd((component) => {
-      component.onSet((entity) => console.log("changed", component.meta.Class.name, entity.eid));
+    this.world.component(Audited).on("add", (component) => {
+      component.on("set", (entity) =>
+        console.log("changed", component.meta.Class.name, entity.eid)
+      );
     });
   }
 }
@@ -171,17 +188,22 @@ at any time. Exclusivity is how you model "exactly one of N" (one renderable per
 physics shape per body) — and it makes type swaps clean, because replacing the component fires the
 old one's `exit`/`onRemove` automatically.
 
+This is distinct from the `Exclusive` relationship trait. `setExclusiveComponents(A, B)` chooses
+which **component class** may exist; `world.component(R).add(Exclusive)` allows one instance of
+relationship `R` as usual but limits it to one **target edge**, replacing that edge atomically. See
+[Relationships — exclusive one-target relationships](./relationships.md#exclusive-one-target-relationships).
+
 ## Cleanup policies: destroying a component entity
 
 Every component key is backed by a component entity. What happens when you destroy that entity
 while other entities still carry the component is controlled by `meta.onDelete`
 (`CleanupPolicy` in `lib/vecs/src/component_meta.ts`):
 
-| Policy                 | Meaning                                                                                            |
-| ---------------------- | -------------------------------------------------------------------------------------------------- |
-| `CleanupPolicy.Throw`  | Default. Destroying the component entity while other entities carry it throws and changes nothing. |
-| `CleanupPolicy.Remove` | Remove the component from every carrier, then destroy the component entity.                        |
-| `CleanupPolicy.Delete` | Destroy every carrier entity, then destroy the component entity.                                   |
+| Policy                 | Meaning                                                                                                                                                                                                                                                                                                  |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CleanupPolicy.Throw`  | Default. Destroying the component entity while other entities carry it throws. The synchronous `destroy()` call throws before mutating anything, so the world stays usable; a `Throw` policy reached during a deferred drain or a relationship cascade throws and leaves the world partial — discard it. |
+| `CleanupPolicy.Remove` | Remove the component from every carrier, then destroy the component entity.                                                                                                                                                                                                                              |
+| `CleanupPolicy.Delete` | Destroy every carrier entity, then destroy the component entity.                                                                                                                                                                                                                                         |
 
 ```ts
 import { CleanupPolicy } from "@vworlds/vecs";
@@ -191,7 +213,29 @@ world.component(Temporary).destroy(); // strips Temporary from all carriers
 ```
 
 The `Throw` default also applies to plain entities used as component keys (`entity.add(keyEntity)`).
-A failed destroy leaves the component entity, its carriers, and the usage count untouched.
+
+## Snapshot policies: what a component may cross worlds with
+
+A component type also declares how
+[subtree snapshots](./snapshots.md) capture it, through `world.component(Type).snapshotPolicy(...)`.
+The default — no declaration — deep-copies the instance's own enumerable fields, and **fails
+loudly at capture** on a nested value that is not plain data, so a component carrying a class
+instance must declare a policy saying how that instance is detached. `DontSnapshot` marks a
+type as world-bound (an engine handle, a socket, a live `Query`), and `CustomSnapshot` with
+`capture` / `materialize` callbacks is how a type that mixes declarative and runtime state hands over
+only the declarative half:
+
+```ts
+world.component(PhysicsEngine).snapshotPolicy(DontSnapshot);
+```
+
+A policy is declared by the owning module and may change at any time: a capture binds the
+materializer its policy resolved to, so an existing snapshot always restores the way it was
+captured.
+A synchronous `destroy()` throw (component still in use) leaves the world usable. A throw during
+deferred drain or a cascade is irrecoverable — the component entity, its carriers, and the usage
+count are in a partial state and the world must be discarded. Configure cleanup policies so cascades
+are consistent; treat a mid-destroy throw as a programming error.
 
 Relationship components have a second, independent policy — `meta.onDeleteTarget` — that governs
 what happens to _sources_ when a relationship **target** is destroyed. See
@@ -279,7 +323,7 @@ the live object itself as a component** with `entity.attach(obj)` instead of kee
 const obj = scene.add.arc(0, 0); // a Phaser GameObject
 entity.attach(obj); // the GameObject is now a component, keyed by its class
 
-world.component(Phaser.GameObjects.Arc).onRemove((_entity, obj) => obj.destroy());
+world.component(Phaser.GameObjects.Arc).on("remove", (_entity, obj) => obj.destroy());
 ```
 
 The entity's component set then _is_ the resource lifecycle: queries drive create/destroy, and
@@ -306,22 +350,21 @@ interface markers for polymorphic dispatch — is in the
 A `Component<T>` is an `Entity` subclass, so the full [entity API](./entities.md#reference)
 applies. On top of it:
 
-| Member                | Description                                                          |
-| --------------------- | -------------------------------------------------------------------- |
-| `onAdd(handler)`      | Register an add hook. Returns the component entity for chaining.     |
-| `onRemove(handler)`   | Register a remove hook.                                              |
-| `onRetarget(handler)` | Register a relationship retarget hook. Throws for non-relationships. |
-| `onSet(handler)`      | Register a set/modified hook.                                        |
-| `meta`                | The `ComponentMeta` bookkeeping record.                              |
+| Member                        | Description                                                                                                                                                                                                                                                                                                      |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `on(event, handler, insert?)` | Register a handler for `add` / `remove` / `set` / `targetAdd` / `targetRemove` (plus the internal `policyAdd` / `policyRemove` / `targetPolicyAdd` / `targetPolicyRemove` events). `insert` defaults to `false` (append); `true` prepends. Rejects `target*` events on non-relationships. Returns the component. |
+| `off(event, handler)`         | Remove a previously-registered handler by reference. Idempotent. Returns the component.                                                                                                                                                                                                                          |
+| `meta`                        | The `ComponentMeta` bookkeeping record.                                                                                                                                                                                                                                                                          |
 
 ### `ComponentMeta` (`lib/vecs/src/component_meta.ts`)
 
-| Field            | Description                                                                                   |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| `Class`          | The component class constructor.                                                              |
-| `eid`            | Component entity id assigned at registration.                                                 |
-| `bitPtr`         | Pre-computed bit pointer into entity archetype bitsets.                                       |
-| `isRelationship` | `true` when the class extends `Relationship`.                                                 |
-| `onDelete`       | `CleanupPolicy` applied to carriers when the component entity is destroyed. Default `Throw`.  |
-| `onDeleteTarget` | `CleanupPolicy` applied to sources when a relationship target is destroyed. Default `Remove`. |
-| `usageCount`     | Number of entities currently carrying this component.                                         |
+| Field                   | Description                                                                                   |
+| ----------------------- | --------------------------------------------------------------------------------------------- |
+| `Class`                 | The component class constructor.                                                              |
+| `eid`                   | Component entity id assigned at registration.                                                 |
+| `bitPtr`                | Pre-computed bit pointer into entity archetype bitsets.                                       |
+| `isRelationship`        | `true` when the class extends `Relationship`.                                                 |
+| `relationshipExclusive` | `true` when the relationship carries the `Exclusive` trait.                                   |
+| `onDelete`              | `CleanupPolicy` applied to carriers when the component entity is destroyed. Default `Throw`.  |
+| `onDeleteTarget`        | `CleanupPolicy` applied to sources when a relationship target is destroyed. Default `Remove`. |
+| `usageCount`            | Number of entities currently carrying this component.                                         |

package/docs/concepts.md

@@ -12,21 +12,22 @@ every idiom in the [Design guide](./design-guide.md) is a consequence of taking
 
 ## The pieces
 
-| Concept                  | What it is                                                                                                  |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| **World**                | Central container. Owns every entity, registered component, query, system, and the flat system pipeline.    |
-| **Entity**               | A numeric id (`eid`) with a set of components attached. Created via the world.                              |
-| **Component**            | A registered plain data class with a no-argument constructor. No behavior.                                  |
-| **System**               | A `Query` plus per-tick logic (`update`, `each`, `run`), assigned to one pipeline phase.                    |
-| **Query**                | A reactive, always-up-to-date set of entities matching a predicate, with `enter`/`exit`/`update` callbacks. |
-| **Filter**               | A non-reactive, one-shot scan: walks all world entities on each `forEach` call.                             |
-| **Hook**                 | Lightweight component callbacks (`onAdd` / `onSet` / `onRemove`, plus relationship `onRetarget`).           |
-| **Phase**                | Marker component for entities used as pipeline ordering anchors.                                            |
-| **Relationship**         | A component whose `target` field points at another entity, with reverse lookup and cleanup cascades.        |
-| **Component trait**      | Policy attached to a component entity, configuring every use of that component type.                        |
-| **Module**               | A unit of packaging: a class whose `init()` registers components, systems, phases, and policy.              |
-| **Exclusive components** | A group of components where at most one may exist on any entity at a time.                                  |
-| **Implements**           | Declares abstract/interface component aliases for a concrete component, for polymorphic queries.            |
+| Concept                    | What it is                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **World**                  | Central container. Owns every entity, registered component, query, system, and the flat system pipeline.     |
+| **Entity**                 | A numeric id (`eid`) with a set of components attached. Created via the world.                               |
+| **Component**              | A registered plain data class with a no-argument constructor. No behavior.                                   |
+| **System**                 | A `Query` plus per-tick logic (`update`, `each`, `run`), assigned to one pipeline phase.                     |
+| **Query**                  | A reactive, always-up-to-date set of entities matching a predicate, with `enter`/`exit`/`update` callbacks.  |
+| **Filter**                 | A non-reactive, one-shot scan: walks all world entities on each `forEach` call.                              |
+| **Hook**                   | Lightweight component callbacks (`onAdd` / `onSet` / `onRemove`, plus relationship edge hooks).              |
+| **Phase**                  | Marker component for entities used as pipeline ordering anchors.                                             |
+| **Relationship**           | A component holding explicit edges to one or more target entities, with reverse lookup and cleanup cascades. |
+| **Component trait**        | Policy attached to a component entity, configuring every use of that component type.                         |
+| **Module**                 | A unit of packaging: a class whose `init()` registers components, systems, phases, and policy.               |
+| **Exclusive components**   | A group of components where at most one may exist on any entity at a time.                                   |
+| **Exclusive relationship** | A relationship carrying `Exclusive`, restricting each source to at most one target.                          |
+| **Implements**             | Declares abstract/interface component aliases for a concrete component, for polymorphic queries.             |
 
 ## Data vs. behavior
 
@@ -46,8 +47,11 @@ right components, and adding a capability to an entity is just adding a componen
 
 Because a registered component is also an entity, it can itself carry components. Built-in
 **component traits** use that meta-ECS layer to declare reusable policy: `Singleton` constrains a
-component, `Implements` declares aliases, and `Traversable` / `OwnedTarget` configure relationships.
-The trait remains data; a module owns the hooks and metadata behavior it activates.
+component, `Implements` declares aliases, `Exclusive` constrains relationship cardinality, and
+`Traversable` / `OwnedTarget` configure exclusive relationships. The trait remains data; a module
+owns the hooks and metadata behavior it activates. Relationship `Exclusive` is unrelated to an
+exclusive component group: one limits edge count, while the other limits coexisting component
+types.
 
 Prefer many small, single-purpose components over one large one. An entity that never rotates
 simply omits `Rotation`; absence encodes "not applicable". See