@vworlds/vecs 1.0.43 → 1.0.45

package/docs/design-guide.md

@@ -152,7 +152,33 @@ world.component(Phaser.GameObjects.Arc).onRemove((_entity, obj) => obj.destroy()
 
 Use them for resource management and cross-cutting reactions that aren't worth a system. (Note
 the difference from systems: hooks are per-component-instance and run at the mutation site;
-systems are queries that run in a phase.)
+systems are queries that run in a phase.) Each event has one handler slot: setting another handler
+replaces it, calling the hook method with no argument reads it, and passing `undefined` removes it.
+
+### Component traits: policy on component entities
+
+A registered component is also an entity. Components attached to that component entity can declare
+policy for every use of the component type; these configuration components are **component traits**:
+
+```ts
+world.component(Gravity).add(Singleton);
+world.component(Inventory).add(OwnedTarget);
+world.component(ChildOf).add(Traversable);
+world.component(Orange).set(Implements, { interfaces: [Fruit] });
+```
+
+| Trait/declaration | Reach for it when                                                          |
+| ----------------- | -------------------------------------------------------------------------- |
+| `Singleton`       | At most one entity may carry the component                                 |
+| `Implements`      | Concrete components should be queryable through abstract aliases           |
+| `Traversable`     | A relationship hierarchy needs depth or cascade ordering                   |
+| `OwnedTarget`     | A relationship is an exclusively owned, zero-or-one entity-valued property |
+
+Traits declare policy; modules implement it through hooks and metadata. Configure them in module
+setup, not inside systems. Lifecycle differs by trait: `OwnedTarget` and `Singleton` are setup-time
+policy, `Traversable` backfills, and `Implements` recomputes declarations. Do not assume traits are
+dynamically removable. See the [Components guide](./components.md#component-traits-policy-on-component-entities)
+for the full model and custom-trait guidance.
 
 ### Exclusive component groups
 
@@ -178,6 +204,21 @@ entity.target(InCell); // the target entity
 world.query("ByCell").with(Networked, Position).groupBy(InCell); // index by target
 ```
 
+Use `entity.ensureTarget(InCell)` when an absent relationship should default to a new independent
+entity. For aggregate parts whose lifetime should remain bound to the source once assigned, attach
+`OwnedTarget` during setup:
+
+```ts
+world.component(Inventory).add(OwnedTarget);
+const inventory = player.ensureTarget(Inventory); // inventory is ChildOf player
+player.add(Inventory); // also creates an owned target
+```
+
+`OwnedTarget` creates a target when the relationship is added, destroys displaced targets on
+retarget, and destroys the current target when the relationship is removed, keeping aggregate
+cleanup aligned with the active relationship. Configure the relationship owner's lifecycle hooks
+before attaching the trait; it wraps those hooks and runs ownership first.
+
 - **`Relationship.target` is an `Entity` — not directly serialisable, but
   relationships can be networked** when listed in `networkComponents`.
   `vecs-protocol` registers `Relationship.prototype.target` as an `"entity"`
@@ -543,6 +584,87 @@ or when the callback is intentionally "future changes only."
 Bucket entities by a relationship target (or a derived key) and look up buckets in O(1) instead of
 scanning. Moving between buckets is a retarget (data change), not a component swap.
 
+### Owned target entities (entity-valued properties)
+
+Before adding a nested object to a component or a side map from owner eid to state, ask whether the
+value is really one ECS sub-entity. Use an owned target when all of these are true:
+
+- The owner has zero or one value for the concern.
+- The value needs its own optional components, systems, or query identity.
+- The value is exclusively owned and never shared.
+- Replacement, relationship removal, and owner destruction should destroy it.
+
+```ts
+class Inventory extends Relationship {}
+class InventoryState {}
+class Capacity {
+  slots = 0;
+}
+class Weight {
+  current = 0;
+}
+
+world.component(Inventory).add(OwnedTarget);
+world.component(InventoryState);
+world.component(Capacity);
+world.component(Weight);
+
+const inventory = player.ensureTarget(Inventory);
+inventory.add(InventoryState).set(Capacity, { slots: 20 }).set(Weight, { current: 0 });
+```
+
+`Inventory` is an entity-valued property of `player`, but it remains entirely inside the ECS.
+Inventory systems operate on inventory entities without adding inventory-specific state to every
+player archetype:
+
+```ts
+world
+  .system("inventory.weight")
+  .with(InventoryState, Weight)
+  .each([Weight], (_inventory, [weight]) => {
+    void weight.current;
+  });
+```
+
+The lifecycle follows from the relationship and trait:
+
+| Operation                              | Result                                   |
+| -------------------------------------- | ---------------------------------------- |
+| `player.add(Inventory)`                | Creates the inventory entity             |
+| First `player.ensureTarget(Inventory)` | Creates and returns the inventory entity |
+| Later `ensureTarget(Inventory)`        | Returns the same target                  |
+| Retarget `Inventory`                   | Destroys the displaced inventory         |
+| Remove `Inventory`                     | Destroys the current inventory           |
+| Destroy `player`                       | `ChildOf` destroys the inventory         |
+
+Inside deferred execution, mutate the entity returned by `ensureTarget`; do not immediately re-read
+the relationship:
+
+```ts
+world.defer(() => {
+  const inventory = player.ensureTarget(Inventory);
+  inventory.set(Capacity, { slots: 20 }); // correct: pending entity is usable
+  player.target(Inventory); // still undefined until flush
+});
+```
+
+Use the narrowest model that fits:
+
+| Need                                                | Model                                      |
+| --------------------------------------------------- | ------------------------------------------ |
+| A few fields sharing the owner's identity/lifecycle | Components directly on the owner           |
+| One composable, exclusively owned sub-entity        | `ensureTarget` + `OwnedTarget`             |
+| One shared or independently living linked entity    | Relationship without `OwnedTarget`         |
+| Zero-to-many subobjects                             | Child entities with identifying components |
+| A non-ECS runtime object                            | `attach(instance)`                         |
+| World-global state                                  | Singleton/component entity                 |
+
+Good fits include an inventory aggregate, equipment loadout, character progression sheet, AI
+blackboard, quest journal, ability book, or unique vehicle subsystem. Individual inventory items,
+abilities, objectives, and other collections should remain separate entities. Networking remains
+explicit: register the relationship and replicate the target's required components; `OwnedTarget`
+itself is local lifecycle policy.
+
 ### Initialize via opt-in `update`-on-entry
 
 When an update callback owns both initialization and later changes, pass `{ onEnter: true }`. The
@@ -559,6 +681,10 @@ system after whatever produces the entity/companion.
 | An imperative runtime object with `start()/stop()/track/enable`        | A **module** + the world's own lifecycle (`clearAllEntities()`, closing the world). Systems live on the world; they don't need a wrapper to turn on.                                                      |
 | Builder/factory helpers that _create entities_ (`createArc(world, …)`) | Let callers `world.entity().add(Networked).set(Arc, …).set(FillStyle, …)`. Components are small and optional; the caller adds exactly what it wants.                                                      |
 | 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>`                                 | Use `owner.ensureTarget(Rel)`; add `OwnedTarget` only for exclusive destructive ownership.                                                                                                                |
+| `OwnedTarget` on `CurrentEnemy`, `InCell`, `Team`, or shared state     | Use a normal relationship; retargeting or removal of an owned relationship 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.                                                                                                                                             |
@@ -588,6 +714,14 @@ system after whatever produces the entity/companion.
   `vecs-protocol` registers it as an `"entity"` wire field (u32 eid) at module
   load, so `Relationship` subclasses listed in `networkComponents` serialise
   correctly.
+- **Component traits have trait-specific setup semantics.** In particular, configure `OwnedTarget`
+  before creating relationship instances; it does not backfill.
+- **`OwnedTarget` is destructive and exclusive.** Retargeting destroys the old target, removing the
+  relationship destroys the current target, and owner destruction cascades through `ChildOf`.
+  Never use it for shared teams, cells, enemies, definitions, or other world entities.
+- **Owned targets are zero-or-one.** Use child entities for collections, and during deferred
+  execution mutate the entity returned by `ensureTarget` instead of re-reading `target(R)` before
+  flush.
 - **`world.module(M)` runs `init` once.** Re-registering with a different config throws.
 
 ---

package/docs/entities.md

@@ -47,6 +47,8 @@ for end-of-session teardown, not selective resets.
 e.add(Position); // attach with default field values (idempotent)
 e.set(Position, { x: 100 }); // attach if needed, assign props, fire onSet/update
 e.get(Position); // Readonly<Position> | undefined
+e.ensure(Position, (pos) => (pos.x += 1)); // create if needed, then mutate and notify
+e.ensureTarget(FriendOf); // get or create an independent relationship target
 e.has(Position); // boolean
 e.remove(Position); // detach; fires exit callbacks, then onRemove
 e.modified(Position); // mark changed after in-place mutation
@@ -63,10 +65,12 @@ key.
   `onSet`.
 - `set(C, props)` attaches if needed (firing `onAdd`), copies `props` onto the instance, and fires
   `onSet` plus `update` callbacks.
+- `ensure(C, callback)` creates the component if missing, then lets you mutate it and fires
+  `onAdd` followed by one `onSet`. When the component already exists, it behaves like `getMut`.
 - `modified(C)` fires `onSet`/`update` for data you already mutated in place. Repeated calls are
   coalesced until the world routes the notification.
 
-### `getMut`: mutating in place
+### `getMut` and `ensure`: mutating in place
 
 `get` returns a `Readonly` view. To mutate, use `getMut`, which marks the component modified for
 you:
@@ -83,8 +87,53 @@ e.getMut(Velocity, (vel) => {
 });
 ```
 
-Calling `getMut(C)` without a callback outside deferred mode throws. `getMut` also throws for
-relationship components (retarget with `set` instead — see
+Use `ensure` when absence should mean "create with defaults, then mutate":
+
+```ts
+e.ensure(Velocity, (vel) => {
+  vel.vx = 2;
+});
+```
+
+`ensure` always returns a component for a live entity. Calling it on a destroyed entity throws.
+When several calls ensure the same missing component during one deferred scope, they return the
+same pending instance. The instance remains hidden from `get` and queries until the queue drains,
+but every ensure callback mutates that shared pending value.
+
+Use `ensureTarget` for the corresponding get-or-create operation on a registered relationship:
+
+```ts
+world.component(FriendOf);
+
+const friend = entity.ensureTarget(FriendOf);
+entity.ensureTarget(FriendOf) === friend; // true
+entity.target(FriendOf) === friend; // true after deferred changes flush
+```
+
+When the relationship is absent, `ensureTarget` creates an independent entity and points the
+relationship at it. It does not add `ChildOf`; destroying the source does not destroy the generated
+target. Repeated calls during one deferred scope return the same pending target, while `target`
+continues to expose only committed state until the queue drains.
+
+Mark the relationship with `OwnedTarget` during world setup when its targets should instead be
+owned by their sources:
+
+```ts
+world.component(Inventory).add(OwnedTarget);
+
+const inventory = player.ensureTarget(Inventory);
+inventory.parent === player; // true after deferred changes flush
+
+player.add(Inventory); // also creates an owned target
+```
+
+The relationship module creates a target when an owned relationship is added, adds `ChildOf`
+whenever `Inventory` is assigned, destroys displaced targets on retarget, and destroys the current
+target when the relationship is removed. Destroying `player` therefore also destroys `inventory`.
+See [Relationships](./relationships.md#owned-targets).
+
+Calling `getMut(C)` or `ensure(C)` without a callback outside deferred mode throws. Both methods
+also throw for relationship components (retarget with `set` instead — see
 [Relationships](./relationships.md#retargeting)) and for `Implements` interface aliases.
 
 ### `attach`: storing an existing instance
@@ -111,6 +160,8 @@ Inside a system body, a `forEach`, or a `world.defer` block, all of the mutators
 commands instead of applying immediately, and reads return the pre-mutation state until the queue
 drains. The exact read-after-write rules are tabulated in
 [Execution model — deferred mutation](./execution-model.md#deferred-mutation-and-flush-boundaries).
+`ensure(C)` is the exception for mutable access: it returns a mutable component immediately, but a
+newly created component does not appear in `get(C)` until the queue drains.
 
 Deferred entity creation is idempotent within one deferred scope: if `world.entity()` or
 `getOrCreateEntity(eid)` creates a new entity, `getEntity(eid)`, `entity(eid)`, and later
@@ -133,8 +184,10 @@ it throws while carriers remain ([Components — cleanup policies](./components.
 
 Any entity can serve as a component key: `other.add(keyEntity)` attaches a marker component whose
 type id is the key entity's eid. The key entity's `meta` (created lazily) carries the same hook
-and policy surface as a registered class, and `keyEntity.onAdd/onSet/onRemove(...)` register hooks
-directly. This is how tag-like, runtime-created component types work without declaring a class.
+and policy surface as a registered class, and `keyEntity.onAdd/onSet/onRemove(...)` get, set, or
+remove its single lifecycle handlers directly. This is how tag-like, runtime-created component
+types work without declaring a class. Registered relationship component entities additionally
+expose `onRetarget(...)`.
 
 ## Relationships, in brief
 
@@ -164,6 +217,8 @@ is in [Relationships](./relationships.md).
 | `set(ref, props)`                              | Attach if needed and assign `props`; fires `onSet` and `update` callbacks. Returns `this`.          |
 | `get(ref)`                                     | Read-only component lookup, or `undefined`.                                                         |
 | `getMut(ref)` / `getMut(ref, callback)`        | Mutable lookup that marks the component modified. Callback form required outside deferred mode.     |
+| `ensure(ref)` / `ensure(ref, callback)`        | Mutable lookup that creates when missing. Callback form required outside deferred mode.             |
+| `ensureTarget(Relationship)`                   | Return a relationship target, creating an independent target when absent.                           |
 | `has(ref)`                                     | `true` when the component is attached.                                                              |
 | `modified(ref)`                                | Queue an `onSet`/`update` notification; coalesced while pending. Returns `this`.                    |
 | `remove(ref)`                                  | Detach a component; routes `exit`, then fires `onRemove`.                                           |
@@ -173,5 +228,6 @@ is in [Relationships](./relationships.md).
 | `childOf(parent)`                              | Shorthand for `set(ChildOf, { target: parent })`. Returns `this`.                                   |
 | `parent` / `parent = p`                        | Getter/setter for the built-in `ChildOf` target; assigning `undefined` removes `ChildOf`.           |
 | `destroyed` / `alive`                          | `true` when the entity has been / has not been destroyed (marked for deletion).                     |
-| `onAdd/onSet/onRemove(handler)`                | Register hooks for this entity used as a component key. Return `this`.                              |
+| `onAdd/onSet/onRemove(handler?)`               | Get, set, or remove this component key's single hook. Setters return `this`.                        |
+| `onRetarget(handler?)`                         | Get, set, or remove a relationship component entity's single retarget hook.                         |
 | `toString()`                                   | Returns `"EntityN"`.                                                                                |

package/docs/execution-model.md

@@ -97,9 +97,9 @@ built-in taxonomy.
 ## Deferred mutation and flush boundaries
 
 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` / `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.
+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.
 
 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
@@ -116,8 +116,12 @@ While a mutation is queued but not yet applied, reads return the pre-mutation st
 | `entity.add(C)`           | `undefined` — no instance has been created yet.            |
 | `entity.attach(instance)` | `undefined`, if `C` was absent before.                     |
 | `entity.set(C, props)`    | The **previous** value (or `undefined` if `C` was absent). |
+| `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.
+
 Outside any deferred scope (top-level user code), the same calls execute inline and effects are
 visible immediately.
 
@@ -156,7 +160,7 @@ Three routing rules worth memorizing:
 - **`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.
 - **In-place mutation needs `modified`.** Assigning to component fields directly notifies no one.
-  Call `entity.modified(C)` (or use `set` / `getMut`) to route the change.
+  Call `entity.modified(C)` (or use `set` / `getMut` / `ensure`) to route the change.
 
 ## Why the patterns work
 

package/docs/glossary.md

@@ -50,8 +50,9 @@ entity lifecycle API. [Utilities](./utilities.md#events).
 **Filter** — a non-reactive, one-shot predicate that scans world entities on each `forEach`.
 [Queries and filters](./queries-and-filters.md#filters-one-shot-scans).
 
-**Hook** — an `onAdd` / `onSet` / `onRemove` callback registered per component class, fired
-synchronously at the mutation site. [Components](./components.md#hooks-onadd-onset-onremove).
+**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).
 
 **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.
@@ -71,6 +72,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).
+
 **Phase** — an entity used as a pipeline ordering anchor (tagged with the `Phase` component);
 systems attach to exactly one phase via `DependsOn`.
 [Execution model](./execution-model.md#phases-the-pipeline-spine).
@@ -102,6 +107,10 @@ assigned to one phase. [Systems](./systems.md).
 **Tick source** — a clock (`IntervalTickSource`, `RateTickSource`, or another system) that gates
 how often a system fires. [Systems](./systems.md#cadence-interval-rate-and-tick-sources).
 
+**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).
+
 **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

@@ -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` (with the `Delete` cascade) 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 `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.                                                                         |
 
 All are exported, so a custom world setup can reuse them.
 

package/docs/relationships.md

@@ -43,6 +43,70 @@ subclasses) explicitly in your `networkComponents` array to replicate parent-chi
 
 `entity.childOf(parent)` is shorthand for `entity.set(ChildOf, { target: parent })`.
 
+## Ensuring a target
+
+Use `ensureTarget` when a registered relationship should always have some target and a new,
+independent entity is the correct default:
+
+```ts
+world.component(FriendOf);
+
+const friend = entity.ensureTarget(FriendOf);
+entity.ensureTarget(FriendOf) === friend; // true
+entity.target(FriendOf) === friend; // true
+```
+
+The method returns the existing target when present. Otherwise it creates an entity, initializes
+the relationship with that target, and attaches the relationship. During deferred execution,
+repeated calls share one pending relationship and return the same target; `target(FriendOf)` still
+returns `undefined` until flush.
+
+The generated target is independent: `ensureTarget` does not add `ChildOf`, and destroying the
+source does not destroy the target. Add ownership explicitly when your model requires it. The
+relationship class must be registered before calling `ensureTarget`.
+
+## Owned targets
+
+Mark a relationship component with `OwnedTarget` during world setup when every target assigned
+through that relationship should become a `ChildOf` child of its source:
+
+```ts
+import { OwnedTarget, Relationship } from "@vworlds/vecs";
+
+class Inventory extends Relationship {}
+
+world.component(Inventory).add(OwnedTarget);
+
+const inventory = player.ensureTarget(Inventory);
+inventory.parent === player; // true
+
+player.destroy();
+inventory.destroyed === true; // ChildOf cascades deletion
+```
+
+Use `add` when the relationship itself represents a feature and initialization belongs in an
+`onAdd` hook or system `enter` callback:
+
+```ts
+world.component(Inventory).add(OwnedTarget);
+
+player.add(Inventory);
+const inventory = player.target(Inventory)!; // target was created by OwnedTarget
+```
+
+`OwnedTarget` wraps `onAdd`, `onSet`, `onRetarget`, and `onRemove` on `Inventory`. Adding the
+relationship creates a target when needed. New targets become `ChildOf` children, displaced targets
+are destroyed on retarget, and the current target is destroyed when the relationship is removed
+(including source destruction). Ownership behavior runs before the relationship owner's existing
+hook, so owner hooks and query entry observe an initialized target. During deferred execution, these
+changes apply while the command queue drains.
+
+Configure the trait before creating relationship instances; it does not backfill existing targets.
+Configure owner lifecycle hooks before attaching the trait, because later hook assignment replaces
+the wrapper and its ownership behavior.
+Do not share one owned target between several sources: retargeting or removing any owning
+relationship can destroy it. `OwnedTarget` rejects ordinary components and `ChildOf` itself.
+
 ## Retargeting
 
 Point a relationship somewhere else with a plain `set`:
@@ -60,6 +124,20 @@ lookups.
 `getMut` throws for relationship components: in-place target mutation would bypass the reverse
 index used by `children()` and the cleanup cascades. Always retarget with `set`.
 
+Register `onRetarget` when behavior needs both targets:
+
+```ts
+world.component(InCell).onRetarget((entity, oldCell, newCell) => {
+  // entity.target(InCell) is newCell here.
+  // oldCell.children(InCell) no longer contains entity.
+  // newCell.children(InCell) already contains entity.
+});
+```
+
+It fires only when an existing relationship moves to a different existing target, after reverse
+indexes update and before `onSet`. Initial assignment, same-target writes, and removal do not fire
+`onRetarget`; use `onSet` and `onRemove` for those lifecycle points.
+
 ## Cleanup when a target dies
 
 What happens to sources when their target entity is destroyed is governed by the relationship's
@@ -145,6 +223,9 @@ the box — the world's default pipeline is itself a `cascade: DependsOn` query
 | `e.target(R)`                                       | The target entity through relationship `R`, or `undefined`.                             |
 | `e.children(R)`                                     | `ReadonlySet<Entity>` of sources targeting `e` through `R`.                             |
 | `e.childOf(parent)`                                 | Shorthand for `e.set(ChildOf, { target: parent })`.                                     |
+| `e.ensureTarget(R)`                                 | Return `R`'s target, creating an independent entity when absent.                        |
+| `world.component(R).add(OwnedTarget)`               | Create and own `R` targets as `ChildOf` children of their sources.                      |
+| `world.component(R).onRetarget(handler?)`           | Get, set, or remove the single retarget handler.                                        |
 | `e.parent` / `e.parent = p`                         | Getter/setter for the built-in `ChildOf` target; setting `undefined` removes `ChildOf`. |
 | `meta.onDeleteTarget`                               | `Remove` (default) or `Delete` cascade when a target is destroyed.                      |
 | `world.component(R).add(Traversable)`               | Enable depth tracking for `cascade` ordering.                                           |

package/package.json

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

package/skills/vecs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: vecs
+description: "Designs, implements, reviews, and debugs games or applications using @vworlds/vecs. Use whenever a task creates or changes vecs components, entities, systems, queries, relationships, modules, phases, lifecycle, networked components, or ECS architecture."
+---
+
+# vecs Application Development
+
+Use the documentation shipped with the consuming project's installed `@vworlds/vecs` package.
+Those docs match the API version the project actually uses and are the source of truth for vecs
+design and behavior.
+
+## Before Working
+
+1. Locate `node_modules/@vworlds/vecs/docs/`. In a workspace or non-npm install, resolve the
+   installed `@vworlds/vecs` package and use its adjacent `docs/` directory.
+2. Read `docs/design-guide.md` sections 1, 2, 8, and 9 before designing or changing ECS behavior.
+3. Read the task-specific sections of that design guide:
+   - Components or replicated state: section 3.
+   - Systems or queries: section 4.
+   - Ordering or timing: section 5.
+   - Feature architecture: section 6.
+   - Lifecycle and synchronization patterns: section 7.
+4. Use `docs/README.md` to select any detailed subsystem guides needed by the task. Read
+   `docs/concepts.md` and `docs/execution-model.md` when the design depends on unfamiliar vecs
+   behavior.
+5. Inspect the consuming project's existing vecs modules and conventions before proposing a new
+   pattern.
+
+Do not rely on memory or a different vecs checkout when installed documentation is available.
+Confirm exact names and signatures against the installed declarations under
+`node_modules/@vworlds/vecs/dist/`.
+
+## Design From ECS Semantics
+
+Start from the vecs golden rule: components are data, systems are behavior, and component presence
+and change drive lifecycle.
+
+Before implementing, identify:
+
+- The state represented by each component and whether absence has meaning.
+- Which component transition creates, updates, or removes related state or resources.
+- Whether the work should react through `enter`, `update`, or `exit` rather than scan every frame.
+- Which phase owns the work and what earlier or later phase it must order against.
+- Whether an owned target, relationship, trait, grouped query, or attached resource expresses the
+  lifecycle better than imperative bookkeeping.
+- Whether the feature belongs in a `Module` that owns registration, systems, phases, and policy.
+
+Prefer the idioms in the installed design guide over generic ECS patterns. vecs execution details,
+including per-system flushes and reactive inbox routing, are part of the design model.
+
+## Avoid Generic Workarounds
+
+Check the design guide before introducing:
+
+- Side maps keyed by entity id.
+- Components containing behavior or broad god-components with optional sentinel fields.
+- Per-frame scans for changes that vecs can route reactively.
+- Manual lifecycle bookkeeping that duplicates component presence.
+- System registration order as a substitute for explicit cross-feature phase ordering.
+- Parallel object graphs that duplicate relationships already represented in the ECS.
+- Wrapper abstractions that hide normal vecs entities, components, systems, or modules without a
+  concrete need.
+
+If the requested design conflicts with a documented vecs invariant, explain the conflict and use
+the documented pattern unless the user explicitly chooses otherwise.
+
+## Implement And Verify
+
+1. Reuse existing components and modules where their semantics match; do not reuse them merely
+   because their fields look similar.
+2. Keep components small data classes and put behavior in systems or narrowly scoped lifecycle
+   hooks as directed by the guide.
+3. Express cross-feature ordering with phases. Treat same-phase registration order as a local
+   implementation detail unless the installed docs explicitly make it part of the design.
+4. Test lifecycle transitions, not only steady-state values: entry, mutation, removal, retargeting,
+   destruction, and same-tick visibility where relevant.
+5. Run the consuming project's typecheck and focused tests. Resolve API uncertainty from the
+   installed declarations and docs rather than guessing.
+
+For networking, physics, Phaser, client, or server integration, also inspect the README and
+declarations shipped with the corresponding `@vworlds/vecs-*` package.