@vworlds/vecs 1.0.9 → 1.0.11

package/dist/filter.d.ts

@@ -5,49 +5,57 @@ import { type MaybeRequired, type QueryDSL } from "./dsl.js";
 /**
  * A non-reactive, one-shot entity filter.
  *
- * Unlike {@link Query}, a `Filter` holds no tracked entity set and registers
- * nothing with the world. Every {@link forEach} call walks all world entities
- * and invokes the callback for those that match the predicate captured at
- * construction time.
+ * Unlike {@link Query} a `Filter` keeps no tracked entity set and registers
+ * nothing on the world. Each call to {@link forEach} walks all current world
+ * entities and invokes the callback on those that match the predicate captured
+ * at construction time.
  *
- * Create via {@link World.filter}:
+ * Create one through {@link World.filter}:
  *
  * ```ts
  * const f = world.filter([Position, Velocity]);
  *
- * // Entity only:
+ * // Iterate matching entities:
  * f.forEach((e) => console.log(e.eid));
  *
- * // With component injection:
+ * // ...or with component injection:
  * f.forEach([Position, Velocity], (e, [pos, vel]) => {
  *   pos.x += vel.vx;
  * });
  * ```
  *
- * ### Type parameter `R`
- * Tracks which component classes are guaranteed present on every matched
- * entity — inferred automatically from the DSL by {@link World.filter}, or
- * supplied manually via the optional `_guaranteed` argument. Components in `R`
- * appear as non-nullable in `forEach` callback tuples.
+ * `forEach` runs the callback inside a {@link World.defer | deferred scope}, so
+ * mutations made by the callback are batched and become visible after iteration
+ * finishes. Nesting a `forEach` inside an already-deferred block (a system, a
+ * `Query.forEach`, an outer `defer`) inherits the outer scope and does not
+ * drain on exit.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ *   Inferred from the DSL by {@link World.filter} when possible, or supplied
+ *   manually via the `_guaranteed` argument. Components in `R` are non-nullable
+ *   in `forEach` callback tuples.
  */
 export declare class Filter<R extends (typeof Component)[] = []> {
-    private readonly world;
-    private readonly belongs;
-    constructor(world: World, dsl: QueryDSL);
+    /** World this filter reads entities from. */
+    readonly world: World;
+    private readonly _belongs;
+    constructor(
+    /** World this filter reads entities from. */
+    world: World, dsl: QueryDSL);
     /**
-     * Iterate all world entities and call `callback` for each one that matches
-     * the DSL this filter was created with.
+     * Walk all current world entities and call `callback` for each one that
+     * satisfies the filter's DSL.
      *
-     * @param callback - Receives only the entity.
+     * @param callback - Receives only the matching entity.
      */
     forEach(callback: (e: Entity) => void): void;
     /**
-     * Iterate all world entities and call `callback` for each one that matches
-     * the DSL, with component injection.
+     * Walk all current world entities, call `callback` for each one that
+     * satisfies the filter's DSL, and inject the requested component instances.
      *
-     * Components declared via {@link World.filter}'s DSL (or `_guaranteed`) are
-     * non-nullable in the resolved tuple; any other requested component may be
-     * `undefined` if the entity lacks it.
+     * Components covered by the filter's DSL or `_guaranteed` hint are
+     * non-nullable in the resolved tuple; any other component class may be
+     * `undefined` if the entity does not have it.
      *
      * @param components - Component classes to resolve from each matching entity.
      * @param callback - Receives the entity and a tuple of resolved component

package/dist/filter.js

@@ -1,55 +1,64 @@
-import { buildEntityTest } from "./dsl.js";
+import { _buildEntityTest } from "./dsl.js";
 /**
  * A non-reactive, one-shot entity filter.
  *
- * Unlike {@link Query}, a `Filter` holds no tracked entity set and registers
- * nothing with the world. Every {@link forEach} call walks all world entities
- * and invokes the callback for those that match the predicate captured at
- * construction time.
+ * Unlike {@link Query} a `Filter` keeps no tracked entity set and registers
+ * nothing on the world. Each call to {@link forEach} walks all current world
+ * entities and invokes the callback on those that match the predicate captured
+ * at construction time.
  *
- * Create via {@link World.filter}:
+ * Create one through {@link World.filter}:
  *
  * ```ts
  * const f = world.filter([Position, Velocity]);
  *
- * // Entity only:
+ * // Iterate matching entities:
  * f.forEach((e) => console.log(e.eid));
  *
- * // With component injection:
+ * // ...or with component injection:
  * f.forEach([Position, Velocity], (e, [pos, vel]) => {
  *   pos.x += vel.vx;
  * });
  * ```
  *
- * ### Type parameter `R`
- * Tracks which component classes are guaranteed present on every matched
- * entity — inferred automatically from the DSL by {@link World.filter}, or
- * supplied manually via the optional `_guaranteed` argument. Components in `R`
- * appear as non-nullable in `forEach` callback tuples.
+ * `forEach` runs the callback inside a {@link World.defer | deferred scope}, so
+ * mutations made by the callback are batched and become visible after iteration
+ * finishes. Nesting a `forEach` inside an already-deferred block (a system, a
+ * `Query.forEach`, an outer `defer`) inherits the outer scope and does not
+ * drain on exit.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity.
+ *   Inferred from the DSL by {@link World.filter} when possible, or supplied
+ *   manually via the `_guaranteed` argument. Components in `R` are non-nullable
+ *   in `forEach` callback tuples.
  */
 export class Filter {
-    constructor(world, dsl) {
+    constructor(
+    /** World this filter reads entities from. */
+    world, dsl) {
         this.world = world;
-        this.belongs = buildEntityTest(world, dsl);
+        this._belongs = _buildEntityTest(world, dsl);
     }
     forEach(componentsOrCallback, callback) {
-        if (typeof componentsOrCallback === "function") {
-            this.world._forEachEntity((e) => {
-                if (this.belongs(e)) {
-                    componentsOrCallback(e);
-                }
-            });
-        }
-        else {
-            const types = componentsOrCallback.map((C) => this.world.getComponentType(C));
-            this.world._forEachEntity((e) => {
-                if (!this.belongs(e)) {
-                    return;
-                }
-                const resolved = types.map((t) => e.get(t));
-                callback(e, resolved);
-            });
-        }
+        this.world.defer(() => {
+            if (typeof componentsOrCallback === "function") {
+                this.world.entities.forEach((e) => {
+                    if (this._belongs(e)) {
+                        componentsOrCallback(e);
+                    }
+                });
+            }
+            else {
+                const types = componentsOrCallback.map((C) => this.world.getComponentType(C));
+                this.world.entities.forEach((e) => {
+                    if (!this._belongs(e)) {
+                        return;
+                    }
+                    const resolved = types.map((t) => e.get(t));
+                    callback(e, resolved);
+                });
+            }
+        });
     }
 }
 //# sourceMappingURL=filter.js.map

package/dist/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAA0D,MAAM,UAAU,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,MAAM;IAGjB,YACmB,KAAY,EAC7B,GAAa;QADI,UAAK,GAAL,KAAK,CAAO;QAG7B,IAAI,CAAC,OAAO,GAAG,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IA2BM,OAAO,CACZ,oBAA6D,EAC7D,QAAoF;QAEpF,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE;YAC9C,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;oBACnB,oBAAoB,CAAC,CAAC,CAAC,CAAC;iBACzB;YACH,CAAC,CAAC,CAAC;SACJ;aAAM;YACL,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9E,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;oBACpB,OAAO;iBACR;gBACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;SACJ;IACH,CAAC;CACF"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAA0D,MAAM,UAAU,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,MAAM;IAGjB;IACE,6CAA6C;IAC7B,KAAY,EAC5B,GAAa;QADG,UAAK,GAAL,KAAK,CAAO;QAG5B,IAAI,CAAC,QAAQ,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;IA2BM,OAAO,CACZ,oBAA6D,EAC7D,QAAoF;QAEpF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE;gBAC9C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;wBACpB,oBAAoB,CAAC,CAAC,CAAC,CAAC;qBACzB;gBACH,CAAC,CAAC,CAAC;aACJ;iBAAM;gBACL,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC9E,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;wBACrB,OAAO;qBACR;oBACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;gBAChC,CAAC,CAAC,CAAC;aACJ;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type System } from "./system.js";
+export { type System, type SystemQuery } from "./system.js";
 export { Query } from "./query.js";
 export { World } from "./world.js";
 export { Filter } from "./filter.js";

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vworlds/vecs",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -12,6 +12,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "format:check": "prettier --check \"**/*.{ts,md}\"",
     "prepare": "husky"
   },
   "devDependencies": {

package/dist/phase.d.ts

@@ -1,32 +1,9 @@
-import { type System } from "./system.js";
 import { type World } from "./world.js";
 /**
- * A named, ordered bucket of {@link System | systems} within the world's
- * update pipeline.
+ * Public interface for a pipeline phase, returned by {@link World.addPhase}.
  *
- * Created internally by {@link World.addPhase}. The systems in a phase run in
- * the order they were registered. Between each system run the world flushes
- * pending archetype changes, so `enter` / `exit` callbacks are always
- * delivered before the next system executes.
- *
- * @internal The concrete class is not part of the public API. Use
- * {@link IPhase} to refer to phases in user code.
- */
-export declare class Phase {
-    /** Name used to look up the phase in the pipeline. */
-    readonly name: string;
-    world: World;
-    /** Systems that belong to this phase, in execution order. */
-    systems: System[];
-    constructor(
-    /** Name used to look up the phase in the pipeline. */
-    name: string, world: World);
-}
-/**
- * Public interface for a pipeline phase returned by {@link World.addPhase}.
- *
- * Pass an `IPhase` to {@link System.phase} to assign a system to that phase,
- * or to {@link World.runPhase} to execute it:
+ * Pass an `IPhase` to {@link System.phase} to assign a system to the phase, or
+ * to {@link World.runPhase} to execute the phase:
  *
  * ```ts
  * const preUpdate = world.addPhase("preupdate");
@@ -40,8 +17,8 @@ export declare class Phase {
  * ```
  */
 export interface IPhase {
-    /** The name this phase was registered under. */
+    /** Name this phase was registered under. */
     get name(): string;
-    /** The world that owns this phase. */
+    /** World that owns this phase. */
     get world(): World;
 }

package/dist/phase.js

@@ -1,22 +1,23 @@
 /**
- * A named, ordered bucket of {@link System | systems} within the world's
- * update pipeline.
+ * Concrete implementation of {@link IPhase}: a named, ordered bucket of
+ * {@link System | systems} within a world's update pipeline.
  *
- * Created internally by {@link World.addPhase}. The systems in a phase run in
- * the order they were registered. Between each system run the world flushes
- * pending archetype changes, so `enter` / `exit` callbacks are always
- * delivered before the next system executes.
+ * Created by {@link World.addPhase}. Systems run in the order they were added
+ * to the phase. Between systems the world drains pending commands so each
+ * system observes a consistent view of the world.
  *
- * @internal The concrete class is not part of the public API. Use
- * {@link IPhase} to refer to phases in user code.
+ * @internal The class itself is not part of the public API; user code should
+ * refer to phases via {@link IPhase}.
  */
 export class Phase {
     constructor(
     /** Name used to look up the phase in the pipeline. */
-    name, world) {
+    name, 
+    /** World that owns this phase. */
+    world) {
         this.name = name;
         this.world = world;
-        /** Systems that belong to this phase, in execution order. */
+        /** Systems registered in this phase, in execution order. */
         this.systems = [];
     }
 }

package/dist/phase.js.map

@@ -1 +1 @@
-{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,KAAK;IAIhB;IACE,sDAAsD;IACtC,IAAY,EACrB,KAAY;QADH,SAAI,GAAJ,IAAI,CAAQ;QACrB,UAAK,GAAL,KAAK,CAAO;QANrB,6DAA6D;QACtD,YAAO,GAAa,EAAE,CAAC;IAM3B,CAAC;CACL"}
+{"version":3,"file":"phase.js","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,KAAK;IAIhB;IACE,sDAAsD;IACtC,IAAY;IAC5B,kCAAkC;IAClB,KAAY;QAFZ,SAAI,GAAJ,IAAI,CAAQ;QAEZ,UAAK,GAAL,KAAK,CAAO;QAP9B,4DAA4D;QACrD,YAAO,GAAa,EAAE,CAAC;IAO3B,CAAC;CACL"}

package/dist/query.d.ts

@@ -3,81 +3,87 @@ import type { Entity } from "./entity.js";
 import { type World } from "./world.js";
 import { type EntityTestFunc, type QueryDSL, type MaybeRequired } from "./dsl.js";
 export type { EntityTestFunc, QueryDSL, MaybeRequired };
-type EntityCallback = (e: Entity) => void;
+/** Component class, or `{ parent: ComponentClass }` to resolve from the entity's parent. */
 type ComponentOrParent = typeof Component | {
     parent: typeof Component;
 };
+/** Resolves the component instance type for one element of a `ComponentOrParent` tuple. */
 type ComponentInstance<T> = T extends {
     parent: typeof Component;
 } ? InstanceType<T["parent"]> : T extends typeof Component ? InstanceType<T> : never;
 /**
- * A reactive, always-updated list of entities that match a given query
- * expression.
+ * A reactive, always-up-to-date set of entities matching a {@link QueryDSL}
+ * predicate.
  *
- * `Query` tracks every entity whose component set satisfies the predicate set
- * via {@link requires} or {@link query}. Entry and exit callbacks fire
- * automatically as entities gain or lose matching components. The tracked set
- * is exposed via {@link entities} and {@link forEach}.
+ * `Query` listens to entity / component mutations through the world's command
+ * queue and tracks which entities currently satisfy its predicate. It fires
+ * `enter`, `exit`, and `update` callbacks as the matched set changes. The
+ * tracked set is exposed via {@link entities} and {@link forEach}.
  *
- * {@link System} extends `Query` and adds per-tick runtime concerns
- * (`update`, `each`, `run`). Use `Query` directly when you only need the
- * reactive entity set without pipeline integration.
+ * Callbacks fire **synchronously** when the world routes a command — so
+ * mutations made inside one of these callbacks are themselves observed
+ * immediately by other queries / systems.
  *
- * ### Type parameter `R`
- * Tracks which component classes are "required" (declared via {@link requires}
- * or the `_guaranteed` hint of {@link query}). Those components appear as
- * non-nullable in {@link sort} callbacks.
+ * {@link System} extends `Query` and queues callbacks into an inbox replayed
+ * during `_run` instead of firing them immediately. Use `Query` directly when
+ * you want a reactive entity set without pipeline integration.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity
+ *   (declared via {@link requires} or the `_guaranteed` hint of {@link query}).
+ *   Components in `R` appear as non-nullable in {@link sort}, {@link forEach},
+ *   and {@link update} callback tuples.
  */
 export declare class Query<R extends (typeof Component)[] = []> {
-    /** Unique name for this query, used in logs and debug output. */
+    /** Unique display name; appears in logs and debug output. */
     readonly name: string;
-    /** The world that owns this query. */
+    /** World that owns this query. */
     readonly world: World;
-    protected _entities: Set<Entity> | undefined;
-    protected _enterCallback: EntityCallback[];
-    protected _exitCallback: EntityCallback[];
-    protected _belongs: EntityTestFunc;
-    protected hasQuery: boolean;
     constructor(
-    /** Unique name for this query, used in logs and debug output. */
+    /** Unique display name; appears in logs and debug output. */
     name: string, 
-    /** The world that owns this query. */
+    /** World that owns this query. */
     world: World, track?: boolean);
+    /**
+     * Read-only view of the entities currently tracked by this query.
+     *
+     * Populated as entities enter and removed as they exit. Empty unless
+     * tracking is enabled — that is the default for standalone queries created
+     * via {@link World.query}, but {@link System} requires an explicit
+     * {@link track}, {@link sort}, or `each` call.
+     */
+    get entities(): ReadonlySet<Entity>;
     /** Returns the query name. */
     toString(): string;
     /**
      * Enable entity tracking: matched entities are inserted into {@link entities}
      * as they enter and removed as they exit.
      *
-     * Idempotent. When called after {@link World.start}, immediately backfills all
-     * existing entities that currently satisfy the query predicate.
+     * Idempotent. When called after {@link World.start}, immediately backfills
+     * every existing entity that satisfies the current predicate.
      *
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      */
     track(): this;
-    private backfill;
+    /** Returns `true` when `e` satisfies this query's predicate. */
+    belongs(e: Entity): boolean;
     /**
-     * Read-only view of the entities currently tracked by this query.
+     * Iterate every entity currently tracked by this query.
      *
-     * Populated as entities enter (and removed as they exit). Empty unless
-     * tracking is enabled (default for standalone queries; requires an explicit
-     * {@link track} call on {@link System | systems}).
-     */
-    get entities(): ReadonlySet<Entity>;
-    /**
-     * Iterate over every entity currently tracked by this query.
+     * Mutations made by `callback` are buffered into the world command queue
+     * and only become visible after iteration finishes. Nested iteration inside
+     * an already-deferred context (a system, an outer `forEach`) inherits the
+     * outer scope and does not drain on exit.
      *
-     * @param callback - Called once per tracked entity, in insertion order
+     * @param callback - Invoked once per tracked entity, in insertion order
      *   (or sort order when {@link sort} is configured).
      */
     forEach(callback: (e: Entity) => void): void;
     /**
-     * Iterate over every entity currently tracked by this query, with component
-     * injection.
+     * Iterate every tracked entity with component injection.
      *
-     * Components declared via {@link requires} (or the `_guaranteed` hint of
-     * {@link query}) are non-nullable in the resolved tuple; any other requested
-     * component may be `undefined` if the entity lacks it.
+     * Components covered by {@link requires} (or the `_guaranteed` hint of
+     * {@link query}) are non-nullable in the resolved tuple; any other
+     * requested component may be `undefined` if the entity lacks it.
      *
      * @param components - Component classes to resolve from each entity.
      * @param callback - Receives the entity and a tuple of resolved component
@@ -86,22 +92,14 @@ export declare class Query<R extends (typeof Component)[] = []> {
     forEach<J extends (typeof Component)[]>(components: readonly [...J], callback: (e: Entity, resolved: {
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => void): void;
-    /** Returns `true` if the entity satisfies this query's predicate. */
-    belongs(e: Entity): boolean;
-    /** Hook for subclasses — called when a component on an entity in this query changes. */
-    notifyModified(_c: Component): void;
-    /** @internal Fires enter callbacks and adds entity to the tracked set. */
-    _enter(e: Entity): void;
-    /** @internal Fires exit callbacks and removes entity from the tracked set. */
-    _exit(e: Entity): void;
     /**
-     * Register a callback that fires when an entity **enters** this query
-     * (i.e. first satisfies the predicate) with injected components.
+     * Register a callback invoked when an entity **enters** this query (i.e.
+     * first satisfies the predicate), with injected components.
      *
      * @param inject - Ordered list of component classes (or `{ parent: C }`) to
      *   resolve from the entering entity and pass to `callback`.
      * @param callback - Receives the entity and the resolved component tuple.
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      *
      * @example
      * ```ts
@@ -115,44 +113,81 @@ export declare class Query<R extends (typeof Component)[] = []> {
         [K in keyof J]: ComponentInstance<J[K]>;
     }) => void): this;
     /**
-     * Register a callback that fires when an entity enters this query.
+     * Register an `enter` callback without component injection.
      *
-     * @param callback - Receives only the entity (no injection).
-     * @returns `this` for chaining.
+     * @param callback - Receives only the entering entity.
+     * @returns This query, for chaining.
      */
     enter(callback: (e: Entity) => void): this;
     /**
-     * Register a callback that fires when an entity **exits** this query
-     * (its components no longer satisfy the predicate, or it was destroyed) with
+     * Register a callback invoked when an entity **exits** this query (its
+     * archetype no longer satisfies the predicate, or it was destroyed), with
      * injected components.
      *
-     * Components that were just removed are still accessible via `get_deleted`
-     * semantics — the injected tuple includes them even though they are no
-     * longer in the entity's active component set.
+     * Components removed in the same frame as the exit are still resolvable
+     * because the runtime snapshots them at routing time.
      *
      * @param inject - Component classes to resolve and inject.
      * @param callback - Receives the entity and the resolved component tuple.
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      */
     exit<J extends ComponentOrParent[]>(inject: readonly [...J], callback: (e: Entity, injected: {
         [K in keyof J]: ComponentInstance<J[K]>;
     }) => void): this;
     /**
-     * Register a callback that fires when an entity exits this query.
+     * Register an `exit` callback without component injection.
      *
-     * @param callback - Receives only the entity.
-     * @returns `this` for chaining.
+     * @param callback - Receives only the exiting entity.
+     * @returns This query, for chaining.
      */
     exit(callback: (e: Entity) => void): this;
     /**
-     * Enable sorted entity tracking: matched entities are stored in insertion
-     * order determined by `compare`, which receives a tuple of resolved
-     * component instances for each pair of entities being ordered.
+     * Register a callback invoked when a component of `ComponentClass` is
+     * modified on a tracked entity.
+     *
+     * On a {@link Query} the callback fires **immediately** when the world
+     * routes the corresponding `Set` / `Modified` command. On a {@link System}
+     * the event is buffered in the inbox and the callback fires during the
+     * system's next `_run`.
+     *
+     * If no other predicate has been set on this query, the watchlist
+     * automatically expands so `ComponentClass` is implicitly required (the
+     * predicate becomes a `HAS` of every watched type).
+     *
+     * @param ComponentClass - Component class to watch.
+     * @param callback - Receives the modified component instance.
+     * @returns This query, for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("RenderPosition")
+     *   .update(Position, (pos) => sprite.setPosition(pos.x, pos.y));
+     * ```
+     */
+    update<C extends typeof Component>(ComponentClass: C, callback: (c: InstanceType<C>) => void): this;
+    /**
+     * Like {@link update}, but with extra components injected from the same
+     * entity.
+     *
+     * @param ComponentClass - Component class to watch.
+     * @param inject - Additional component classes to resolve from the entity.
+     * @param callback - Receives the modified component and the injected tuple.
+     * @returns This query, for chaining.
+     */
+    update<C extends typeof Component, J extends (typeof Component)[]>(ComponentClass: C, inject: readonly [...J], callback: (c: InstanceType<C>, injected: {
+        [K in keyof J]: MaybeRequired<J[K], R>;
+    }) => void): this;
+    /**
+     * Switch the tracked set to a sorted ordering: matched entities are stored
+     * in the position determined by `compare`, which receives a tuple of
+     * resolved component instances for each pair being ordered.
+     *
+     * Implies {@link track}.
      *
      * @param components - Component classes to resolve and pass to `compare`.
-     * @param compare - Returns a negative number, zero, or positive number when
-     *   `a` should sort before, equal to, or after `b`.
-     * @returns `this` for chaining.
+     * @param compare - Negative when `a` should sort before `b`, zero for
+     *   equality, positive when `a` should sort after `b`.
+     * @returns This query, for chaining.
      *
      * @example
      * ```ts
@@ -167,17 +202,18 @@ export declare class Query<R extends (typeof Component)[] = []> {
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => number): this;
     /**
-     * Set the entity membership predicate using the {@link QueryDSL} DSL.
+     * Set the entity-membership predicate using a {@link QueryDSL} expression.
      *
-     * Replaces any previous predicate. The optional `guaranteed` tuple is a
-     * pure type-level hint: it tells {@link sort} callbacks which components are
-     * guaranteed present on every matched entity, eliminating `| undefined` from
-     * those positions. It has no effect at runtime.
+     * Replaces any previous predicate. The optional `_guaranteed` tuple is a
+     * pure type-level hint: it tells {@link sort} / {@link forEach} /
+     * {@link update} callbacks which components are guaranteed present on every
+     * matched entity, eliminating `| undefined` from those positions. It has no
+     * effect at runtime.
      *
-     * @param q - A {@link QueryDSL} expression.
+     * @param q - Query expression.
      * @param _guaranteed - Component classes guaranteed present on every matched
      *   entity (type hint only — not validated at runtime).
-     * @returns `this` for chaining.
+     * @returns This query, retyped with the guaranteed tuple as its `R`.
      *
      * @example
      * ```ts
@@ -190,28 +226,26 @@ export declare class Query<R extends (typeof Component)[] = []> {
      */
     query<T extends (typeof Component)[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): Query<T>;
     /**
-     * Remove this query from the world and all entities.
+     * Shorthand for `query([...components])`: track entities that have **all**
+     * of the listed component types.
      *
-     * Every entity that currently belongs to this query has the query silently
-     * removed (no exit callbacks are fired). After this call the query is
-     * unregistered from its world and `world` is set to `undefined` by force.
+     * Equivalent to `query({ HAS: components })`. Unlike `query`, the listed
+     * components are also recorded in the type parameter `R`, so {@link sort}
+     * and {@link forEach} callbacks see them as non-nullable.
      *
-     * Calling any method on the query after `destroy()` is **undefined behavior**.
+     * @param components - Component classes to require.
+     * @returns This query, retyped with the required tuple as its `R`.
      */
-    destroy(): void;
+    requires<T extends (typeof Component)[]>(...components: [...T]): Query<T>;
     /**
-     * Shorthand for `query([...components])` — tracks entities that have
-     * **all** of the listed component types.
+     * Permanently remove this query from the world.
      *
-     * Equivalent to `query({ HAS: components })`. Unlike `query`, passing
-     * component classes here also informs the types of {@link sort} callbacks:
-     * listed components will be non-nullable in those tuples.
+     * Every entity that currently belongs to this query has the membership
+     * silently purged (no `exit` callbacks fire), the tracked set is cleared,
+     * and the `world` reference is forced to `undefined`. Calling any method on
+     * the query afterwards is **undefined behavior**.
      *
-     * @param components - One or more component classes.
-     * @returns `this` for chaining.
+     * Not supported on {@link System} — calling it on a system throws.
      */
-    requires<T extends (typeof Component)[]>(...components: [...T]): Query<T>;
-    private getComponent;
-    private getInjected;
-    private mapInjectedClassToTypes;
+    destroy(): void;
 }