@vworlds/vecs 1.0.25 → 1.0.26

package/docs/entities.md

@@ -0,0 +1,175 @@
+# Entities
+
+Create, look up, mutate, and destroy entities, and understand how the entity API behaves under
+deferred mutation.
+
+## What an entity is
+
+An `Entity` (`lib/vecs/src/entity/entity.ts`) is a unique numeric id (`eid`) owned by a `World`,
+with an arbitrary set of component instances attached. Never instantiate `Entity` directly —
+create entities through the world.
+
+## Creating and looking up entities
+
+```ts
+// New entity with an auto-assigned id (from the "entity" pool, 1000+ by default):
+const e = world.entity();
+
+// Look up by id (throws if not found):
+const found = world.entity(42);
+
+// Optional lookup — returns undefined instead of throwing:
+const maybe = world.getEntity(42);
+
+// Externally assigned id (e.g. from a server); creates the entity if absent:
+const net = world.getOrCreateEntity(serverId, (newEntity) => {
+  tracked.add(newEntity);
+});
+
+// Named entities, via the built-in Identity component:
+world.entity("player"); // looks up by name, creating the entity if absent
+world.entity("player").name === "player"; // true
+world.getEntity("player"); // lookup only — undefined when absent
+```
+
+`world.entity(ref)` also accepts a registered component class (returning its component entity) or
+an `Entity` (validating it belongs to this world). Names are maintained by `IdentityModule`:
+setting `entity.name` writes the `Identity` component, and duplicate names are last-writer-wins.
+
+`world.entities` is a read-only view of every live entity keyed by id, and `world.clearAllEntities()`
+destroys **every** entity in the world — ordinary entities first, then component entities once
+their carriers are gone. It is a full wipe (systems and phases are backed by entities too); use it
+for end-of-session teardown, not selective resets.
+
+## The component API
+
+```ts
+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.has(Position); // boolean
+e.remove(Position); // detach; fires exit callbacks, then onRemove
+e.modified(Position); // mark changed after in-place mutation
+e.destroy(); // remove everything and unregister the entity
+```
+
+All mutators return the entity for chaining (`remove` and `destroy` return `void`). Component
+references can be a registered class, a numeric component id, or an entity used as a component
+key.
+
+### `set` vs `add` vs `modified`
+
+- `add(C)` attaches with defaults and fires `onAdd` only. It is idempotent and does **not** fire
+  `onSet`.
+- `set(C, props)` attaches if needed (firing `onAdd`), copies `props` onto the instance, and fires
+  `onSet` plus `update` callbacks.
+- `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
+
+`get` returns a `Readonly` view. To mutate, use `getMut`, which marks the component modified for
+you:
+
+```ts
+// Inside a system / forEach / defer block (deferred mode) — returns the mutable instance:
+const vel = e.getMut(Velocity)!;
+vel.vx += 1;
+
+// Outside deferred mode you must use the callback form, so the modified
+// notification fires after your mutation:
+e.getMut(Velocity, (vel) => {
+  vel.vx += 1;
+});
+```
+
+Calling `getMut(C)` without a callback outside deferred mode throws. `getMut` also throws for
+relationship components (retarget with `set` instead — see
+[Relationships](./relationships.md#retargeting)) and for `Implements` interface aliases.
+
+### `attach`: storing an existing instance
+
+`attach` stores the exact object you pass, replacing any previous instance of that component
+class, and fires events as a `set` would:
+
+```ts
+const shared = new Position();
+e.attach(shared);
+e.get(Position) === shared; // true
+
+// Store under a base class key instead of the instance's own constructor:
+e.attach(BaseShape, concreteShape);
+```
+
+The resolved class must already be registered in the entity's world. Use `attach` when component
+ownership is intentionally shared with caller code or another object graph; code receiving the
+component through vecs callbacks should use the entity vecs passes, not assume a 1:1 mapping.
+
+### Deferred semantics
+
+Inside a system body, a `forEach`, or a `world.defer` block, all of the mutators above enqueue
+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).
+
+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
+`getOrCreateEntity(eid)` calls before the drain return that same pending entity. Collection-style
+reads such as `world.entities` and queries still do not see the entity until the queued creation
+drains.
+
+## Destroying entities
+
+`e.destroy()` removes every component (firing each `onRemove` hook and query `exit`), emits the
+entity's `"destroy"` event just before teardown, unregisters the entity from the world, and
+applies incoming relationship cleanup policies (see
+[Relationships](./relationships.md#cleanup-when-a-target-dies)). After destruction the entity must
+not be used.
+
+If the entity is itself in use as a component key, `destroy` honors `meta.onDelete` — by default
+it throws while carriers remain ([Components — cleanup policies](./components.md#cleanup-policies-destroying-a-component-entity)).
+
+## Entities as component keys
+
+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.
+
+## Relationships, in brief
+
+`e.parent(Rel)` returns the target of a relationship component, `e.children(Rel)` the set of
+entities targeting `e` through it, and `e.childOf(parent)` is shorthand for
+`e.set(ChildOf, { target: parent })`. The full model — retargeting, cleanup cascades, traversal —
+is in [Relationships](./relationships.md).
+
+## Reference
+
+`lib/vecs/src/entity/` (split across `entity.base.ts`, `entity.components.ts`,
+`entity.lifecycle.ts`, `entity.relationships.ts`):
+
+| Property / Method                              | Description                                                                                         |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `eid`                                          | Unique numeric entity id.                                                                           |
+| `world`                                        | The `World` that owns this entity.                                                                  |
+| `name`                                         | Identity name (getter/setter backed by the `Identity` component); `undefined` when unnamed.         |
+| `componentBitmask`                             | `Bitset` of component type ids attached. Used for archetype matching.                               |
+| `components`                                   | Read-only `ArrayMap` view of attached instances keyed by type id (`forEach`, `get`, `has`, `size`). |
+| `empty`                                        | `true` when no components are attached.                                                             |
+| `properties`                                   | Free-form `Map<string, any>` for module-level bookkeeping.                                          |
+| `meta`                                         | `ComponentMeta` for using this entity as a component key (created lazily).                          |
+| `instanceCount()`                              | Number of entities currently carrying this entity's eid as a component.                             |
+| `add(ref)`                                     | Attach a component with default values (idempotent). Returns `this`.                                |
+| `attach(instance)` / `attach(Class, instance)` | Store an existing instance, replacing any previous one; fires set-side events. Returns `this`.      |
+| `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.     |
+| `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`.                                           |
+| `destroy()`                                    | Remove all components, unregister, and apply incoming relationship cleanup.                         |
+| `parent(rel)`                                  | Target entity of relationship `rel`, or `undefined`.                                                |
+| `children(rel)`                                | `ReadonlySet<Entity>` of entities targeting this one through `rel`.                                 |
+| `childOf(parent)`                              | Shorthand for `set(ChildOf, { target: parent })`. Returns `this`.                                   |
+| `onAdd/onSet/onRemove(handler)`                | Register hooks for this entity used as a component key. Return `this`.                              |
+| `toString()`                                   | Returns `"EntityN"`.                                                                                |

package/docs/execution-model.md

@@ -0,0 +1,173 @@
+# Execution Model
+
+How `world.progress` runs your systems: the phase spine, ordering guarantees, deferred mutation,
+and reactive event routing. Every design trick in vecs follows from the rules on this page.
+
+## One tick, anatomically
+
+`world.progress(now, delta)` (`lib/vecs/src/world/world.pipeline.ts`) does, in order:
+
+1. **`beginFrame(delta)`** — flush any pending top-level commands, rebuild the flat pipeline if
+   the pipeline query changed (this is when newly created systems are inserted), and evaluate
+   every registered tick source once (see [Systems — cadence](./systems.md#cadence-interval-rate-and-tick-sources)).
+2. **For each system in pipeline order:** run the system, then `flush()` the world's command
+   queue.
+3. **`endFrame()`** — close the frame.
+
+`now` and `delta` are both milliseconds. You can also call `beginFrame` / `endFrame` yourself and
+run systems manually, but `progress` is the normal driver.
+
+## Phases: the pipeline spine
+
+Systems are grouped by **phase**, and phases run in a fixed order. The eight built-in phases are
+plain entities, created by `PipelineModule` and chained with the `DependsOn` relationship
+(`lib/vecs/src/modules/pipeline.ts`). The exported constants are their entity names:
+
+| Constant      | Entity name        | Use it for                                                                          |
+| ------------- | ------------------ | ----------------------------------------------------------------------------------- |
+| `ON_LOAD`     | `vecs::OnLoad`     | Load data _into_ the ECS: inputs, network snapshots, external reads.                |
+| `POST_LOAD`   | `vecs::PostLoad`   | Process raw loaded data: turn key presses into high-level actions.                  |
+| `PRE_UPDATE`  | `vecs::PreUpdate`  | Final prep before game logic: clean up last frame, prepare state gameplay will use. |
+| `ON_UPDATE`   | `vecs::OnUpdate`   | **The default phase.** Main gameplay/simulation logic.                              |
+| `ON_VALIDATE` | `vecs::OnValidate` | Validate state after updates: collision detection, constraint checks.               |
+| `POST_UPDATE` | `vecs::PostUpdate` | Apply corrections from validation: resolve collisions, fix up state.                |
+| `PRE_STORE`   | `vecs::PreStore`   | Prepare data for output: compute render state once all logic is done.               |
+| `ON_STORE`    | `vecs::OnStore`    | Store/emit the final frame: rendering, writing output, sending snapshots.           |
+
+`BUILTIN_PIPELINE_PHASES` exports the eight names in order. Map your work onto this taxonomy
+rather than inventing phases: input belongs in `ON_LOAD`/`POST_LOAD`, gameplay in `ON_UPDATE`,
+validation and correction in `ON_VALIDATE`/`POST_UPDATE`, output in `PRE_STORE`/`ON_STORE`.
+
+### Assigning a system to a phase
+
+Every system defaults to `ON_UPDATE`. Call `.phase(...)` only to run elsewhere:
+
+```ts
+import { ON_STORE } from "@vworlds/vecs";
+
+world.system("Render").phase(ON_STORE).with(Sprite, Position).each([Sprite, Position], draw);
+```
+
+`.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.
+
+### Ordering guarantees
+
+1. **Across phases, order is guaranteed by the phase spine.** A system in `PRE_STORE` always runs
+   before any system in `ON_STORE`, regardless of when either was created.
+2. **Within a phase, systems run in creation order** (entity-id order — the order `world.system`
+   was called). An umbrella module controls this by the order it loads sub-modules.
+3. **Never rely on registration order for cross-module correctness.** When two independent
+   features must order against each other, express it with phases.
+
+### The pipeline is a query
+
+The pipeline itself is an ordered query over system entities. The default, installed by
+`PipelineModule`:
+
+```ts
+world.setPipeline({
+  with: { all: [System, { target: [DependsOn, Phase] }] },
+  cascade: DependsOn,
+});
+```
+
+It matches every `System` whose backing entity `DependsOn` a `Phase`, ordered depth-first along
+the `DependsOn` cascade. `world.setPipeline(spec)` replaces it; the world always appends `System`
+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:
+
+```ts
+import { insertPhaseAfter, ON_UPDATE, Phase } from "@vworlds/vecs";
+
+const physicsStep = world.entity("physics-step").add(Phase);
+insertPhaseAfter(physicsStep, world.entity(ON_UPDATE));
+```
+
+Reserve custom phases for engine-level modules that genuinely need their own spine (the physics
+engine inserts its step phases after `ON_UPDATE`). Application and render systems should use the
+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.
+
+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
+the same phase or in a later phase — but not to A itself mid-iteration. This single fact enables
+teardown-before-create ordering, the companion-component lifecycle, and same-tick reconciliation
+(see the [Design guide](./design-guide.md)).
+
+### What reads see while deferred
+
+While a mutation is queued but not yet applied, reads return the pre-mutation state:
+
+| After calling…            | `entity.get(C)` / `entity.getMut(C)` returns…              |
+| ------------------------- | ---------------------------------------------------------- |
+| `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.remove(C)`        | Still the component instance.                              |
+
+Outside any deferred scope (top-level user code), the same calls execute inline and effects are
+visible immediately.
+
+### Controlling deferral yourself
+
+```ts
+world.deferred;            // true while the world is in deferred mode
+world.defer(() => { ... }); // run a block in deferred mode, drain on exit
+world.beginDefer();         // open a scope manually…
+world.endDefer();           // …close it (drains at the outermost scope)
+world.flush();              // drain queued top-level commands now
+```
+
+Scopes nest: a `Filter.forEach` inside a system inherits the system's scope and does not drain on
+exit. `flush()` is a no-op while any scope is open; it also builds queries created since the last
+flush.
+
+## Reactive routing
+
+When the world applies a command, it routes events to everything that watches the affected
+component:
+
+- **Hooks** (`onAdd` / `onSet` / `onRemove`) fire synchronously at the moment the command is
+  applied — inline outside deferred mode, or during the drain.
+- **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
+  their next run (`lib/vecs/src/system.ts`). So systems react to change without scanning, and they
+  react _in their own phase slot_, in event arrival order.
+
+Three routing rules worth memorizing:
+
+- **`update(C)` fires on entry.** When an entity enters a system, the system pushes an `update`
+  event for every watched component already present. A single `.update(C, ...)` therefore
+  initializes on entry _and_ reacts to changes — don't write a duplicate `enter`.
+- **`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.
+
+## Why the patterns work
+
+Putting the rules together:
+
+- _Teardown before create:_ an `exit`-driven teardown system in `PRE_STORE` runs before an
+  `enter`-driven creation system in `ON_STORE`; the teardown's `remove` is flushed between them,
+  so a type swap tears down the old companion and builds the new one in the same tick.
+- _React, don't scan:_ `update(C)` touches nothing on idle entities, where `each` would visit all
+  of them every tick.
+- _Same-tick reconciliation:_ a system that writes a component early in the tick is guaranteed
+  that later phases see the new value.
+
+The [Design guide](./design-guide.md) develops each of these into a full pattern.

package/docs/getting-started.md

@@ -0,0 +1,215 @@
+# Getting Started
+
+Build a small simulation from scratch: create a world, register components, write two systems, and
+drive the loop with `world.progress`.
+
+## Install
+
+```sh
+npm install @vworlds/vecs
+```
+
+The package ships TypeScript types; no extra tooling is required.
+
+## 1. Create a world
+
+A `World` owns every entity, registered component, query, system, and the update pipeline. Create
+one per game session:
+
+```ts
+import { World } from "@vworlds/vecs";
+
+const world = new World();
+```
+
+The constructor installs the built-in modules — identity names, interface aliases, singletons,
+relationships, and the eight-phase pipeline — so the world is ready to use immediately (see
+[Modules](./modules.md)).
+
+## 2. Define and register components
+
+Components are plain data classes: field initializers, a no-argument constructor, and no behavior.
+Register each class with `world.component` before using it:
+
+```ts
+class Position {
+  x = 0;
+  y = 0;
+}
+
+class Velocity {
+  vx = 0;
+  vy = 0;
+}
+
+class Health {
+  hp = 100;
+}
+
+world.component(Position);
+world.component(Velocity);
+world.component(Health);
+```
+
+There is no automatic registration — using an unregistered class as a component throws. See
+[Components](./components.md) for ids, hooks, and policies.
+
+## 3. Add a system
+
+Systems declare which entities they care about with `.with(...)` and attach behavior. `each` runs
+once per matched entity on every tick:
+
+```ts
+world
+  .system("Move")
+  .with(Position, Velocity)
+  .each([Position, Velocity], (e, [pos, vel]) => {
+    pos.x += vel.vx;
+    pos.y += vel.vy;
+    e.modified(Position); // notify watchers that Position changed
+  });
+```
+
+Two details to internalize early:
+
+- The components listed in `.with` are guaranteed present, so `pos` and `vel` are non-nullable in
+  the callback tuple.
+- Mutating fields directly does not notify anyone. Call `e.modified(Position)` so hooks, `update`
+  callbacks, and reactive queries see the change. See [Systems](./systems.md).
+
+## 4. Add a reactive system in a later phase
+
+Systems run in the world's phase pipeline and default to the `vecs::OnUpdate` phase. Place
+follow-up work in a later phase — here, despawning dead entities during validation:
+
+```ts
+import { ON_VALIDATE } from "@vworlds/vecs";
+
+world
+  .system("Reap")
+  .phase(ON_VALIDATE)
+  .with(Health)
+  .update(Health, (entity, health) => {
+    if (health.hp <= 0) {
+      entity.destroy();
+    }
+  });
+```
+
+`update(Health, ...)` fires only when `Health` is set or marked modified on a tracked entity — and
+once on entry for each watched component already present — so this system does no work for idle
+entities. The phase taxonomy and ordering rules are in
+[Execution model](./execution-model.md).
+
+## 5. Observe lifecycle with hooks
+
+For a per-component callback that is not worth a whole system, register hooks on the component
+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`));
+```
+
+`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.
+
+## 6. Spawn entities
+
+`world.entity()` creates an entity; `set` attaches a component and assigns data in one call.
+Calls chain:
+
+```ts
+world.entity().set(Position, { x: 0, y: 0 }).set(Velocity, { vx: 5, vy: 0 }).set(Health, { hp: 3 });
+```
+
+## 7. Drive the loop
+
+`world.progress(now, delta)` runs one tick: every system in phase order, with structural changes
+flushed after each system. Both arguments are milliseconds — `now` is your absolute clock, `delta`
+the time since the previous tick:
+
+```ts
+let now = 0;
+for (let tick = 0; tick < 5; tick++) {
+  now += 16;
+  world.progress(now, 16);
+}
+```
+
+In a real game, call `world.progress` from your frame loop (`requestAnimationFrame`, a fixed-step
+server loop, etc.).
+
+## Complete program
+
+```ts
+import { ON_VALIDATE, World } from "@vworlds/vecs";
+
+class Position {
+  x = 0;
+  y = 0;
+}
+
+class Velocity {
+  vx = 0;
+  vy = 0;
+}
+
+class Health {
+  hp = 100;
+}
+
+const world = new World();
+
+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`));
+
+world
+  .system("Move")
+  .with(Position, Velocity)
+  .each([Position, Velocity], (e, [pos, vel]) => {
+    pos.x += vel.vx;
+    pos.y += vel.vy;
+    e.modified(Position);
+  });
+
+world
+  .system("Drain")
+  .with(Health)
+  .each([Health], (e, [health]) => {
+    health.hp -= 1;
+    e.modified(Health);
+  });
+
+world
+  .system("Reap")
+  .phase(ON_VALIDATE)
+  .with(Health)
+  .update(Health, (entity, health) => {
+    if (health.hp <= 0) {
+      entity.destroy();
+    }
+  });
+
+world.entity().set(Position, { x: 0, y: 0 }).set(Velocity, { vx: 5, vy: 0 }).set(Health, { hp: 3 });
+
+let now = 0;
+for (let tick = 0; tick < 5; tick++) {
+  now += 16;
+  world.progress(now, 16);
+}
+```
+
+Run it and watch the entity spawn, drain, and die after three ticks.
+
+## Where to go next
+
+- [Concepts](./concepts.md) — the mental model behind what you just wrote.
+- [Execution model](./execution-model.md) — why the phase placement and `modified` calls work.
+- [Design guide](./design-guide.md) — the idioms to reach for as your design grows.

package/docs/glossary.md

@@ -0,0 +1,113 @@
+# Glossary
+
+ECS and vecs terminology, in alphabetical order. Each entry links to the guide that develops it.
+
+**Archetype** — the set of component type ids attached to an entity, represented as the entity's
+`componentBitmask` (a [`Bitset`](./utilities.md#bitset)). Query matching tests
+archetypes with fast bitwise subset checks.
+
+**Backfill** — when a tracked query or system is built, entities that already match are routed
+through `enter` so the tracked set starts complete.
+[Queries and filters](./queries-and-filters.md#lifecycle-build-backfill-destroy).
+
+**Bitset** — a compact, growable set of non-negative integers backed by 32-bit words; used for
+archetypes and watchlists, and exported for bit-flag component fields.
+[Utilities](./utilities.md#bitset).
+
+**Cascade (query)** — depth-first ordering of a query's members along a `Traversable`
+relationship, via `{ with: ..., cascade: Rel }`.
+[Relationships](./relationships.md#traversal-order-traversable-and-cascade).
+
+**Cleanup policy** — what happens to dependent entities on destruction: `onDelete` (component
+entity destroyed → carriers throw/strip/die) and `onDeleteTarget` (relationship target destroyed →
+sources strip/die). [Components](./components.md#cleanup-policies-destroying-a-component-entity),
+[Relationships](./relationships.md#cleanup-when-a-target-dies).
+
+**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).
+
+**Component** — a registered plain data class with a no-argument constructor; pure data, no
+behavior. [Components](./components.md).
+
+**Component entity** — the entity backing a registered component class; returned by
+`world.component(C)` and carrying the class's hooks and `ComponentMeta`.
+[Components](./components.md#registration-worldcomponent).
+
+**Deferred mode / flush** — inside systems, `forEach`, and `defer` blocks, entity mutations are
+queued as commands; `flush` drains the queue at the scope boundary (after each system in the
+pipeline). [Execution model](./execution-model.md#deferred-mutation-and-flush-boundaries).
+
+**Entity** — a unique numeric id (`eid`) owned by a world, with a set of components attached.
+[Entities](./entities.md).
+
+**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).
+
+**Events** — a minimal typed event emitter helper exported for package-level events. It is not an
+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).
+
+**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.
+[Components](./components.md#interface-aliases-with-implements).
+
+**Inbox** — a system's ordered queue of routed `enter` / `exit` / `update` events, replayed at the
+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.
+[Systems](./systems.md#component-injection).
+
+**Iter** — an opt-in reusable cursor passed to callbacks instead of the bare entity, exposing the
+visited entity and the source entity of each injected slot.
+[Systems](./systems.md#the-iter-cursor).
+
+**Module** — a packaging unit (`class M extends Module<Config>`) whose `init()` registers
+components, systems, and policy once per world. [Modules](./modules.md).
+
+**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).
+
+**Pipeline** — the flat, ordered list of systems `world.progress` runs each tick; defined by an
+ordered query over system entities. [Execution model](./execution-model.md#the-pipeline-is-a-query).
+
+**Query** — a reactive, always-up-to-date set of entities matching a DSL predicate, with
+`enter` / `exit` / `update` callbacks. [Queries and filters](./queries-and-filters.md).
+
+**Query DSL** — the composable predicate language (`all` / `any` / `not` / `only` / `target` /
+`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).
+
+**Silence domain / `ignoreSource`** — a query configuration that drops `update` events originating
+from systems matching another query, breaking write feedback loops.
+[Queries and filters](./queries-and-filters.md#silencing-feedback-ignoresource).
+
+**Singleton** — a component class constrained to at most one carrier entity; commonly stored on
+its own component entity via `world.set` / `world.get`.
+[Components](./components.md#singletons-and-world-global-data).
+
+**System** — a query plus per-tick behavior (`run`, `each`) and inbox-replayed reactive callbacks,
+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).
+
+**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).
+
+**Wire type** — a field-level encoding declaration (`@type` from `@vworlds/vecs-wire`, commonly
+imported as `wireType`) used by the networking packages to serialize components. Networking is
+documented with `@vworlds/vecs-wire` / `@vworlds/vecs-protocol`, not here.
+
+**World** — the central container owning entities, component registrations, queries, systems, and
+the pipeline; driven by `world.progress(now, delta)`. [Concepts](./concepts.md).