@vworlds/vecs 1.0.44 → 1.0.46

package/docs/snapshots.md

@@ -0,0 +1,181 @@
+# Subtree snapshots
+
+A subtree snapshot moves an entity forest between two vecs worlds: capture it in one world,
+recreate it in another, or do both. It is the primitive behind a multi-sector host, where a ship
+crosses a world boundary and its ECS state has to appear in the next sector's world.
+
+Three operations, one matched set:
+
+| Operation         | Source world    | Destination world   |
+| ----------------- | --------------- | ------------------- |
+| `snapshotSubtree` | read-only       | unchanged           |
+| `restoreSubtree`  | unchanged       | gets fresh entities |
+| `moveSubtree`     | roots destroyed | gets fresh entities |
+
+```ts
+const result = world.moveSubtree(ship, nextSectorWorld, {
+  components: [Position, LinearVelocity, Hull],
+  relationships: [ChildOf, Carries],
+  externalTargets: "error",
+});
+
+result.roots; // destination root entities
+result.entities.get(sourceEid); // destination entity for one snapshot key
+result.sourceToDestination.get(sourceEntity); // the same, keyed by source entity
+```
+
+## What a snapshot holds
+
+Nothing live. Entity ids, component ids, and relationship edges are all world-local, so a snapshot
+records:
+
+- the component **classes** the forest carried, plus each instance's captured **data**;
+- each relationship's class, its non-edge **data**, and its **internal targets** as snapshot keys;
+- how many targets were **left behind** (see external targets below).
+
+The source's instances are never attached to the destination, and never mutated. Restore builds
+every destination component through the same materializer `Entity.set` uses, so aliases,
+exclusivity, `add` hooks, and query entry fire exactly once per component, the same as for an
+ordinary `set`.
+
+## Selecting what crosses
+
+```ts
+world.snapshotSubtree(root, {
+  traversal: ChildOf, // default; any registered relationship
+  components: [Position, Hull],
+  relationships: [ChildOf, Carries],
+  externalTargets: "omit", // default
+});
+```
+
+- **`traversal`** — the relationship that defines "subtree". `ChildOf` by default; a convoy might
+  use its own ordering relationship instead. The forest is every entity reachable through that
+  relationship, transitively.
+- **`components` / `relationships`** — allowlists. Omit one to select every type in that category;
+  supply one to select exactly those. `ChildOf` is captured as the traversal relationship whatever
+  the `relationships` list says, since without it the result is not a subtree.
+- **`externalTargets`** — what to do with a selected edge that points outside the forest.
+
+A cycle in the traversal relationship, or an entity reachable from two roots in one call, is an
+error: an ambiguous forest has no single correct capture.
+
+## External targets
+
+An entity outside the forest is not captured, so an edge to it has nowhere to land.
+
+- `"omit"` (default) — drop the edge, record how many targets were dropped.
+- `"error"` — refuse to capture at all.
+
+Use `"error"` when leaving data behind is a bug you want to hear about; use `"omit"` when the edge
+is genuinely world-bound, like a tether to something the next sector does not own.
+
+## Snapshot policies
+
+Per component type, capture follows the type's `OnSnapshot` declaration. Ordinary plain-data
+components need no declaration at all:
+
+```ts
+class Position {
+  x = 0;
+  y = 0;
+}
+```
+
+`Position` has no policy, so it uses **`ClonePublic`**: a fresh instance with the source instance's
+own enumerable fields copied over. That is the same shallow copy `set` performs, and it is exactly
+as aliasing-sensitive — a component holding a nested object shares it until something copies it.
+
+### `DontSnapshot`
+
+For state that cannot exist in another world: engine handles, sockets, live queries and systems.
+
+```ts
+world.component(PhysicsEngine).snapshotPolicy(DontSnapshot);
+```
+
+A `DontSnapshot` type is skipped during capture. **Selecting** one explicitly is an error, so a
+caller cannot silently lose state it asked for by name.
+
+### `CustomSnapshot`
+
+For a component that mixes declarative state with runtime state. The owner supplies both halves.
+
+```ts
+world.component(Body).snapshotPolicy(CustomSnapshot, {
+  // Keep the declarative fields, drop the engine handle.
+  capture: (body) => ({ type: body.type }),
+  // Build a destination-owned instance.
+  materialize: (data) => Object.assign(new Body(), data),
+});
+```
+
+`capture` receives the live source instance and returns detached data. `materialize` receives that
+data and returns a freshly constructed instance belonging to no other entity. The captured value
+never has to be JSON — whatever `capture` returns is handed to `materialize` verbatim — but it must
+not reference the source world, its entities, or anything the source still holds.
+
+A policy is declared by the module that owns the component type. It may be declared, changed, or
+revoked at any time — including after entities already carry the component — because **capture binds
+the materializer it resolved**. Each captured record stores the materialize function that was in
+effect at capture time, so a policy declared afterwards cannot retroactively change how an existing
+snapshot restores. The same binding makes a snapshot safe to restore much later, after the owning
+module has moved on.
+
+`@vworlds/vecs-physics` installs policies for its own components, which is why a physics subtree
+moves without any physics-specific code in the caller: `PhysicsEngine` is `DontSnapshot`, while
+`Body`, shapes, and joint types capture their declarative fields and let the destination lifecycle
+systems allocate fresh Box2D handles. Their custom policies deep-copy only primitives, arrays, and
+plain `Object`/null-prototype records; a Box2D `b2Vec2` wrapper or other class instance fails at
+capture with its component and field path. `JointFrame`, `JointSettings`, and joint feature
+components use the default `ClonePublic` policy.
+
+## Restore order
+
+Restore is ordered, and the order is observable:
+
+1. **Preflight** every captured class against the destination. A class that is not registered there,
+   or that the destination declares `DontSnapshot`, fails here — before any entity exists.
+2. **Allocate** one destination entity per record, so every edge target exists before any edge is
+   added.
+3. **Materialize** plain-data components.
+4. **Rebuild edges**, traversal relationship first, then everything else. Hierarchy-sensitive
+   policies such as `OneOf` and `Traversable` therefore see a complete tree.
+5. **Assign** each relationship's non-edge data, in capture order.
+
+If any step throws, everything the attempt created is destroyed and the error propagates, so a
+failed restore leaves the destination as it was found.
+
+## Move and rollback
+
+`moveSubtree` captures and preflights **before** it destroys anything, so a snapshot that cannot be
+restored leaves the source world untouched.
+
+Once the source is destroyed and the destination restore fails, everything the restore created is
+destroyed, the source snapshot is restored back into the source world, and the original error is
+rethrown. The rollback rebuilds equivalent state with freshly allocated ids, so `Entity` references
+held before a failed move are stale afterwards.
+
+Destroying a root applies its component `remove` hooks and its relationship cleanup policies, which
+can reach outside the captured forest. That is what "the source is gone" means; select transferable
+data accordingly.
+
+## Deferred worlds
+
+All three operations throw while either world is deferred. Cross-world scheduling is the
+application's job — a transfer that interleaved with a half-applied frame of mutations would have no
+well-defined outcome. Call them between frames.
+
+## Inheritance
+
+`IsA` edges are never captured. An inheritance edge and the values it materialized would both be
+captured, and the destination would end up holding two disagreeing answers. Move an inheriting
+entity by selecting its effective values instead. (The inheritance work that introduces `IsA` is
+not in vecs yet; when it lands, it must keep declaring `IsA` as `DontSnapshot`.)
+
+## What this is not
+
+- **Not serialization.** A snapshot is an in-memory value, not a wire format, and not stable across
+  vecs versions. `@vworlds/vecs-wire` and `@vworlds/vecs-protocol` cover the network case.
+- **Not a cross-world transaction.** Two live worlds are not locked together. Capture-then-restore
+  cannot make two worlds atomically consistent; it makes the _transfer_ recoverable.

package/docs/systems.md

@@ -40,7 +40,7 @@ the full query DSL (operator semantics in
 .with({ all: [Position, { any: [Sprite, Container] }] })  // compound DSL
 .with({ not: Invisible })
 .without(Invisible)                                       // shorthand for .with({ not: Invisible })
-.with({ target: [FriendOf, Position] })                   // relationship target has Position
+.with({ target: [FriendOf, Position] })                   // any relationship target has Position
 .with({ parent: Body })                                   // ChildOf target has Body
 ```
 
@@ -89,6 +89,14 @@ Fires once when an entity starts matching the system:
 .enter({ inject: [Position, Sprite] }, (e, [pos, sprite]) => sprite.setPosition(pos.x, pos.y))
 ```
 
+The callback runs only if the entity is still a member when this system drains its inbox. If it
+left or was destroyed first, vecs drops the queued `enter` and its paired `exit`; do not add a
+`destroyed` guard to normal `enter` setup code. If it leaves and re-enters before draining, the
+callback receives the ordered lifecycle transitions.
+
+For systems, injected values and `Iter.src` are captured when entry is routed and replayed from that
+snapshot when the system next drains its inbox.
+
 ### `.update(ComponentClass, callback)` / `.update(options, callback)`
 
 Fires when the watched component is set or marked modified on a tracked entity.
@@ -121,9 +129,10 @@ registration throws instead of replacing the existing callback.
 ### `.exit(callback)` / `.exit(inject, callback)` / `.exit(options, callback)`
 
 Fires when an entity stops matching (component removed, or entity destroyed). Directly injected
-components are read from a **snapshot captured at exit time**, so they are still resolvable even
-though they are being removed; `target`-injected components resolve live at callback time and may
-be `undefined`:
+components and relationship projections are read from a **snapshot captured at exit time**, so
+the same component and entity references remain available even if storage or edges change before
+the system drains its inbox. Component objects are not cloned; later in-place changes to the same
+object remain visible:
 
 ```ts
 .exit([Sprite], (e, [sprite]) => sprite.destroy());
@@ -185,23 +194,55 @@ anything else resolves as `T | undefined` — guard it. (`enter`/`exit` injectio
 direct components to be present and throws otherwise; list only components your predicate
 guarantees.)
 
-### Relationship injection: `target` and `down`
+### Relationship injection
 
-`{ target: [Rel, [C1, C2]] }` follows the entity's relationship to its target and flattens the
-target's components into the tuple. Target-side slots are `undefined` when the relationship or the
-component is absent:
+`{ target: [Rel, projection] }` follows the entity's **first** relationship target and flattens the
+projection into the callback tuple. Use a component class to inject one target-side component, use
+`Entity` to inject the target itself, or use a tuple to inject several values in order:
 
 ```ts
-.forEach([Body, { target: [FriendOf, [Position, Velocity]] }], (e, [body, pos, vel]) => {
-  // body is from e; pos and vel are from e.target(FriendOf).
+.enter([{ target: [FriendOf, Entity] }], (source, [friend]) => {
+  // friend is source.target(FriendOf), one current target, or undefined.
+});
+
+.forEach([Body, { target: [FriendOf, Position] }], (source, [body, pos]) => {
+  // body is from source; pos is from source.target(FriendOf).
 });
+
+.forEach([{ target: [FriendOf, [Entity, Position, Velocity]] }], (source, [friend, pos, vel]) => {
+  // friend, pos, and vel all project from the same FriendOf target.
+});
+```
+
+Every target projection is optional. If the source lacks `Rel`, every projected slot is
+`undefined`. If the relationship exists, an `Entity` slot is the target while each component slot
+is `undefined` when that target lacks the component.
+
+Use `{ targets: [Rel, projection] }` to project every target. Unlike singular injection, the whole
+term occupies **one callback tuple slot** containing a readonly array of rows. Each target produces
+one row; row ordering follows the current target snapshot but is not a public ordering contract. The
+row contains one value for a scalar projection or several values for a tuple projection:
+
+```ts
+.forEach(
+  [{ targets: [FriendOf, [Entity, Position, Velocity]] }],
+  (source, [friends]) => {
+    // friends: ReadonlyArray<readonly [Entity, Position | undefined, Velocity | undefined]>
+    for (const [friend, position, velocity] of friends) { ... }
+  }
+);
 ```
 
-With two or more components in the inner tuple, TypeScript widens the slot types to a union;
-mark the inner tuple `as const` (`{ target: [FriendOf, [Position, Velocity] as const] }`) to get
-precise per-slot types. Single-component tuples infer precisely as-is.
+An absent relationship injects an empty array. The `Entity` value in each plural row is always
+present; projected components remain optional. `target` and `targets` resolve live for `each`,
+`forEach`, `update`, and `orderBy`. For deferred system `enter` and `exit` callbacks, vecs captures
+their projected component and entity references plus sources when the event is routed. Inbox replay
+retains those references even if storage or edges change; component objects are not cloned.
+
+Inline projection tuples infer precise slot types. When reusing a projection tuple stored in a
+variable, declare it `as const` to preserve each position's type.
 
-`{ down: [Rel, [C1]] }` fans out: the callback fires once per child targeting the visited entity
+`{ down: [Rel, [C1]] }` fans out: the callback fires once per source targeting the visited entity
 through `Rel`, with that child's components filling the slots (nullable). `down` is allowed only
 in `each` and `forEach`, at most once per tuple, and entities with zero children produce no calls.
 `down` iterates **all** children through the relationship, independent of any membership filter:
@@ -231,12 +272,14 @@ system.each(
 );
 ```
 
-`it.src` holds the source entity per tuple slot: the visited entity for direct components, the
-relationship target for `target` slots, the specific child for `down` slots. When `Iter` is not
-requested, the non-cursor path runs with zero per-entity overhead — dispatch happens once at setup
-time. `each`/`forEach`/`update`/`orderBy` reuse cursor and tuple instances across the pass, so
-snapshot what you need before triggering further mutations from inside a callback. Passing
-`{ cursor: Entity, ... }` is also accepted and means the default entity-first signature.
+`it.src` holds the source per tuple slot: the visited entity for direct components, the first
+target for every flattened `target` slot, the readonly target-array snapshot for the single
+`targets` slot, and the specific child for `down` slots. Event-time `enter` / `exit` snapshots also
+capture `Iter.src`. When `Iter` is not requested, the non-cursor path has no cursor allocation;
+dispatch happens once at setup time. `each`/`forEach`/`update`/`orderBy` reuse cursor and
+tuple instances across the pass, so snapshot what you need before triggering further mutations
+from inside a callback. Passing `{ cursor: Entity, ... }` is also accepted and means the default
+entity-first signature.
 
 ## Ordering and tracking
 
@@ -321,7 +364,7 @@ While disabled, query membership is still maintained, so the tracked set is corr
 | `phase(anchor)`                                                  | Place after a phase anchor (name or entity). Default `ON_UPDATE`.                                                                |
 | `enter(cb)` / `enter(inject, cb)`                                | Fires once when an entity starts matching.                                                                                       |
 | `update(C, cb)` / `update(options, cb)`                          | Fires on `set`/`modified` of `C` on a member; `options.onEnter: true` also fires on entry for present watched components.        |
-| `exit(cb)` / `exit(inject, cb)`                                  | Fires when an entity stops matching; direct injection reads an exit-time snapshot.                                               |
+| `exit(cb)` / `exit(inject, cb)`                                  | Fires when an entity stops matching; injection retains references captured at exit time.                                         |
 | `each([C...], cb)`                                               | Fires per tracked entity every tick. Implies `track`. One per system.                                                            |
 | `run(cb)`                                                        | Fires once per tick, `(now, delta)`.                                                                                             |
 | `interval(seconds)` / `rate(n[, source])` / `tickSource(source)` | Cadence control.                                                                                                                 |

package/docs/utilities.md

@@ -70,12 +70,16 @@ map.size; // 0
 
 `IterableArrayMap` (`lib/vecs/src/util/array_map.ts`) is an iterable `Map<number, T>` substitute
 backed by dense entries plus sparse indexes. Use it when callers need fast `forEach` or `values`
-over present entries. Random access resolves `key → dense index` through an internal `ArrayMap`,
-then indexes into a dense items array; iteration walks the dense items array directly.
-
-Deletes keep the items array dense by moving the last value into the removed slot, so iteration
-is always a tight loop without sparse holes. Compared with `ArrayMap`, this costs extra memory
-for tuple storage and an index map.
+over present entries. Random access reads the entry's dense position from a slot array indexed by
+key, which holds only small integers so V8 keeps it on its fast path, then reads the value from a
+dense value array. Iteration walks the dense key and value arrays directly.
+
+Deletes keep the dense arrays dense by moving the last entry into the removed position, so
+iteration is always a tight loop without sparse holes. Compared with `ArrayMap`, this costs extra
+memory for the slot array and the dense key and value arrays. Because the dense arrays grow by
+`push`, V8 cannot pretenure the entries, so a fresh process that creates tens of thousands of
+long-lived entities in bulk and then destroys them can run slower than with per-entry
+`[key, value]` tuples. The repository's `bench/README.md` has the measurements.
 
 ```ts
 import { IterableArrayMap } from "@vworlds/vecs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -15,7 +15,7 @@
     "prepack": "npm run build",
     "build": "npm run clean && npm run compile",
     "compile": "tsc -p tsconfig.build.json && cp \"./package.json\" ./dist/",
-    "bench:ecs": "NODE_OPTIONS=--max-old-space-size=32768 RUN_VECS_ECS_BENCH=1 vitest run tests/ecs.bench.test.ts --pool=forks --poolOptions.forks.singleFork",
+    "bench:ecs": "NODE_OPTIONS=--max-old-space-size=32768 RUN_VECS_ECS_BENCH=1 vitest run tests/ecs.bench.test.ts --pool=forks --maxWorkers=1 --reporter=default",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --no-error-on-unmatched-pattern",

package/skills/vecs/SKILL.md

@@ -41,8 +41,9 @@ Before implementing, identify:
 - 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 a multi-target relationship, an `Exclusive` relationship, an explicitly created owned
+  target, a grouped query, or an 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,
@@ -72,8 +73,8 @@ the documented pattern unless the user explicitly chooses otherwise.
    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.
+4. Test lifecycle transitions, not only steady-state values: entry, mutation, edge addition and
+   removal, exclusive edge replacement, 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.