@vworlds/vecs 1.0.44 → 1.0.46

package/docs/execution-model.md

@@ -49,9 +49,9 @@ world.system("Render").phase(ON_STORE).with(Sprite, Position).each([Sprite, Posi
 ```
 
 `.phase(anchor)` accepts a phase name or an entity. It sets `DependsOn` on the system's backing
-entity (replacing any previous target) and tags the anchor with `Phase`, creating the anchor
-entity if the name is new. **A system lives in exactly one phase.** If a concern needs work in two
-phases, split it into two systems.
+entity (atomically replacing its previous exclusive edge) and tags the anchor with `Phase`,
+creating the anchor entity if the name is new. **A system lives in exactly one phase.** If a concern
+needs work in two phases, split it into two systems.
 
 ### Ordering guarantees
 
@@ -81,7 +81,7 @@ to the spec so the result flattens to systems.
 ### Custom phases: `insertPhaseAfter`
 
 `insertPhaseAfter(phase, anchor)` splices an existing `Phase` entity into the spine directly after
-`anchor`, retargeting the anchor's downstream phases onto the new one:
+`anchor`, replacing the anchor's downstream `DependsOn` edges with edges to the new one:
 
 ```ts
 import { insertPhaseAfter, ON_UPDATE, Phase } from "@vworlds/vecs";
@@ -98,8 +98,14 @@ built-in taxonomy.
 
 Inside a system body, a `Query.forEach` / `Filter.forEach` iteration, or any `world.defer(...)`
 block, the world is in **deferred mode**: entity mutations (`add` / `attach` / `set` / `ensure` /
-`ensureTarget` / `remove` / `destroy` / `modified`, and `world.entity()` creation) are queued as
-commands instead of applied inline. The queue drains when the scope that opened deferral ends.
+`remove` / `destroy` / `modified`, explicit relationship edge additions/removals, and
+`world.entity()` creation) are queued as commands instead of applied inline. The queue drains when
+the scope that opened deferral ends.
+
+All commands share one FIFO queue, including relationship edge commands and commands enqueued by
+hooks while that queue is draining. Their final state is therefore determined by call order. For
+example, deferred `add(R, a)`, `add(R, b)`, `remove(R, a)` leaves only `b`; on an `Exclusive`
+relationship each queued addition atomically replaces the edge present when that command executes.
 
 For the pipeline this means: **a structural change made by system A is applied in the flush
 immediately after A finishes, so it is visible to every later system in the same tick** — later in
@@ -119,8 +125,10 @@ While a mutation is queued but not yet applied, reads return the pre-mutation st
 | `entity.ensure(C)`        | A mutable component, even when newly created.              |
 | `entity.remove(C)`        | Still the component instance.                              |
 
-`entity.ensureTarget(R)` similarly returns one shared pending target while `entity.target(R)`
-continues to return the previously committed target until flush.
+Relationship reads follow the same committed-state rule. After queued `add(R, target)` or
+`remove(R, target)`, `has(R)`, `target(R)`, `targets(R)`, `hasTarget(R, target)`, and reverse
+`children(R)` continue to report the state from before the deferred scope until the FIFO queue
+applies those edge commands.
 
 Outside any deferred scope (top-level user code), the same calls execute inline and effects are
 visible immediately.
@@ -146,6 +154,8 @@ component:
 
 - **Hooks** (`onAdd` / `onSet` / `onRemove`) fire synchronously at the moment the command is
   applied — inline outside deferred mode, or during the drain.
+- **Relationship edge hooks** (`onTargetAdd` / `onTargetRemove`) fire synchronously after each
+  edge and reverse-index change. Edge changes do not fire `onSet`.
 - **Standalone `Query` callbacks** (`enter` / `update` / `exit`) also fire synchronously during
   routing.
 - **Systems** queue events into an ordered **inbox** instead, and replay the inbox at the top of
@@ -157,8 +167,14 @@ Three 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.
   Use that for initialization; leave it off when a separate `enter` owns setup.
-- **`exit` reads a snapshot.** Components injected into an `exit` callback are captured when the
-  exit is routed, so they are still resolvable even though they are being (or have been) removed.
+- **`enter` and `exit` injection read snapshots.** Direct components, singular/plural target
+  projections, and `Iter.src` are captured when the event is routed, so inbox replay retains those
+  component and entity references even if storage or edges change before the system runs. Component
+  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.
 - **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/getting-started.md

@@ -109,12 +109,12 @@ entity:
 ```ts
 world
   .component(Health)
-  .onAdd((entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
-  .onRemove((entity) => console.log(`entity ${entity.eid} died`));
+  .on("add", (entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
+  .on("remove", (entity) => console.log(`entity ${entity.eid} died`));
 ```
 
-`onAdd` fires when the component is first attached, `onRemove` when it is detached or its entity is
-destroyed, and `onSet` whenever its data is set or marked modified.
+The `add` event fires when the component is first attached, `remove` when it is detached or its
+entity is destroyed, and `set` whenever its data is set or marked modified.
 
 ## 6. Spawn entities
 
@@ -167,8 +167,8 @@ world.component(Position);
 world.component(Velocity);
 world
   .component(Health)
-  .onAdd((entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
-  .onRemove((entity) => console.log(`entity ${entity.eid} died`));
+  .on("add", (entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
+  .on("remove", (entity) => console.log(`entity ${entity.eid} died`));
 
 world
   .system("Move")

package/docs/glossary.md

@@ -25,7 +25,7 @@ sources strip/die). [Components](./components.md#cleanup-policies-destroying-a-c
 
 **Companion (wrapper) component** — a local, non-networked component holding a non-ECS resource
 (render object, WASM handle) so the entity's component set drives the resource lifecycle.
-[Components](./components.md#companion-components-for-non-ecs-resources).
+[Components](./components.md#resources-as-components-non-ecs-objects).
 
 **Component** — a registered plain data class with a no-argument constructor; pure data, no
 behavior. [Components](./components.md).
@@ -44,6 +44,10 @@ pipeline). [Execution model](./execution-model.md#deferred-mutation-and-flush-bo
 **Exclusive components** — a declared group where at most one member may exist on an entity;
 setting one removes the others. [Components](./components.md#exclusive-component-groups).
 
+**Exclusive relationship** — a relationship carrying the `Exclusive` trait, restricting each
+source to at most one target. Adding a different edge replaces the current edge. This is separate
+from an exclusive component group. [Relationships](./relationships.md).
+
 **Events** — a minimal typed event emitter helper exported for package-level events. It is not an
 entity lifecycle API. [Utilities](./utilities.md#events).
 
@@ -51,8 +55,8 @@ entity lifecycle API. [Utilities](./utilities.md#events).
 [Queries and filters](./queries-and-filters.md#filters-one-shot-scans).
 
 **Hook** — an `onAdd` / `onSet` / `onRemove` callback registered per component class, or an
-`onRetarget` callback for relationships, fired synchronously at the mutation site.
-[Components](./components.md#hooks-onadd-onset-onremove-onretarget).
+`onTargetAdd` / `onTargetRemove` callback for relationship edges, fired synchronously at the
+mutation site. [Components](./components.md#hooks-component-and-relationship-edges).
 
 **Implements / interface alias** — a declaration that a concrete component is queryable through
 abstract/interface component types; aliases are read-only views of the same instance.
@@ -62,7 +66,8 @@ abstract/interface component types; aliases are read-only views of the same inst
 top of the system's run. [Execution model](./execution-model.md#reactive-routing).
 
 **Injection** — resolving component instances per entity into a typed callback tuple, including
-`target` (relationship target's components) and `down` (fan-out over children) markers.
+singular `target` (the first relationship target), plural `targets` (one projection row per target),
+and `down` (fan-out over children) markers.
 [Systems](./systems.md#component-injection).
 
 **Iter** — an opt-in reusable cursor passed to callbacks instead of the bare entity, exposing the
@@ -72,9 +77,10 @@ visited entity and the source entity of each injected slot.
 **Module** — a packaging unit (`class M extends Module<Config>`) whose `init()` registers
 components, systems, and policy once per world. [Modules](./modules.md).
 
-**Owned target entity** — a zero-or-one aggregate entity targeted through a relationship carrying
-the `OwnedTarget` trait. It is parented to the source and destroyed when displaced, when the
-relationship is removed, or when the source dies. [Relationships](./relationships.md#owned-targets).
+**Owned target entity** — an explicitly created zero-or-one aggregate entity targeted through a
+relationship carrying both `Exclusive` and `OwnedTarget`. It is parented to the source and destroyed
+when displaced, when its edge or relationship is removed, or when the source dies.
+[Relationships](./relationships.md#owned-targets).
 
 **Phase** — an entity used as a pipeline ordering anchor (tagged with the `Phase` component);
 systems attach to exactly one phase via `DependsOn`.
@@ -90,8 +96,10 @@ ordered query over system entities. [Execution model](./execution-model.md#the-p
 `source` / `parent` / `children` / `test`).
 [Queries and filters](./queries-and-filters.md#the-query-dsl).
 
-**Relationship** — a component with a `target: Entity` field linking its source entity to a target,
-with reverse lookup (`children`) and cleanup cascades. [Relationships](./relationships.md).
+**Relationship** — a component holding explicit edges from its source entity to one or more targets,
+with `target` / `targets` / `hasTarget` lookup, reverse lookup (`children`), and cleanup cascades.
+Target storage is private; mutate edges with `add(Rel, target)` and `remove(Rel, target)`.
+[Relationships](./relationships.md).
 
 **Silence domain / `ignoreSource`** — a query configuration that drops `update` events originating
 from systems matching another query, breaking write feedback loops.
@@ -109,7 +117,8 @@ how often a system fires. [Systems](./systems.md#cadence-interval-rate-and-tick-
 
 **Trait (component trait)** — policy attached as a component to a registered component entity,
 configuring every use of that component type. Built-ins include `Singleton`, `Implements`,
-`Traversable`, and `OwnedTarget`. [Components](./components.md#component-traits-policy-on-component-entities).
+`Exclusive`, `Traversable`, and `OwnedTarget`.
+[Components](./components.md#component-traits-policy-on-component-entities).
 
 **Watchlist** — the set of component types a query or system reacts to via `update`, stored as a
 bitmask. [Systems](./systems.md#reactive-callbacks-enter-update-exit).

package/docs/modules.md

@@ -62,7 +62,7 @@ is often one module per item plus a thin umbrella that composes them:
 ```ts
 export class PhaserRenderModule extends Module<{ scene: Scene }> {
   public init(cfg: { scene: Scene }): void {
-    this.world.component(GameObject).onRemove((_e, obj) => obj.destroy()); // GameObject: Implements marker over every Phaser object
+    this.world.component(GameObject).on("remove", (_e, obj) => obj.destroy()); // GameObject: Implements marker over every Phaser object
     this.world.module(ArcModule, { scene: cfg.scene });
     this.world.module(RectangleModule, { scene: cfg.scene });
     // … shape modules first …
@@ -89,13 +89,13 @@ Guidelines:
 Every `World` constructor installs these (`lib/vecs/src/world/world.ts`); you interact with their
 _components_, not with the module objects:
 
-| Module                | Provides                                                                                                                                                                                             |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IdentityModule`      | The `Identity` name component and the name → entity index behind `world.entity("name")` / `entity.name`.                                                                                             |
-| `ImplementsModule`    | Maintains [`Implements` interface aliases](./components.md#interface-aliases-with-implements) and their transitive closure.                                                                          |
-| `SingletonModule`     | Enforces the [`Singleton`](./components.md#singletons-and-world-global-data) one-carrier constraint.                                                                                                 |
-| `RelationshipsModule` | Registers `ChildOf`, installs [`OwnedTarget`](./relationships.md#owned-targets) ownership, and maintains [`Traversable` depth tracking](./relationships.md#traversal-order-traversable-and-cascade). |
-| `PipelineModule`      | Creates the eight [built-in phases](./execution-model.md#phases-the-pipeline-spine) and installs the default pipeline query.                                                                         |
+| Module                | Provides                                                                                                                                                                                                                                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IdentityModule`      | The `Identity` name component and the name → entity index behind `world.entity("name")` / `entity.name`.                                                                                                                                                                                       |
+| `ImplementsModule`    | Maintains [`Implements` interface aliases](./components.md#interface-aliases-with-implements) and their transitive closure.                                                                                                                                                                    |
+| `SingletonModule`     | Enforces the [`Singleton`](./components.md#singletons-and-world-global-data) one-carrier constraint.                                                                                                                                                                                           |
+| `RelationshipsModule` | Registers relationship traits, marks built-in single-target relationships `Exclusive`, installs explicit-edge [`OwnedTarget`](./relationships.md#owned-targets) ownership, and maintains exclusive [`Traversable` depth tracking](./relationships.md#traversal-order-traversable-and-cascade). |
+| `PipelineModule`      | Creates the eight [built-in phases](./execution-model.md#phases-the-pipeline-spine) and installs the default pipeline query.                                                                                                                                                                   |
 
 All are exported, so a custom world setup can reuse them.
 

package/docs/queries-and-filters.md

@@ -17,7 +17,7 @@ It is accepted by `query().with`, `system().with`, and `world.filter`:
 | `{ any: [q1, q2] }`    | At least one sub-expression matches                                 |
 | `{ not: q }`           | Sub-expression must not match                                       |
 | `{ only: [A, B] }`     | Entity has exactly `A` and `B`, nothing else                        |
-| `{ target: [R, q] }`   | Relationship `R`'s target matches `q`                               |
+| `{ target: [R, q] }`   | At least one of relationship `R`'s targets matches `q`              |
 | `{ source: [R, q] }`   | Filter-only: some entity targeting this one through `R` matches `q` |
 | `{ parent: q }`        | Built-in `ChildOf` target matches `q`                               |
 | `{ children: q }`      | Filter-only: some `ChildOf` child matches `q`                       |
@@ -36,12 +36,13 @@ Class-valued terms are components — register them first; an unregistered class
 whose changes should re-evaluate it.
 
 `target` and `source` take tuple form only: `{ target: [RelationshipClass, innerDSL] }`. The first
-element must extend `Relationship` (a plain component throws). `target` evaluates the inner DSL
-against the relationship's target; `source` evaluates it against each entity pointing at the
-candidate and matches when at least one does. `parent` / `children` are the same operators
-specialized to `ChildOf`. **`source` and `children` are non-reactive**: exact for each filter
-scan, but rejected by tracked queries and systems. `target` / `parent` are fully reactive — see
-[Relationships](./relationships.md#querying-through-relationships).
+element must extend `Relationship` (a plain component throws). `target` is existential: it evaluates
+the inner DSL against every relationship target and matches when at least one does. `source`
+evaluates it against each entity pointing at the candidate and also matches when at least one does.
+`parent` / `children` are the same operators specialized to the exclusive `ChildOf` relationship.
+**`source` and `children` are non-reactive**: exact for each filter scan, but rejected by tracked
+queries and systems. `target` / `parent` are fully reactive to edge changes and target-side changes
+— see [Relationships](./relationships.md#querying-through-relationships).
 
 ### `QuerySpec`: adding `cascade` and `hint`
 
@@ -144,15 +145,19 @@ Two forms (`lib/vecs/src/query/grouped_query.ts`):
 
 - `groupBy([components], keyFn)` / `groupBy({ inject: [components] }, keyFn)` — bucket by a
   computed key; injected components are watched, so changing them re-keys the entity.
-- `groupBy(RelationshipClass)` / `groupBy({ relationship: RelationshipClass })` — bucket by the
-  relationship's target entity. Moving between buckets is a retarget, a plain data change (see
-  [Relationships](./relationships.md#retargeting)).
+- `groupBy(RelationshipClass)` / `groupBy({ relationship: RelationshipClass })` — place each member
+  in one bucket per relationship target. Adding or removing edges reconciles only the affected
+  buckets; an exclusive replacement moves the member from the old target bucket to the new one.
 
 The result is a `GroupedQuery<K, R>` adding `group(key)`, `groups()`, `groupKeys()`, `groupCount`,
 and `onGroupEnter` / `onGroupExit` callbacks for bucket creation and disposal. Each `Group` exposes
 `key`, `count`, `has`, iteration, and injected `forEach`. Grouping implies tracking. Systems do
 not support `groupBy` — keep the grouped query standalone and read it from a system.
 
+A many-target member can therefore appear in several groups at once. Re-adding an existing edge
+does not duplicate it within a bucket, removing one edge leaves its other buckets intact, and
+destroying a target removes that target's bucket according to normal relationship cleanup.
+
 ## Filters: one-shot scans
 
 `world.filter(spec)` returns a `Filter` (`lib/vecs/src/filter.ts`): a non-reactive predicate that