@vworlds/vecs 1.0.15 → 1.0.16

package/dist/component.d.ts

@@ -1,86 +1,62 @@
-import { BitPtr } from "./util/bitset.js";
-import type { Entity } from "./entity.js";
-/** A component instance. Components are plain objects created with a no-arg constructor. */
-export type Component = object;
-/** A component class constructor. */
-export type ComponentClass<T extends Component = Component> = new () => T;
-/** A component class constructor or its numeric type id. */
-export type ComponentClassOrType = number | ComponentClass;
-/**
- * Lifecycle hook for a registered component class. Obtained via
- * {@link World.hook}.
- *
- * Hooks are a lightweight alternative to building a {@link System} when all
- * you need is a callback on add / remove / set for a single component type.
- * The same `Hook` is returned on every call to `world.hook(C)`, so registration
- * methods chain:
- *
- * ```ts
- * world.hook(Sprite)
- *   .onAdd((e, c) => initSprite(e, c))
- *   .onRemove((e, c) => destroySprite(e, c))
- *   .onSet((e, c) => syncSprite(e, c));
- * ```
- *
- * Callbacks fire synchronously when the corresponding entity command is
- * applied: inline outside deferred mode, or while the world drains its command
- * queue inside a system / `forEach` / `defer` block.
- *
- * @typeParam C - Component class this hook is bound to.
- */
-export interface Hook<C extends Component = Component> {
+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";
+/** A component entity created by {@link World.component}. */
+export declare class Component<T extends ComponentType = ComponentType> extends Entity {
     /**
-     * Register a handler invoked when a component of this type is first attached
-     * to an entity (`entity.add(C)` or `entity.set(C, ...)` on an entity that
-     * does not yet have the component).
+     * Register a callback fired each time this component is **added** to an entity.
      *
-     * @param handler - Receives the entity and freshly created component instance.
-     * @returns This hook, for chaining.
+     * 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: (entity: Entity, c: C) => void): Hook<C>;
+    onAdd(handler: (entity: Entity, c: InstanceType<T>) => void): this;
     /**
-     * Register a handler invoked when a component of this type is removed from
-     * an entity (explicit `entity.remove(C)` or implicit removal during
-     * `entity.destroy()`).
+     * 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.
      *
-     * @param handler - Receives the entity and component instance that was removed.
-     * @returns This hook, for chaining.
+     * @example
+     * ```ts
+     * world.component(Sprite).onRemove((entity, sprite) => sprite.destroy(scene));
+     * ```
      */
-    onRemove(handler: (entity: Entity, c: C) => void): Hook<C>;
+    onRemove(handler: (entity: Entity, c: InstanceType<T>) => void): this;
     /**
-     * Register a handler invoked when a component's data has been marked as
-     * changed (`entity.modified(C)`), and when
-     * `entity.set(C, props)` is called on an entity that already has the
-     * component.
+     * Register a callback fired each time this component's data is **set or
+     * modified**.
      *
-     * @param handler - Receives the entity and component instance whose data changed.
-     * @returns This hook, for chaining.
+     * 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: (entity: Entity, c: C) => void): Hook<C>;
-}
-/**
- * Bookkeeping record produced for each component class registered via
- * {@link World.registerComponent}.
- *
- * Holds the constructor, numeric type id, display name, and pre-computed
- * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
- * lifecycle handlers attached via `world.hook(C)` are stored directly on the
- * meta object.
- */
-export declare class ComponentMeta implements Hook<Component> {
-    /** The component class constructor this meta represents. */
-    readonly Class: ComponentClass;
-    /** Numeric type id assigned at registration time. */
-    readonly type: number;
-    /** Human-readable name used in logs and serialization lookups. */
-    readonly componentName: string;
-    /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
-    readonly bitPtr: BitPtr;
-    constructor(Class: ComponentClass, type: number, componentName: string);
-    /** @inheritdoc */
-    onAdd(handler: (entity: Entity, c: Component) => void): ComponentMeta;
-    /** @inheritdoc */
-    onRemove(handler: (entity: Entity, c: Component) => void): ComponentMeta;
-    /** @inheritdoc */
-    onSet(handler: (entity: Entity, c: Component) => void): ComponentMeta;
+    onSet(handler: (entity: Entity, c: InstanceType<T>) => void): this;
 }

package/dist/component.js

@@ -1,56 +1,71 @@
-import { BitPtr, Bitset } from "./util/bitset.js";
-/**
- * Bookkeeping record produced for each component class registered via
- * {@link World.registerComponent}.
- *
- * Holds the constructor, numeric type id, display name, and pre-computed
- * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
- * lifecycle handlers attached via `world.hook(C)` are stored directly on the
- * meta object.
- */
-export class ComponentMeta {
-    constructor(Class, type, componentName) {
-        /**
-         * @internal Peer metas of components that cannot coexist with this one on
-         * the same entity. Set via {@link World.setExclusiveComponents}; `undefined`
-         * means no restriction.
-         */
-        this._exclusive = undefined;
-        this.Class = Class;
-        this.type = type;
-        this.componentName = componentName;
-        this.bitPtr = new BitPtr(type);
-    }
-    /** @inheritdoc */
+import { Entity } from "./entity/index.js";
+export { CleanupPolicy, ComponentMeta, } 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._onAddHandlers ?? (this._onAddHandlers = [])).unshift(handler);
+        this.ownMeta.onAdd(handler);
         return this;
     }
-    /** @inheritdoc */
+    /**
+     * 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._onRemoveHandlers ?? (this._onRemoveHandlers = [])).unshift(handler);
+        this.ownMeta.onRemove(handler);
         return this;
     }
-    /** @inheritdoc */
+    /**
+     * 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._onSetHandlers ?? (this._onSetHandlers = [])).unshift(handler);
+        this.ownMeta.onSet(handler);
         return this;
     }
 }
-/**
- * Compute a {@link Bitset} with one bit set for every component class or
- * numeric type id in `classes`.
- *
- * @internal Used to build archetype masks for `HAS` / `HAS_ONLY` queries.
- *
- * @param classes - Component classes or type ids to include.
- * @param world - World used to resolve classes to type ids.
- */
-export function _calculateComponentBitmask(classes, world) {
-    const bitmask = new Bitset();
-    classes.forEach((C) => {
-        bitmask.add(world.getComponentType(C));
-    });
-    return bitmask;
-}
 //# sourceMappingURL=component.js.map

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,EAAE,MAAM,kBAAkB,CAAC;AAoElD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAwBxB,YAAY,KAAqB,EAAE,IAAY,EAAE,aAAqB;QAdtE;;;;WAIG;QACI,eAAU,GAAgC,SAAS,CAAC;QAUzD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+C;QAC1D,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+C;QAC7D,CAAC,IAAI,CAAC,iBAAiB,KAAtB,IAAI,CAAC,iBAAiB,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+C;QAC1D,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAA4B,EAAE,KAAY;IACnF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"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"}

package/dist/component_meta.d.ts

@@ -0,0 +1,98 @@
+import { BitPtr } from "./util/bitset.js";
+import type { Entity, EntityClass } from "./entity/index.js";
+export declare enum CleanupPolicy {
+    Throw = "throw",
+    Remove = "remove",
+    Delete = "delete"
+}
+/** A component instance. Components are plain objects created with a no-arg constructor. */
+export type ComponentInstance = object;
+/** A component constructor used as a component key. */
+export type ComponentType<T extends ComponentInstance = ComponentInstance> = new (...args: any[]) => T;
+/** A component class constructor that can be instantiated by entity.add/set. */
+export type ComponentClass<T extends ComponentInstance = ComponentInstance> = new () => T;
+/** A component class constructor, component eid, or entity component key. */
+export type ComponentRef = number | ComponentType | EntityClass | Entity;
+/**
+ * Lifecycle hook for a registered component class. Exposed by
+ * {@link World.component}.
+ *
+ * Hooks are a lightweight alternative to building a {@link System} when all
+ * you need is a callback on add / remove / set for a single component type.
+ * Component entities expose the same registration methods, so calls chain:
+ *
+ * ```ts
+ * world.component(Sprite)
+ *   .onAdd((e, c) => initSprite(e, c))
+ *   .onRemove((e, c) => destroySprite(e, c))
+ *   .onSet((e, c) => syncSprite(e, c));
+ * ```
+ *
+ * Callbacks fire synchronously when the corresponding entity command is
+ * applied: inline outside deferred mode, or while the world drains its command
+ * queue inside a system / `forEach` / `defer` block.
+ *
+ * @typeParam C - Component class this hook is bound to.
+ */
+export interface Hook<C extends ComponentInstance = ComponentInstance> {
+    /**
+     * Register a handler invoked when a component of this type is first attached
+     * to an entity (`entity.add(C)` or `entity.set(C, ...)` on an entity that
+     * does not yet have the component).
+     *
+     * @param handler - Receives the entity and freshly created component instance.
+     * @returns This hook, for chaining.
+     */
+    onAdd(handler: (entity: Entity, c: C) => void): Hook<C>;
+    /**
+     * Register a handler invoked when a component of this type is removed from
+     * an entity (explicit `entity.remove(C)` or implicit removal during
+     * `entity.destroy()`).
+     *
+     * @param handler - Receives the entity and component instance that was removed.
+     * @returns This hook, for chaining.
+     */
+    onRemove(handler: (entity: Entity, c: C) => void): Hook<C>;
+    /**
+     * Register a handler invoked when a component's data has been marked as
+     * changed (`entity.modified(C)`), and when
+     * `entity.set(C, props)` is called on an entity that already has the
+     * component.
+     *
+     * @param handler - Receives the entity and component instance whose data changed.
+     * @returns This hook, for chaining.
+     */
+    onSet(handler: (entity: Entity, c: C) => void): Hook<C>;
+}
+/**
+ * Bookkeeping record produced for each component eid.
+ *
+ * Holds the constructor, component eid, and pre-computed
+ * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
+ * lifecycle handlers attached via `world.component(C)` are stored directly on
+ * the meta object.
+ */
+export declare class ComponentMeta implements Hook<ComponentInstance> {
+    /** The component class constructor this meta represents. */
+    readonly Class: ComponentType;
+    /** Component entity id assigned at registration time. */
+    readonly eid: number;
+    /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
+    readonly bitPtr: BitPtr;
+    /** Whether this component is a relationship pointing at another entity. */
+    readonly isRelationship: boolean;
+    /** Applied to entities carrying this component when this component entity is deleted. */
+    onDelete: CleanupPolicy;
+    /** Applied to entities targeting a deleted entity through this relationship. */
+    onDeleteTarget: CleanupPolicy;
+    private _usageCount;
+    constructor(Class: ComponentType, eid: number);
+    /** Number of entities currently carrying this component eid. */
+    get usageCount(): number;
+    /** @inheritdoc */
+    onAdd(handler: (entity: Entity, c: ComponentInstance) => void): ComponentMeta;
+    /** @inheritdoc */
+    onRemove(handler: (entity: Entity, c: ComponentInstance) => void): ComponentMeta;
+    /** @inheritdoc */
+    onSet(handler: (entity: Entity, c: ComponentInstance) => void): ComponentMeta;
+}

package/dist/component_meta.js

@@ -0,0 +1,65 @@
+import { BitPtr } from "./util/bitset.js";
+import { Relationship } from "./relationship.js";
+export var CleanupPolicy;
+(function (CleanupPolicy) {
+    CleanupPolicy["Throw"] = "throw";
+    CleanupPolicy["Remove"] = "remove";
+    CleanupPolicy["Delete"] = "delete";
+})(CleanupPolicy || (CleanupPolicy = {}));
+/**
+ * Bookkeeping record produced for each component eid.
+ *
+ * Holds the constructor, component eid, and pre-computed
+ * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
+ * lifecycle handlers attached via `world.component(C)` are stored directly on
+ * the meta object.
+ */
+export class ComponentMeta {
+    constructor(Class, eid) {
+        /** Applied to entities carrying this component when this component entity is deleted. */
+        this.onDelete = CleanupPolicy.Throw;
+        /** Applied to entities targeting a deleted entity through this relationship. */
+        this.onDeleteTarget = CleanupPolicy.Remove;
+        /**
+         * @internal Peer metas of components that cannot coexist with this one on
+         * the same entity. Set via {@link World.setExclusiveComponents}; `undefined`
+         * means no restriction.
+         */
+        this._exclusive = undefined;
+        this._usageCount = 0;
+        this.Class = Class;
+        this.eid = eid;
+        this.bitPtr = new BitPtr(eid);
+        this.isRelationship = Class.prototype instanceof Relationship;
+    }
+    /** Number of entities currently carrying this component eid. */
+    get usageCount() {
+        return this._usageCount;
+    }
+    /** @internal */
+    _incrementUsage() {
+        this._usageCount++;
+    }
+    /** @internal */
+    _decrementUsage() {
+        if (this._usageCount > 0) {
+            this._usageCount--;
+        }
+    }
+    /** @inheritdoc */
+    onAdd(handler) {
+        (this._onAddHandlers ?? (this._onAddHandlers = [])).unshift(handler);
+        return this;
+    }
+    /** @inheritdoc */
+    onRemove(handler) {
+        (this._onRemoveHandlers ?? (this._onRemoveHandlers = [])).unshift(handler);
+        return this;
+    }
+    /** @inheritdoc */
+    onSet(handler) {
+        (this._onSetHandlers ?? (this._onSetHandlers = [])).unshift(handler);
+        return this;
+    }
+}
+//# sourceMappingURL=component_meta.js.map

package/dist/component_meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component_meta.js","sourceRoot":"","sources":["../src/component_meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,gCAAe,CAAA;IACf,kCAAiB,CAAA;IACjB,kCAAiB,CAAA;AACnB,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AAsED;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IA+BxB,YAAY,KAAoB,EAAE,GAAW;QArB7C,yFAAyF;QAClF,aAAQ,GAAG,aAAa,CAAC,KAAK,CAAC;QACtC,gFAAgF;QACzE,mBAAc,GAAG,aAAa,CAAC,MAAM,CAAC;QAE7C;;;;WAIG;QACI,eAAU,GAAgC,SAAS,CAAC;QASnD,gBAAW,GAAG,CAAC,CAAC;QAGtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,SAAS,YAAY,YAAY,CAAC;IAChE,CAAC;IAED,gEAAgE;IAChE,IAAW,UAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,gBAAgB;IACT,eAAe;QACpB,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;IAED,gBAAgB;IACT,eAAe;QACpB,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAAuD;QAClE,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAAuD;QACrE,CAAC,IAAI,CAAC,iBAAiB,KAAtB,IAAI,CAAC,iBAAiB,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAAuD;QAClE,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/dsl.d.ts

@@ -1,9 +1,10 @@
-import { type ComponentClass, ComponentClassArray, ComponentClassOrType } from "./component.js";
-import type { Entity } from "./entity.js";
+import { type ComponentRef, type ComponentRefArray, type ComponentType } from "./component.js";
+import { Entity } from "./entity/index.js";
+import type { World } from "./world/index.js";
 /**
  * A predicate that decides whether a given entity belongs to a query.
  *
- * Pass one directly inside {@link QueryDSL} to express membership rules that
+ * Use `{ test: fn }` inside {@link QueryDSL} to express membership rules that
  * the structured operators cannot reach.
  */
 export type EntityTestFunc = (e: Entity) => boolean;
@@ -14,38 +15,40 @@ export type EntityTestFunc = (e: Entity) => boolean;
  * Operators can be nested arbitrarily:
  *
  * ```ts
- * // Position AND (Sprite OR Container):
+ * // Position and either Sprite or Container:
  * world.system("render").query({
- *   AND: [Position, { OR: [Sprite, Container] }],
+ *   all: [Position, { any: [Sprite, Container] }],
  * });
  *
- * // Parent has Player AND Container:
- * world.system("attach").query({
- *   PARENT: { AND: [Player, Container] },
- * });
- * ```
- *
  * Short forms recognized by `query` / `filter`:
- * - A registered component class or numeric type id is shorthand for `{ HAS: [C] }`.
- * - An array `[A, B]` is shorthand for `{ HAS: [A, B] }`.
- * - An {@link EntityTestFunc} is invoked directly for fully custom logic.
+ * - `true` matches all entities; `false` matches no entities.
+ * - A registered component class or numeric type id matches entities with that component.
+ * - An array `[A, B]` matches entities with all listed components.
+ * - An empty array `[]` is shorthand for `true`.
+ * - `{ test: fn, watch: refs }` invokes an arbitrary predicate, rechecked for watched refs.
  *
- * Function values are treated as component classes only when the world already
- * has registered metadata for that class. Register component classes before
- * using them in query DSL expressions.
+ * Function values are component classes. Register component classes before using
+ * them in query DSL expressions.
  */
-export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFunc | {
-    HAS: ComponentClassArray | ComponentClassOrType;
+export type QueryDSL = true | false | ComponentRefArray | ComponentRef | {
+    all: readonly QueryDSL[];
+} | {
+    any: readonly QueryDSL[];
+} | {
+    not: QueryDSL;
+} | {
+    only: ComponentRefArray | ComponentRef;
 } | {
-    HAS_ONLY: ComponentClassArray | ComponentClassOrType;
+    target: readonly [ComponentRef, QueryDSL];
 } | {
-    AND: readonly QueryDSL[];
+    source: readonly [ComponentRef, QueryDSL];
 } | {
-    OR: readonly QueryDSL[];
+    parent: QueryDSL;
 } | {
-    NOT: QueryDSL;
+    children: QueryDSL;
 } | {
-    PARENT: QueryDSL;
+    test: EntityTestFunc;
+    watch?: ComponentRefArray | ComponentRef;
 };
 /**
  * Resolve component nullability based on what was declared in `requires` (or
@@ -57,7 +60,7 @@ export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFu
  * @typeParam C - Component class being injected.
  * @typeParam R - Tuple of component classes guaranteed present.
  */
-export type MaybeRequired<C, R extends ComponentClass[]> = C extends ComponentClass ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
+export type MaybeRequired<C, R extends ComponentType[]> = C extends ComponentType ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
 /**
  * Statically extract the component classes that are **guaranteed present** on
  * every entity matched by a {@link QueryDSL} expression.
@@ -65,22 +68,31 @@ export type MaybeRequired<C, R extends ComponentClass[]> = C extends ComponentCl
  * Rules:
  * - Plain component class `C` → `[C]`
  * - Plain array `[A, B]` → `[A, B]`
- * - `{ HAS: ... }` / `{ HAS_ONLY: ... }` → recurse into the payload
- * - `{ AND: [q1, q2, ...] }` → concatenate each branch's extraction
- * - `{ OR: ... }` / `{ NOT: ... }` / `{ PARENT: ... }` → `[]` (no guarantee)
- * - `EntityTestFunc` / numeric type id → `[]` (opaque)
+ * - `true` / `false` / `[]` → `[]` (no guarantee)
+ * - `{ only: ... }` → recurse into the payload
+ * - `{ all: [q1, q2, ...] }` → concatenate each branch's extraction
+ * - `{ any: ... }` / `{ not: ... }` / `{ test: ... }` → `[]` (no guarantee)
+ * - numeric type id → `[]` (opaque)
  *
  * @typeParam Q - Query expression to analyse.
  */
-export type ExtractRequired<Q> = Q extends ComponentClass ? [Q] : Q extends readonly ComponentClass[] ? Q : Q extends {
-    HAS: infer H;
+export type ExtractRequired<Q> = Q extends ComponentType ? [Q] : Q extends readonly ComponentType[] ? Q : Q extends {
+    only: infer H;
 } ? ExtractRequired<H> : Q extends {
-    HAS_ONLY: infer H;
-} ? ExtractRequired<H> : Q extends {
-    AND: infer A extends readonly QueryDSL[];
+    all: infer A extends readonly QueryDSL[];
 } ? _ExtractAndChain<A> : [];
 type _ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [
     infer First,
     ...infer Rest extends readonly QueryDSL[]
 ] ? [...ExtractRequired<First>, ..._ExtractAndChain<Rest>] : [];
+export declare function _resolveRelationship(ref: ComponentRef, world: World): number;
+export declare function containsDownTerm(q: QueryDSL): boolean;
+/**
+ * Return a deterministic FNV-1a hash for a query DSL expression.
+ *
+ * Equivalent expressions hash identically because the DSL is simplified before
+ * hashing. Custom predicate functions are represented by process-local function
+ * identity ids. Like any 32-bit hash, collisions are theoretically possible.
+ */
+export declare function getDSLKey(q: QueryDSL, world: World): number;
 export {};