@vworlds/vecs 1.0.20 → 1.0.22

package/README.md

@@ -14,30 +14,30 @@ yarn add @vworlds/vecs
 
 | Concept                  | What it is                                                                      |
 | ------------------------ | ------------------------------------------------------------------------------- |
-| **World**                | Central container. Owns every entity, query, system, and pipeline phase.        |
+| **World**                | Central container. Owns every entity, query, system, and flat system pipeline.  |
 | **Component**            | A registered plain data class with a no-argument constructor.                   |
 | **Entity**               | A numeric id with a set of components. Created via the world.                   |
 | **Query**                | A reactive, always-up-to-date set of entities matching a predicate.             |
-| **System**               | A `Query` with phase placement and per-tick logic (`update`, `each`, `run`).    |
+| **System**               | A `Query` with per-tick logic (`update`, `each`, `run`).                        |
 | **Filter**               | A non-reactive, one-shot scan: walks all world entities on each `forEach` call. |
 | **Hook**                 | Lightweight `onAdd` / `onRemove` / `onSet` callbacks per component class.       |
-| **Phase**                | Named ordered bucket of systems within the update pipeline.                     |
+| **Phase**                | Marker component for entities used as pipeline ordering anchors.                |
 | **Exclusive components** | A group of components where at most one may exist on any entity at a time.      |
 
 ### Lifecycle in brief
 
 ```
-world.component() × N  →  addPhase() / system() / query() × N  →  start()  →  progress() every frame
+world.component() / system() / query() × N  →  progress() every frame
 ```
 
-Components must be registered before they are used as component classes. After `start()`, component registration is disabled. Systems and queries can still be created — standalone queries backfill existing matched entities immediately.
+Components must be registered before they are used as component classes. Components, systems, and standalone queries can be created at any time. Newly-created systems are inserted into the pipeline the next time `world.progress()` runs; standalone queries backfill existing matched entities immediately.
 
 ---
 
 ## Example
 
 ```ts
-import { World, type IPhase } from "@vworlds/vecs";
+import { DependsOn, ON_UPDATE, Phase, World } from "@vworlds/vecs";
 
 // ─── Components ────────────────────────────────────────────────────────────
 
@@ -63,18 +63,17 @@ world.component(Position);
 world.component(Velocity);
 world.component(Health);
 
-// ─── Phases ────────────────────────────────────────────────────────────────
+// ─── Pipeline anchors ──────────────────────────────────────────────────────
 
-const update: IPhase = world.addPhase("update");
-const cleanup: IPhase = world.addPhase("cleanup");
+const update = world.entity(ON_UPDATE);
+const cleanup = world.entity("cleanup").add(Phase).set(DependsOn, { target: update });
 
 // ─── Systems ───────────────────────────────────────────────────────────────
 
 // MoveSystem: integrates Velocity into Position every tick.
 world
   .system("Move")
-  .phase(update)
-  .requires(Position, Velocity)
+  .with(Position, Velocity)
   .each([Position, Velocity], (e, [pos, vel]) => {
     pos.x += vel.vx;
     pos.y += vel.vy;
@@ -85,7 +84,7 @@ world
 world
   .system("Health")
   .phase(cleanup)
-  .requires(Health)
+  .with(Health)
   .update(Health, (entity, health) => {
     if (health.hp <= 0) {
       entity.destroy();
@@ -99,10 +98,6 @@ world
   .onAdd((entity, h) => console.log(`entity ${entity.eid} spawned with hp=${h.hp}`))
   .onRemove((entity) => console.log(`entity ${entity.eid} died`));
 
-// ─── Start ─────────────────────────────────────────────────────────────────
-
-world.start(); // freeze registration, distribute systems into phases
-
 // ─── Spawn entities ────────────────────────────────────────────────────────
 
 world.entity().set(Position, { x: 0, y: 0 }).set(Velocity, { vx: 5, vy: 0 }).set(Health, { hp: 3 });
@@ -145,7 +140,7 @@ const world = new World();
 
 #### Component registration
 
-Components are ordinary classes. They do not inherit from a vecs base class, and vecs constructs them with `new ComponentClass()`, so constructors should take no parameters. Register every component class before using it in `add`, `set`, `get`, `requires`, `query`, `filter`, hook registration, or `setExclusiveComponents`.
+Components are ordinary classes. They do not inherit from a vecs base class, and vecs constructs them with `new ComponentClass()`, so constructors should take no parameters. Register every component class before using it in `add`, `set`, `get`, `with`, `filter`, hook registration, or `setExclusiveComponents`. Registration can happen at any time.
 
 ```ts
 class Position {
@@ -160,7 +155,7 @@ const positionComponent = world.component(Position);
 world.component(Position, 42);
 
 // Access component metadata (numeric id, cleanup policy, etc.):
-const meta = world.component(Position).ownMeta; // ComponentMeta
+const componentMeta = world.component(Position).meta; // ComponentMeta
 
 // Give the component a name so it can be looked up by string later:
 world.component(Position).name = "Position";
@@ -177,7 +172,7 @@ Id ranges are configured by passing `idPools` to the `World` constructor. The bu
 | `module`    | 900 – 999 |
 | `entity`    | 1000 – ∞  |
 
-After `world.start()` (or `world.disableComponentRegistration()`) any further call to `world.component(Class)` that would register a new class throws. There is no automatic component registration; using an unregistered component class as a component is an error.
+There is no automatic component registration; using an unregistered component class as a component is an error.
 
 #### Exclusive component groups
 
@@ -189,7 +184,7 @@ e.add(Walking);
 e.add(Running); // Walking is automatically removed first
 ```
 
-Each call defines one independent group. A component may belong to at most one group; calling `setExclusiveComponents` again with the same class overwrites its group. Safe to call before or after `world.start()`.
+Each call defines one independent group. A component may belong to at most one group; calling `setExclusiveComponents` again with the same class overwrites its group. Safe to call at any time.
 
 #### Entity management
 
@@ -222,7 +217,7 @@ world.component("Position"); // resolves the same component entity
 
 #### Component entity deletion cleanup
 
-Every component key is backed by a component entity. Destroying that component entity is controlled by `world.component(C).ownMeta.onDelete`:
+Every component key is backed by a component entity. Destroying that component entity is controlled by `world.component(C).meta.onDelete`:
 
 | Policy                 | Meaning                                                                                            |
 | ---------------------- | -------------------------------------------------------------------------------------------------- |
@@ -233,7 +228,7 @@ Every component key is backed by a component entity. Destroying that component e
 ```ts
 import { CleanupPolicy } from "@vworlds/vecs";
 
-world.component(Temporary).ownMeta.onDelete = CleanupPolicy.Remove;
+world.component(Temporary).meta.onDelete = CleanupPolicy.Remove;
 world.component(Temporary).destroy(); // strips Temporary from all carriers
 ```
 
@@ -251,36 +246,28 @@ world
 
 `onAdd` fires when the component is first attached. `onRemove` fires when it is removed (or the entity is destroyed). `onSet` fires whenever `entity.modified(C)` is called, when `entity.set(C, props)` applies data, and when `entity.attach(instance)` stores an existing instance. Hook callbacks receive the owning entity because component instances do not carry entity references.
 
-#### Phases
+#### Pipeline
 
 ```ts
-const preUpdate = world.addPhase("preupdate");
-const update = world.addPhase("update");
-const send = world.addPhase("send");
+const update = world.entity("vecs::OnUpdate");
+const send = world.entity("send").add(Phase).set(DependsOn, { target: update });
 
-// Drive every phase in registration order:
-world.progress(now, delta);
+world.system("Send").phase(send).run(sendPackets);
 
-// ...or run individual phases manually:
-world.beginFrame(delta); // one numeric arg: ms since last frame
-try {
-  world.runPhase(preUpdate, now, delta);
-  world.runPhase(update, now, delta);
-  world.runPhase(send, now, delta);
-} finally {
-  world.endFrame();
-}
+// Drive every system returned by the pipeline query:
+world.progress(now, delta);
 ```
 
-Systems with no explicit phase are placed in the built-in `"update"` phase.
+Systems default to `vecs::OnUpdate`; call `.phase(...)` only when a system needs another pipeline anchor. The default pipeline query matches systems whose backing entity `DependsOn` a `Phase`, ordered by the `DependsOn` cascade. Built-in phase entity names are namespaced: `vecs::OnLoad`, `vecs::PostLoad`, `vecs::PreUpdate`, `vecs::OnUpdate`, `vecs::OnValidate`, `vecs::PostUpdate`, `vecs::PreStore`, and `vecs::OnStore`.
+
+Use `world.setPipeline(spec)` to replace the default. `World` appends `System` to the query, so the query result is always flattened to systems.
 
 #### Systems
 
 ```ts
 world
   .system("MySystem")
-  .phase("update")
-  .requires(A, B)
+  .with(A, B)
   .enter(...)
   .update(...)
   .each(...)
@@ -353,14 +340,13 @@ Tick source objects and systems can both be used as sources. Disabling a source
 ```ts
 const enemies = world
   .query("Enemies")
-  .requires(Enemy, Health)
+  .with(Enemy, Health)
   .enter((e) => console.log("enemy spawned", e.eid));
 
-world.start();
 // enemies.count and query iteration are kept up-to-date automatically.
 
-// Standalone queries can also be created after start(); existing matched
-// entities are backfilled immediately.
+// Standalone queries can also be created later; existing matched entities are
+// backfilled immediately.
 ```
 
 #### Filters
@@ -380,17 +366,16 @@ world.filter({ all: [Position, Velocity] }).forEach([Position, Velocity], (e, [p
 });
 
 // Manual hint for queries the type extractor can't see through:
-world.filter({ any: [Position, Velocity] }, [Position]).forEach([Position], (e, [pos]) => pos.x);
+world
+  .filter({ with: { any: [Position, Velocity] }, hint: [Position] })
+  .forEach([Position], (e, [pos]) => pos.x);
 ```
 
-A `Filter` requires no name, no `world.start()`, and no `destroy()` — create it anywhere and discard freely.
+A `Filter` requires no name and no `destroy()` — create it anywhere and discard freely.
 
 #### Pipeline control
 
 ```ts
-world.start();                         // freeze registration, distribute systems
-world.disableComponentRegistration();  // freeze registration without sorting
-
 world.flush();                         // drain queued top-level mutations
 world.defer(() => { ... });            // run a block in deferred mode
 world.beginDefer();                    // pair with endDefer() for finer scoping
@@ -433,7 +418,7 @@ entity.get(Position) === shared; // true
 | Shared instances possible | `entity.attach(instance)` stores the exact passed object; code should use the entity passed by vecs callbacks. |
 | Manual dirty marking      | After mutating fields directly, call `entity.modified(C)` to notify hooks, queries, and systems.               |
 
-Use `world.component(C).ownMeta` when you need metadata such as the numeric type id or component name. Metadata is world-specific.
+Use `world.component(C).meta` when you need metadata such as the numeric type id or component name. Metadata is world-specific.
 
 ---
 
@@ -495,14 +480,14 @@ item.parent(EquippedBy); // player
 player.children(EquippedBy).has(item); // true
 ```
 
-Relationship target cleanup is controlled by `ownMeta.onDeleteTarget`:
+Relationship target cleanup is controlled by `meta.onDeleteTarget`:
 
 | Policy                 | Meaning                                                                                      |
 | ---------------------- | -------------------------------------------------------------------------------------------- |
 | `CleanupPolicy.Remove` | Default. When a target is destroyed, remove the relationship component from each source.     |
 | `CleanupPolicy.Delete` | When a target is destroyed, destroy each source entity that targets it through the relation. |
 
-`ChildOf` is registered by every `World` and uses `CleanupPolicy.Delete`. Custom relationships default to `Remove`; set `world.component(MyRelationship).ownMeta.onDeleteTarget = CleanupPolicy.Delete` if target deletion should cascade.
+`ChildOf` is registered by every `World` and uses `CleanupPolicy.Delete`. Custom relationships default to `Remove`; set `world.component(MyRelationship).meta.onDeleteTarget = CleanupPolicy.Delete` if target deletion should cascade.
 
 `onDeleteTarget` is independent from `onDelete`: `onDeleteTarget` runs when a relationship target is destroyed, while `onDelete` runs when the relationship component entity itself is destroyed.
 
@@ -511,8 +496,8 @@ Retarget relationships with `entity.set(RelationshipClass, { target })`. `entity
 Relationship queries use `target` to follow a relationship from the candidate entity to its target and test that target with another DSL expression. Use `parent` for the built-in `ChildOf` hierarchy:
 
 ```ts
-world.query("body-friends").query({ all: [Body, { target: [FriendOf, [Position, Velocity]] }] });
-world.query("positioned-children").query({ all: [Position, { parent: Body }] });
+world.query("body-friends").with({ all: [Body, { target: [FriendOf, [Position, Velocity]] }] });
+world.query("positioned-children").with({ all: [Position, { parent: Body }] });
 ```
 
 Tracked queries stay live when either side changes. Adding or removing `FriendOf` on the candidate re-routes the candidate normally; adding or removing `Position` / `Velocity` on the target also refreshes every candidate that points at that target. Nested `target` works the same way across multiple hops.
@@ -530,7 +515,7 @@ Component injection supports lowercase `down` in `forEach` and system `each` inj
 ```ts
 world
   .query("parents")
-  .requires(Body)
+  .with(Body)
   .forEach([Body, { down: [ChildOf, [Position]] }], (parent, [body, childPos]) => {
     // One call per ChildOf child of parent. childPos is undefined when that child lacks Position.
   });
@@ -547,17 +532,18 @@ Two details matter:
 
 Systems are created via `world.system(name)` and configured through a fluent builder. Every method returns `this` for chaining. `System` extends `Query`, so the membership / enter / exit / update / sort APIs are shared.
 
-#### `.requires(...components)` and `.query(q)`
+#### `.with(...specs)`
 
 Declare which entities the system tracks.
 
 ```ts
-.requires(Position, Velocity)                                      // shorthand for [Position, Velocity]
-.query([Position, Velocity])                                       // explicit component list
-.query({ all: [Position, { any: [Sprite, Container] }] })          // compound
-.query({ not: Invisible })
-.query({ target: [FriendOf, Position] })                           // relationship target has Position
-.query({ parent: Body })                                           // ChildOf target has Body
+.with(Position, Velocity)                                         // explicit component list
+.with([Position, Velocity])                                       // array shorthand
+.with({ all: [Position, { any: [Sprite, Container] }] })          // compound
+.with({ not: Invisible })
+.without(Invisible)                                               // shorthand for .with({ not: Invisible })
+.with({ target: [FriendOf, Position] })                           // relationship target has Position
+.with({ parent: Body })                                           // ChildOf target has Body
 ```
 
 **Query operators:**
@@ -578,31 +564,31 @@ Declare which entities the system tracks.
 
 `target` and `source` use tuple form only: `{ target: [RelationshipClass, innerDSL] }` / `{ source: [RelationshipClass, innerDSL] }`. The first element must be a component that extends `Relationship`; passing a normal component throws. `target` evaluates the inner DSL against the relationship target; `source` evaluates it against each child/source and matches when at least one child/source matches. Because `source` and `children` are non-reactive, use them with `world.filter(...)`, not tracked queries or systems.
 
-Component injection also supports lowercase relationship markers. `up` works in `forEach`, `each`, `enter`, and `exit` injection lists. It follows the relationship target and flattens the requested target components into the callback tuple:
+Component injection also supports lowercase relationship markers. `target` works in `forEach`, `each`, `enter`, and `exit` injection lists. It follows the relationship target and flattens the requested target components into the callback tuple:
 
 ```ts
 world
   .query("friends")
-  .query({ target: [FriendOf, Position] })
-  .forEach([Body, { up: [FriendOf, [Position, Velocity]] }], (e, [body, pos, vel]) => {
+  .with({ target: [FriendOf, Position] })
+  .forEach([Body, { target: [FriendOf, [Position, Velocity]] }], (e, [body, pos, vel]) => {
     // body is from e; pos and vel are from e.parent(FriendOf)
     // target-side injected components are undefined if the target is absent or lacks them.
   });
 ```
 
-On `exit`, direct component injection is snapshot-stable when the exiting component was just removed. `up` injection resolves the target live at callback time, so target-side slots can be `undefined` if the exit was caused by the target losing that component.
+On `exit`, direct component injection is snapshot-stable when the exiting component was just removed. `target` injection resolves the target live at callback time, so target-side slots can be `undefined` if the exit was caused by the target losing that component.
 
 Lowercase `down` is allowed only in `forEach` and system `each`, where fan-out has a clear meaning. Only one `down` marker is allowed per injection tuple.
 
 #### Iter cursor
 
-Pass `Iter` as the first argument to `each`, `forEach`, `enter`, `exit`, `update`, or `sort` to receive a reusable cursor object instead of the bare entity. The cursor exposes:
+Pass `Iter` as the first argument to `each`, `forEach`, `enter`, `exit`, `update`, or `orderBy` to receive a reusable cursor object instead of the bare entity. The cursor exposes:
 
 - `it.entity` — the visited entity.
-- `it.src` — a same-length array of source entities: the visited entity for a directly-injected component, the relationship target for an `up`-injected one, or the specific child for a `down`-injected one.
+- `it.src` — a same-length array of source entities: the visited entity for a directly-injected component, the relationship target for a `target`-injected one, or the specific child for a `down`-injected one.
 
 ```ts
-system.each(Iter, [Body, { up: [ChildOf, [Position]] }], (it, [body, pos]) => {
+system.each(Iter, [Body, { target: [ChildOf, [Position]] }], (it, [body, pos]) => {
   it.entity; // the visited entity
   it.src[0]; // entity `body` was read from (the visited entity)
   it.src[1]; // entity `pos` was read from (the ChildOf target)
@@ -611,26 +597,27 @@ system.each(Iter, [Body, { up: [ChildOf, [Position]] }], (it, [body, pos]) => {
 
 When `Iter` is **not** requested, the original code path runs with zero per-entity overhead. Dispatch to the cursor or non-cursor path happens once at setup time — not per entity. A single `Iter` instance is mutated before each callback; read what you need inside the callback but do not retain the cursor or its `src` array across callbacks.
 
-`enter` and `exit` allocate a fresh `Iter` per event (they fire reentrantly during command routing). `each` / `forEach` / `update` reuse a single `Iter` instance for the whole pass; `sort` reuses two (one per side of the comparison). Because a plain `Query.update` callback fires synchronously during command routing, a nested mutation triggered from inside it can re-enter `update` and overwrite that reused cursor and tuple mid-callback — snapshot any `it`, `it.src`, or tuple values you need before triggering further mutations.
+`enter` and `exit` allocate a fresh `Iter` per event (they fire reentrantly during command routing). `each` / `forEach` / `update` reuse a single `Iter` instance for the whole pass; `orderBy` reuses two (one per side of the comparison). Because a plain `Query.update` callback fires synchronously during command routing, a nested mutation triggered from inside it can re-enter `update` and overwrite that reused cursor and tuple mid-callback — snapshot any `it`, `it.src`, or tuple values you need before triggering further mutations.
 
 Class-valued query terms are components. Register component classes before using them in a `QueryDSL`; an unregistered class throws. Use `{ test: fn }` for arbitrary predicate functions.
 
-**Type inference.** `requires()` records the listed classes as a type parameter `R` on the system. Callbacks in `.sort()`, `.each()`, and `.update()` injection treat those components as non-nullable — no `!` needed. For complex `query()` expressions the type system can't introspect, supply a `_guaranteed` second argument:
+**Type inference.** `with()` records inferrable component classes as a type parameter `R` on the system. Callbacks in `.orderBy()`, `.each()`, and `.update()` injection treat those components as non-nullable — no `!` needed. For complex `with()` expressions the type system can't introspect, supply a `hint` field:
 
 ```ts
-.query({ all: [Position, Velocity] }, [Position, Velocity])
+.with({ with: { all: [Position, Velocity] }, hint: [Position, Velocity] })
 .each([Position, Velocity], (e, [pos, vel]) => {
   pos.x += vel.vx; // pos and vel are non-null
 });
 ```
 
-#### `.phase(p)`
+#### `.phase(anchor)`
 
-Assign the system to a phase by name or `IPhase` reference. Default phase is `"update"`.
+Place the system after a pipeline anchor by name or entity. Sets `DependsOn` on the system's backing entity (replacing any previous target) and tags the anchor with `Phase`, so it is picked up and ordered by the default pipeline query. Systems default to `vecs::OnUpdate`, so call this only to run elsewhere.
 
 ```ts
-.phase("preupdate")
-.phase(myPhase)
+.phase(ON_LOAD)                 // a built-in phase constant
+.phase("custom")               // a custom anchor, created and tagged if missing
+.phase(world.entity("custom")) // an existing entity
 ```
 
 #### `.enter(callback)` / `.enter(inject, callback)`
@@ -646,7 +633,7 @@ Fires once when an entity first matches the system.
 
 #### `.exit(callback)` / `.exit(inject, callback)`
 
-Fires when an entity leaves the system (component removed or entity destroyed). Direct components removed in the same frame are still resolvable in `inject`; `up` injection resolves relationship targets live.
+Fires when an entity leaves the system (component removed or entity destroyed). Direct components removed in the same frame are still resolvable in `inject`; `target` injection resolves relationship targets live.
 
 ```ts
 .exit([Sprite], (e, [sprite]) => sprite.destroy());
@@ -664,38 +651,38 @@ Fires when `entity.modified(ComponentClass)` is called for the watched component
 });
 ```
 
-If `query()` has not been called, `update` automatically expands the implicit component predicate to require the watched component.
+If `with()` has not been called, `update` automatically expands the implicit component predicate to require the watched component.
 
 #### `.each(components, callback)`
 
 Fires every tick for **every tracked entity**, regardless of whether anything changed. Use it for per-entity logic that must run every frame. Implies `.track()`. Only one `each` per system.
 
 ```ts
-.requires(Position, Velocity)
+.with(Position, Velocity)
 .each([Position, Velocity], (e, [pos, vel]) => {
   pos.x += vel.vx;
 });
 ```
 
-#### `.sort(components, compare)`
+#### `.orderBy(components, compare)`
 
 Store matched entities in a custom order determined by `compare`. Implies `.track()`. Iterating the system, `forEach`, and `each` walks entities in sorted order.
 
 ```ts
 world
   .system("Render")
-  .requires(Position, Sprite)
-  .sort([Position], (_entityA, [posA], _entityB, [posB]) => posA.z - posB.z)
+  .with(Position, Sprite)
+  .orderBy([Position], (_entityA, [posA], _entityB, [posB]) => posA.z - posB.z)
   .each([Position, Sprite], (e, [pos, sprite]) => sprite.draw(pos.x, pos.y));
 ```
 
 #### `.track()`
 
-Enable entity tracking without an `each` callback — exposes matched entities via `system.count`, `system.has(e)`, and direct iteration. `each` and `sort` imply `track` automatically. When called after `world.start()`, immediately backfills existing matched entities.
+Enable entity tracking without an `each` callback — exposes matched entities via `system.count`, `system.has(e)`, and direct iteration. `each` and `orderBy` imply `track` automatically. Backfills existing matched entities when the system is built.
 
 #### `.run(callback)`
 
-Fires every tick when the system's phase runs, regardless of entity state. Use for polling, network I/O, timers, etc.
+Fires every tick when the system runs in the pipeline, regardless of entity state. Use for polling, network I/O, timers, etc.
 
 ```ts
 .run((now, delta) => {
@@ -708,7 +695,7 @@ Fires every tick when the system's phase runs, regardless of entity state. Use f
 Pause and resume a system at runtime. While disabled the system is effectively invisible: the inbox is cleared immediately, any new `enter`, `exit`, or `update` events are silently dropped, `run` and `each` callbacks do not fire, and the system skips its `_run` entirely. Entity membership in the underlying query is still maintained, so the tracked set remains correct and the system resumes cleanly when re-enabled. Events that occurred while the system was disabled are **not** replayed.
 
 ```ts
-const ai = world.system("AI").requires(Enemy).run(tickAI);
+const ai = world.system("AI").with(Enemy).run(tickAI);
 
 // Pause AI processing during a cutscene:
 ai.disable();
@@ -721,25 +708,23 @@ Both methods return `this` for chaining and are idempotent (calling `disable()`
 
 #### `.destroy()`
 
-Permanently remove this system from the world. Calls `disable()` first (clearing the inbox), then removes the system from its phase and unregisters its backing entity. No `exit` callbacks fire. Use a standalone `Query` if you need a temporary reactive set that can be destroyed mid-session.
+Permanently remove this system from the world. Calls `disable()` first (clearing the inbox), then unregisters its backing entity. No `exit` callbacks fire. Use a standalone `Query` if you need a temporary reactive set that can be destroyed mid-session.
 
 ---
 
 ### `Query`
 
-`world.query(name)` returns a standalone reactive entity set, configured through the same builder API as `System`. It has no phase and no per-tick callbacks.
+`world.query(name)` returns a standalone reactive entity set, configured through the same builder API as `System`. It has no per-tick callbacks.
 
 ```ts
 const projectiles = world
   .query("Projectiles")
-  .requires(Position, Velocity)
-  .sort([Position], (_entityA, [a], _entityB, [b]) => a.z - b.z)
+  .with(Position, Velocity)
+  .orderBy([Position], (_entityA, [a], _entityB, [b]) => a.z - b.z)
   .enter([Position], (e, [pos]) => {
     pos.x = spawnX;
   });
 
-world.start();
-
 projectiles.forEach((e) => { ... });
 for (const e of projectiles) { ... }
 console.log(projectiles.count, "active projectiles");
@@ -747,13 +732,13 @@ console.log(projectiles.count, "active projectiles");
 
 | Method                                                  | Description                                                                                         |
 | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `.requires(...components)`                              | Set the membership predicate to require all listed components and start tracking.                   |
-| `.query(expr, _guaranteed?)`                            | Set the membership predicate using a `QueryDSL` expression.                                         |
+| `.with(...specs)`                                       | Add membership predicates using `QuerySpec` expressions.                                            |
+| `.without(dsl)`                                         | Add a negated membership predicate; shorthand for `.with({ not: dsl })`.                            |
 | `.enter(callback)` / `.enter(inject, callback)`         | Fires when an entity joins the query.                                                               |
 | `.exit(callback)` / `.exit(inject, callback)`           | Fires when an entity leaves the query.                                                              |
 | `.update(C, callback)` / `.update(C, inject, callback)` | Fires when `C` is modified on a tracked entity. Callback receives `(entity, component, injected?)`. |
-| `.sort(components, compare)`                            | Store matched entities in sorted order. Comparator receives `(entityA, tupleA, entityB, tupleB)`.   |
-| `.track()`                                              | Enable tracking. Backfills when called after `start()`.                                             |
+| `.orderBy(components, compare)`                         | Store matched entities in sorted order. Comparator receives `(entityA, tupleA, entityB, tupleB)`.   |
+| `.track()`                                              | Enable tracking. Backfills existing matches when the query is built.                                |
 | `.belongs(e)`                                           | Returns `true` if the entity satisfies the predicate.                                               |
 | `.count`                                                | Number of currently tracked entities.                                                               |
 | `.has(e)`                                               | Returns `true` if the entity is currently tracked.                                                  |
@@ -767,12 +752,12 @@ console.log(projectiles.count, "active projectiles");
 `destroy()` permanently removes a standalone query from the world. Entity references are silently purged (no `exit` callbacks fire), the tracked set is cleared, and the `world` reference is set to `undefined`. Any further use of the object is **undefined behavior**.
 
 ```ts
-const q = world.query("Temporary").requires(Position);
+const q = world.query("Temporary").with(Position);
 // ... use q.count, q.has(e), or iterate q ...
 q.destroy();
 ```
 
-`System` shares the same DSL, callback, sorting, and tracking machinery — `System` extends `Query` and adds phase placement, `run`, `each`, and an inbox replayed on every tick.
+`System` shares the same DSL, callback, sorting, and tracking machinery — `System` extends `Query` and adds `run`, `each`, and an inbox replayed on every tick.
 
 ---
 
@@ -791,14 +776,14 @@ const f = world.filter([Position, Velocity]);
 
 `forEach` runs inside a deferred scope, so mutations made by the callback are batched and become visible after iteration finishes.
 
-**Type inference.** Component classes the type system can extract from the DSL (plain component classes, plain arrays, `only`, and `all` of those) are non-nullable in the callback tuple. For the rest, supply a `_guaranteed` second argument to `world.filter()`:
+**Type inference.** Component classes the type system can extract from the DSL (plain component classes, plain arrays, `only`, and `all` of those) are non-nullable in the callback tuple. For the rest, supply a `hint` field:
 
 ```ts
 // Auto-deduced — both non-null:
 world.filter([Position, Velocity]).forEach([Position, Velocity], (e, [pos, vel]) => { ... });
 
 // Manual hint for any / not / test:
-world.filter({ any: [Position, Velocity] }, [Position]).forEach([Position], (e, [pos]) => pos.x);
+world.filter({ with: { any: [Position, Velocity] }, hint: [Position] }).forEach([Position], (e, [pos]) => pos.x);
 ```
 
 A `Filter` holds no tracked set, makes no registration calls, and needs no `destroy()`.

package/dist/component.d.ts

@@ -1,6 +1,6 @@
 import { Entity } from "./entity/index.js";
-import type { ComponentType } from "./component_meta.js";
-export { CleanupPolicy, ComponentMeta, type ComponentClass, type ComponentInstance, type ComponentRef, type ComponentRefArray, type ComponentType, type Hook, } from "./component_meta.js";
+import type { ComponentInstance, ComponentType } from "./component_meta.js";
+export { CleanupPolicy, ComponentMeta, Relationship, type ComponentClass, type ComponentInstance, type ComponentRef, type ComponentRefArray, type ComponentType, type Hook, } from "./component_meta.js";
 /** A component entity created by {@link World.component}. */
 export declare class Component<T extends ComponentType = ComponentType> extends Entity {
     /**
@@ -19,6 +19,7 @@ export declare class Component<T extends ComponentType = ComponentType> extends
      * ```
      */
     onAdd(handler: (entity: Entity, c: InstanceType<T>) => void): this;
+    onAdd(handler: (entity: Entity, c: ComponentInstance) => void): this;
     /**
      * Register a callback fired each time this component is **removed** from an
      * entity, or when the owning entity is destroyed.
@@ -36,6 +37,7 @@ export declare class Component<T extends ComponentType = ComponentType> extends
      * ```
      */
     onRemove(handler: (entity: Entity, c: InstanceType<T>) => void): this;
+    onRemove(handler: (entity: Entity, c: ComponentInstance) => void): this;
     /**
      * Register a callback fired each time this component's data is **set or
      * modified**.
@@ -59,4 +61,5 @@ export declare class Component<T extends ComponentType = ComponentType> extends
      * ```
      */
     onSet(handler: (entity: Entity, c: InstanceType<T>) => void): this;
+    onSet(handler: (entity: Entity, c: ComponentInstance) => void): this;
 }

package/dist/component.js

@@ -1,70 +1,17 @@
 import { Entity } from "./entity/index.js";
-export { CleanupPolicy, ComponentMeta, } from "./component_meta.js";
+export { CleanupPolicy, ComponentMeta, Relationship, } from "./component_meta.js";
 /** A component entity created by {@link World.component}. */
 export class Component extends Entity {
-    /**
-     * Register a callback fired each time this component is **added** to an entity.
-     *
-     * The handler is called with the owning entity and the freshly created
-     * component instance. Use it to initialise external state (e.g. scene objects)
-     * that should exist for the lifetime of the component.
-     *
-     * @param handler - Callback invoked with `(entity, componentInstance)`.
-     * @returns This `Component` entity, for chaining.
-     *
-     * @example
-     * ```ts
-     * world.component(Sprite).onAdd((entity, sprite) => sprite.initialize(scene));
-     * ```
-     */
     onAdd(handler) {
-        this.ownMeta.onAdd(handler);
+        super.onAdd(handler);
         return this;
     }
-    /**
-     * Register a callback fired each time this component is **removed** from an
-     * entity, or when the owning entity is destroyed.
-     *
-     * The handler is called with the owning entity and the component instance that
-     * is about to be detached. Use it to clean up any external state associated
-     * with the component.
-     *
-     * @param handler - Callback invoked with `(entity, componentInstance)`.
-     * @returns This `Component` entity, for chaining.
-     *
-     * @example
-     * ```ts
-     * world.component(Sprite).onRemove((entity, sprite) => sprite.destroy(scene));
-     * ```
-     */
     onRemove(handler) {
-        this.ownMeta.onRemove(handler);
+        super.onRemove(handler);
         return this;
     }
-    /**
-     * Register a callback fired each time this component's data is **set or
-     * modified**.
-     *
-     * Fires when:
-     * - `entity.set(C, props)` applies data to the component.
-     * - `entity.attach(instance)` stores an existing instance.
-     * - `entity.modified(C)` is called after in-place mutation.
-     * - A system's `getMut(C)` marks the component dirty.
-     *
-     * The handler receives the owning entity and the current component instance.
-     * Component instances do not carry entity references, which is why the entity
-     * is passed explicitly.
-     *
-     * @param handler - Callback invoked with `(entity, componentInstance)`.
-     * @returns This `Component` entity, for chaining.
-     *
-     * @example
-     * ```ts
-     * world.component(Transform).onSet((entity, t) => renderer.syncTransform(entity.eid, t));
-     * ```
-     */
     onSet(handler) {
-        this.ownMeta.onSet(handler);
+        super.onSet(handler);
         return this;
     }
 }

package/dist/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EACL,aAAa,EACb,aAAa,GAOd,MAAM,qBAAqB,CAAC;AAE7B,6DAA6D;AAC7D,MAAM,OAAO,SAAmD,SAAQ,MAAM;IAC5E;;;;;;;;;;;;;;OAcG;IACI,KAAK,CAAC,OAAqD;QAChE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAyD,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,QAAQ,CAAC,OAAqD;QACnE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAyD,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,KAAK,CAAC,OAAqD;QAChE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAyD,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,GAOb,MAAM,qBAAqB,CAAC;AAE7B,6DAA6D;AAC7D,MAAM,OAAO,SAAmD,SAAQ,MAAM;IAkB5D,KAAK,CAAC,OAAyC;QAC7D,KAAK,CAAC,KAAK,CAAC,OAAyD,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAoBe,QAAQ,CAAC,OAAyC;QAChE,KAAK,CAAC,QAAQ,CAAC,OAAyD,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IA0Be,KAAK,CAAC,OAAyC;QAC7D,KAAK,CAAC,KAAK,CAAC,OAAyD,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}