@vworlds/vecs 1.0.15 → 1.0.17

package/dist/terms/component_term.d.ts

@@ -0,0 +1,37 @@
+import type { Entity } from "../entity/index.js";
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+/**
+ * World-pinned leaf term that matches every entity carrying a specific
+ * component type.
+ *
+ * `ComponentTerm` is the component-presence index. It maintains the live set
+ * of entities that have the component identified by `componentEid`. The world
+ * routes `add`, `remove`, and `set`/`modified` commands here via the
+ * `notifyComponent*` helpers in `build.ts`.
+ *
+ * - **Membership** events (`componentAdded` / `componentRemoved`) propagate
+ *   via the standard `_add`/`_delete` path and fan out to all consumers as
+ *   enter/exit events.
+ * - **Data-only** changes (`componentChanged`) emit only a refresh hint via
+ *   `_emitRefresh`, which wakes predicate terms watching this component
+ *   without triggering a membership re-evaluation in terms that do not care
+ *   about component values.
+ */
+export declare class ComponentTerm extends Term {
+    readonly componentEid: number;
+    constructor(world: World, key: string, componentEid: number, onDestroy: (term: Term) => void);
+    /** Called by `build.ts` when the component is added to `entity`. */
+    componentAdded(entity: Entity): void;
+    /**
+     * Called by `build.ts` when the component's value changes on `entity`
+     * without a membership change.
+     *
+     * Emits a refresh hint rather than an enter/exit event so that consumers
+     * watching for data updates (predicate terms) are woken while
+     * membership-only consumers are not disturbed.
+     */
+    componentChanged(entity: Entity): void;
+    /** Called by `build.ts` when the component is removed from `entity`. */
+    componentRemoved(entity: Entity): void;
+}

package/dist/terms/component_term.js

@@ -0,0 +1,49 @@
+import { Term } from "./term.js";
+/**
+ * World-pinned leaf term that matches every entity carrying a specific
+ * component type.
+ *
+ * `ComponentTerm` is the component-presence index. It maintains the live set
+ * of entities that have the component identified by `componentEid`. The world
+ * routes `add`, `remove`, and `set`/`modified` commands here via the
+ * `notifyComponent*` helpers in `build.ts`.
+ *
+ * - **Membership** events (`componentAdded` / `componentRemoved`) propagate
+ *   via the standard `_add`/`_delete` path and fan out to all consumers as
+ *   enter/exit events.
+ * - **Data-only** changes (`componentChanged`) emit only a refresh hint via
+ *   `_emitRefresh`, which wakes predicate terms watching this component
+ *   without triggering a membership re-evaluation in terms that do not care
+ *   about component values.
+ */
+export class ComponentTerm extends Term {
+    constructor(world, key, componentEid, onDestroy) {
+        super(world, key, "component", true, onDestroy);
+        this.componentEid = componentEid;
+        this._initializeFromWorld();
+    }
+    /** Called by `build.ts` when the component is added to `entity`. */
+    componentAdded(entity) {
+        this._add(entity);
+    }
+    /**
+     * Called by `build.ts` when the component's value changes on `entity`
+     * without a membership change.
+     *
+     * Emits a refresh hint rather than an enter/exit event so that consumers
+     * watching for data updates (predicate terms) are woken while
+     * membership-only consumers are not disturbed.
+     */
+    componentChanged(entity) {
+        this._emitRefresh(entity);
+    }
+    /** Called by `build.ts` when the component is removed from `entity`. */
+    componentRemoved(entity) {
+        this._delete(entity);
+    }
+    /** @internal */
+    _matches(entity) {
+        return !entity._destroyed && entity._get(this.componentEid) !== undefined;
+    }
+}
+//# sourceMappingURL=component_term.js.map

package/dist/terms/component_term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component_term.js","sourceRoot":"","sources":["../../src/terms/component_term.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAc,SAAQ,IAAI;IACrC,YACE,KAAY,EACZ,GAAW,EACK,YAAoB,EACpC,SAA+B;QAE/B,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QAHhC,iBAAY,GAAZ,YAAY,CAAQ;QAIpC,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC;IAED,oEAAoE;IAC7D,cAAc,CAAC,MAAc;QAClC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACI,gBAAgB,CAAC,MAAc;QACpC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,wEAAwE;IACjE,gBAAgB,CAAC,MAAc;QACpC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,gBAAgB;IACN,QAAQ,CAAC,MAAc;QAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,SAAS,CAAC;IAC5E,CAAC;CACF"}

package/dist/terms/empty_term.d.ts

@@ -0,0 +1,6 @@
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+/** World-pinned leaf term that matches no entities; the materialization of `false`. */
+export declare class EmptyTerm extends Term {
+    constructor(world: World, key: string, onDestroy: (term: Term) => void);
+}

package/dist/terms/empty_term.js

@@ -0,0 +1,12 @@
+import { Term } from "./term.js";
+/** World-pinned leaf term that matches no entities; the materialization of `false`. */
+export class EmptyTerm extends Term {
+    constructor(world, key, onDestroy) {
+        super(world, key, "empty", true, onDestroy);
+    }
+    /** @internal */
+    _matches(_entity) {
+        return false;
+    }
+}
+//# sourceMappingURL=empty_term.js.map

package/dist/terms/empty_term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty_term.js","sourceRoot":"","sources":["../../src/terms/empty_term.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,uFAAuF;AACvF,MAAM,OAAO,SAAU,SAAQ,IAAI;IACjC,YAAmB,KAAY,EAAE,GAAW,EAAE,SAA+B;QAC3E,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED,gBAAgB;IACN,QAAQ,CAAC,OAAe;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/terms/index.d.ts

@@ -0,0 +1,11 @@
+export { Term, TermEventKind, type TermConsumer, type TermKind } from "./term.js";
+export { WorldTerm } from "./world_term.js";
+export { ComponentTerm } from "./component_term.js";
+export { EmptyTerm } from "./empty_term.js";
+export { AllTerm } from "./all_term.js";
+export { AnyTerm } from "./any_term.js";
+export { NotTerm } from "./not_term.js";
+export { OnlyTerm } from "./only_term.js";
+export { PredicateTerm, type MergedInfo } from "./predicate_term.js";
+export { TargetTerm } from "./target_term.js";
+export { getTerm, getCachedTerm, notifyComponentAdded, notifyComponentChanged, notifyComponentRemoved, notifyEntityCreated, notifyEntityDestroyed, } from "./build.js";

package/dist/terms/index.js

@@ -0,0 +1,12 @@
+export { Term } from "./term.js";
+export { WorldTerm } from "./world_term.js";
+export { ComponentTerm } from "./component_term.js";
+export { EmptyTerm } from "./empty_term.js";
+export { AllTerm } from "./all_term.js";
+export { AnyTerm } from "./any_term.js";
+export { NotTerm } from "./not_term.js";
+export { OnlyTerm } from "./only_term.js";
+export { PredicateTerm } from "./predicate_term.js";
+export { TargetTerm } from "./target_term.js";
+export { getTerm, getCachedTerm, notifyComponentAdded, notifyComponentChanged, notifyComponentRemoved, notifyEntityCreated, notifyEntityDestroyed, } from "./build.js";
+//# sourceMappingURL=index.js.map

package/dist/terms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terms/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmD,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,OAAO,EACP,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/terms/not_term.d.ts

@@ -0,0 +1,35 @@
+import type { Entity } from "../entity/index.js";
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+import type { QueryDSL } from "../dsl.js";
+import type { getTerm as GetTermFn } from "./build.js";
+/**
+ * Composite term that matches entities in the world but **not** in a child
+ * term.
+ *
+ * Children: `[worldTerm, child]`. The world leaf provides lifecycle
+ * (creation/destruction); the child provides the set to negate.
+ */
+export declare class NotTerm extends Term {
+    constructor(world: World, key: string, worldTerm: Term, child: Term, onDestroy: (term: Term) => void);
+    /**
+     * Build a `NotTerm` for the given child DSL.
+     *
+     * @param world - Owning world.
+     * @param childDSL - The DSL expression to negate.
+     * @param key - Canonical cache key.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static build(world: World, childDSL: QueryDSL, key: string, getTerm: typeof GetTermFn, onDestroy: (term: Term) => void): NotTerm;
+    /**
+     * No-op override: a pure negation term does not need to re-evaluate on a
+     * data or shape refresh.
+     *
+     * `NotTerm` membership flips only when the child's membership changes (a
+     * real enter/exit) or when the world emits a lifecycle event — both of
+     * which arrive via `onTermEvent`, not `onTermRefresh`. Reacting to refresh
+     * hints would cause spurious `_sync` calls with no change in result.
+     */
+    onTermRefresh(_entity: Entity): void;
+}

package/dist/terms/not_term.js

@@ -0,0 +1,47 @@
+import { Term } from "./term.js";
+/**
+ * Composite term that matches entities in the world but **not** in a child
+ * term.
+ *
+ * Children: `[worldTerm, child]`. The world leaf provides lifecycle
+ * (creation/destruction); the child provides the set to negate.
+ */
+export class NotTerm extends Term {
+    constructor(world, key, worldTerm, child, onDestroy) {
+        super(world, key, "not", false, onDestroy);
+        this._setChildren([worldTerm, child]);
+        this._initializeFromWorld();
+    }
+    /**
+     * Build a `NotTerm` for the given child DSL.
+     *
+     * @param world - Owning world.
+     * @param childDSL - The DSL expression to negate.
+     * @param key - Canonical cache key.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static build(world, childDSL, key, getTerm, onDestroy) {
+        const worldTerm = getTerm(world, true);
+        const child = getTerm(world, childDSL);
+        return new NotTerm(world, key, worldTerm, child, onDestroy);
+    }
+    /**
+     * No-op override: a pure negation term does not need to re-evaluate on a
+     * data or shape refresh.
+     *
+     * `NotTerm` membership flips only when the child's membership changes (a
+     * real enter/exit) or when the world emits a lifecycle event — both of
+     * which arrive via `onTermEvent`, not `onTermRefresh`. Reacting to refresh
+     * hints would cause spurious `_sync` calls with no change in result.
+     */
+    onTermRefresh(_entity) {
+        // Shape/data refreshes do not affect a pure negation unless the child emits
+        // a real membership event, or the world emits a lifecycle event.
+    }
+    /** @internal */
+    _matches(entity) {
+        return this._children[0].has(entity) && !this._children[1].has(entity);
+    }
+}
+//# sourceMappingURL=not_term.js.map

package/dist/terms/not_term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not_term.js","sourceRoot":"","sources":["../../src/terms/not_term.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC;;;;;;GAMG;AACH,MAAM,OAAO,OAAQ,SAAQ,IAAI;IAC/B,YACE,KAAY,EACZ,GAAW,EACX,SAAe,EACf,KAAW,EACX,SAA+B;QAE/B,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,CACjB,KAAY,EACZ,QAAkB,EAClB,GAAW,EACX,OAAyB,EACzB,SAA+B;QAE/B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvC,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;OAQG;IACa,aAAa,CAAC,OAAe;QAC3C,4EAA4E;QAC5E,iEAAiE;IACnE,CAAC;IAED,gBAAgB;IACN,QAAQ,CAAC,MAAc;QAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/terms/only_term.d.ts

@@ -0,0 +1,47 @@
+import type { Entity } from "../entity/index.js";
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+import type { getTerm as GetTermFn } from "./build.js";
+/**
+ * Composite term that matches entities carrying **exactly** the specified set
+ * of component types — no more, no fewer.
+ *
+ * Internally composed from two children:
+ * - `children[0]`: an `AllTerm` (or array shorthand) for the required
+ *   components, ensuring every listed component is present.
+ * - `children[1]`: the world leaf, ensuring the entity is live and
+ *   non-component.
+ *
+ * `OnlyTerm` additionally subscribes to the **shape channel** of the world
+ * term so it is re-evaluated whenever *any* component is added to or removed
+ * from the entity — not just when one of the listed components changes
+ * membership. This is necessary because `only` requires `entity.components.size
+ * === componentEids.length`; adding an unlisted component must evict the entity
+ * even though the `AllTerm` child has not changed.
+ */
+export declare class OnlyTerm extends Term {
+    private readonly _componentEids;
+    constructor(world: World, key: string, allTerm: Term, worldTerm: Term, _componentEids: readonly number[], onDestroy: (term: Term) => void);
+    /**
+     * Build an `OnlyTerm` for the given component eid list.
+     *
+     * @param world - Owning world.
+     * @param componentEids - Numeric component type ids that must be present and
+     *   comprise the entire component set.
+     * @param key - Canonical cache key.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static build(world: World, componentEids: readonly number[], key: string, getTerm: typeof GetTermFn, onDestroy: (term: Term) => void): OnlyTerm;
+    /**
+     * Shape-channel entry point: called directly by `WorldTerm` when the entity's
+     * component set changes.
+     *
+     * Overrides the base `onTermRefresh` to ensure a shape change always
+     * triggers a re-evaluation, regardless of which child emitted the hint.
+     * Without this override the base implementation would also call `_sync`,
+     * but the explicit override makes the intent clear and guards against future
+     * base-class changes.
+     */
+    onTermRefresh(entity: Entity): void;
+}

package/dist/terms/only_term.js

@@ -0,0 +1,79 @@
+import { Term } from "./term.js";
+import { WorldTerm } from "./world_term.js";
+/**
+ * Composite term that matches entities carrying **exactly** the specified set
+ * of component types — no more, no fewer.
+ *
+ * Internally composed from two children:
+ * - `children[0]`: an `AllTerm` (or array shorthand) for the required
+ *   components, ensuring every listed component is present.
+ * - `children[1]`: the world leaf, ensuring the entity is live and
+ *   non-component.
+ *
+ * `OnlyTerm` additionally subscribes to the **shape channel** of the world
+ * term so it is re-evaluated whenever *any* component is added to or removed
+ * from the entity — not just when one of the listed components changes
+ * membership. This is necessary because `only` requires `entity.components.size
+ * === componentEids.length`; adding an unlisted component must evict the entity
+ * even though the `AllTerm` child has not changed.
+ */
+export class OnlyTerm extends Term {
+    constructor(world, key, allTerm, worldTerm, _componentEids, onDestroy) {
+        super(world, key, "only", false, onDestroy);
+        this._componentEids = _componentEids;
+        this._setChildren([allTerm, worldTerm]);
+        if (worldTerm instanceof WorldTerm) {
+            this._addChildCleanup(worldTerm.subscribeShape(this));
+        }
+        this._initializeFromWorld();
+    }
+    /**
+     * Build an `OnlyTerm` for the given component eid list.
+     *
+     * @param world - Owning world.
+     * @param componentEids - Numeric component type ids that must be present and
+     *   comprise the entire component set.
+     * @param key - Canonical cache key.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static build(world, componentEids, key, getTerm, onDestroy) {
+        // Build the inner all-term for the component set, then the world leaf.
+        const allTerm = getTerm(world, componentEids);
+        const worldTerm = getTerm(world, true);
+        return new OnlyTerm(world, key, allTerm, worldTerm, componentEids, onDestroy);
+    }
+    /**
+     * Shape-channel entry point: called directly by `WorldTerm` when the entity's
+     * component set changes.
+     *
+     * Overrides the base `onTermRefresh` to ensure a shape change always
+     * triggers a re-evaluation, regardless of which child emitted the hint.
+     * Without this override the base implementation would also call `_sync`,
+     * but the explicit override makes the intent clear and guards against future
+     * base-class changes.
+     */
+    onTermRefresh(entity) {
+        this._sync(entity);
+    }
+    /**
+     * @internal React only to world-kind child refreshes.
+     *
+     * `OnlyTerm` cares about world-shape events (component add/remove) because
+     * the component count check in `_matches` can be violated by adding an
+     * unlisted component. Component-kind refreshes (data-only value changes) do
+     * not affect `only` membership and are intentionally ignored here.
+     */
+    _onChildRefresh(entity, child) {
+        if (child.kind === "world") {
+            this._sync(entity);
+        }
+    }
+    /** @internal */
+    _matches(entity) {
+        return (this._children[0].has(entity) &&
+            this._children[1].has(entity) &&
+            entity.components.size === this._componentEids.length);
+    }
+}
+//# sourceMappingURL=only_term.js.map

package/dist/terms/only_term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"only_term.js","sourceRoot":"","sources":["../../src/terms/only_term.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,QAAS,SAAQ,IAAI;IAChC,YACE,KAAY,EACZ,GAAW,EACX,OAAa,EACb,SAAe,EACE,cAAiC,EAClD,SAA+B;QAE/B,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAH3B,mBAAc,GAAd,cAAc,CAAmB;QAIlD,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;QACxC,IAAI,SAAS,YAAY,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,KAAK,CACjB,KAAY,EACZ,aAAgC,EAChC,GAAW,EACX,OAAyB,EACzB,SAA+B;QAE/B,uEAAuE;QACvE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,aAAyB,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;OASG;IACa,aAAa,CAAC,MAAc;QAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACgB,eAAe,CAAC,MAAc,EAAE,KAAW;QAC5D,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,gBAAgB;IACN,QAAQ,CAAC,MAAc;QAC/B,OAAO,CACL,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;YAC7B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;YAC7B,MAAM,CAAC,UAAU,CAAC,IAAI,KAAK,IAAI,CAAC,cAAc,CAAC,MAAM,CACtD,CAAC;IACJ,CAAC;CACF"}

package/dist/terms/predicate_term.d.ts

@@ -0,0 +1,80 @@
+import { type EntityTestFunc, type QueryDSL } from "../dsl.js";
+import type { Entity } from "../entity/index.js";
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+import type { getTerm as GetTermFn } from "./build.js";
+/**
+ * Analysis summary derived from a collapsed `all`/`any` subtree.
+ *
+ * Produced by `_allAnyPrecheck` in `build.ts` and consumed by
+ * {@link PredicateTerm.buildMerged} to configure the unified class without
+ * first building — and then having to tear down — the composite child terms.
+ */
+export type MergedInfo = {
+    componentEids: ReadonlySet<number>;
+    dependsOnWorld: boolean;
+    containsOnly: boolean;
+};
+/**
+ * A reactive predicate term that covers two related use-cases under one class:
+ *
+ * - **Plain predicate** (`kind === "predicate"`): wraps a user-supplied
+ *   `{ test, watch }` DSL node. The predicate is evaluated whenever a watched
+ *   component changes; membership requires the world leaf to include the entity
+ *   (i.e. it is not destroyed and not a `Component` instance).
+ *
+ * - **Merged / diamond-collapsed** (`kind === "merged"`): wraps a compiled
+ *   predicate for an `all`/`any` subtree that was detected to contain a
+ *   leaf-level diamond (the same leaf reachable via two paths). Collapsing it
+ *   into a single compiled predicate keeps the live graph a strict tree and
+ *   avoids glitch-inducing double propagation. The optional `_worldTerm` is
+ *   present only when the subtree depends on world lifecycle, and
+ *   `_usesShapeRefresh` is set when the subtree contains an `only(...)` node
+ *   (which needs a shape-channel wakeup on component add/remove).
+ *
+ * Both variants are constructed via the static factory methods
+ * {@link buildPredicate} and {@link buildMerged}; the constructor is not
+ * public.
+ */
+export declare class PredicateTerm extends Term {
+    private readonly _predicate;
+    private readonly _worldTerm;
+    private readonly _usesShapeRefresh;
+    protected constructor(world: World, key: string, kind: "predicate" | "merged", predicate: EntityTestFunc, worldTerm: Term | undefined, watchedTerms: readonly Term[], usesShapeRefresh: boolean, onDestroy: (term: Term) => void);
+    /**
+     * Build a plain predicate term for a `{ test, watch }` DSL node.
+     *
+     * Subscribes to the world leaf plus any watched component leaves so the
+     * predicate is re-evaluated whenever watched component data changes.
+     *
+     * @param world - Owning world.
+     * @param dsl - DSL node with a `test` function and optional `watch` list.
+     * @param key - Canonical cache key for this term.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static buildPredicate(world: World, dsl: {
+        test: EntityTestFunc;
+        watch?: unknown;
+    }, key: string, getTerm: typeof GetTermFn, onDestroy: (term: Term) => void): PredicateTerm;
+    /**
+     * Build a merged (diamond-collapsed) predicate term for an `all`/`any`
+     * subtree.
+     *
+     * The predicate is compiled from the full subtree DSL via `_compile` so no
+     * composite child terms need to be constructed and then torn down. The
+     * `worldTerm` leaf is included only when the subtree depends on world
+     * lifecycle; shape-refresh subscription is added only when the subtree
+     * contains an `only(...)` node.
+     *
+     * @param world - Owning world.
+     * @param dsl - The original subtree DSL to compile into a predicate.
+     * @param key - Canonical cache key for this term.
+     * @param info - Pre-computed analysis of the subtree (from `_allAnyPrecheck`).
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static buildMerged(world: World, dsl: QueryDSL, key: string, info: MergedInfo, getTerm: typeof GetTermFn, onDestroy: (term: Term) => void): PredicateTerm;
+    /** Direct shape-channel invalidation from `WorldTerm.subscribeShape`. */
+    onTermRefresh(entity: Entity): void;
+}

package/dist/terms/predicate_term.js

@@ -0,0 +1,109 @@
+import { _compile } from "../dsl.js";
+import { Term } from "./term.js";
+import { WorldTerm } from "./world_term.js";
+/**
+ * A reactive predicate term that covers two related use-cases under one class:
+ *
+ * - **Plain predicate** (`kind === "predicate"`): wraps a user-supplied
+ *   `{ test, watch }` DSL node. The predicate is evaluated whenever a watched
+ *   component changes; membership requires the world leaf to include the entity
+ *   (i.e. it is not destroyed and not a `Component` instance).
+ *
+ * - **Merged / diamond-collapsed** (`kind === "merged"`): wraps a compiled
+ *   predicate for an `all`/`any` subtree that was detected to contain a
+ *   leaf-level diamond (the same leaf reachable via two paths). Collapsing it
+ *   into a single compiled predicate keeps the live graph a strict tree and
+ *   avoids glitch-inducing double propagation. The optional `_worldTerm` is
+ *   present only when the subtree depends on world lifecycle, and
+ *   `_usesShapeRefresh` is set when the subtree contains an `only(...)` node
+ *   (which needs a shape-channel wakeup on component add/remove).
+ *
+ * Both variants are constructed via the static factory methods
+ * {@link buildPredicate} and {@link buildMerged}; the constructor is not
+ * public.
+ */
+export class PredicateTerm extends Term {
+    constructor(world, key, kind, predicate, worldTerm, watchedTerms, usesShapeRefresh, onDestroy) {
+        super(world, key, kind, false, onDestroy);
+        this._predicate = predicate;
+        this._worldTerm = worldTerm;
+        this._usesShapeRefresh = usesShapeRefresh;
+        this._setChildren(worldTerm ? [worldTerm, ...watchedTerms] : watchedTerms);
+        if (usesShapeRefresh && worldTerm instanceof WorldTerm) {
+            this._addChildCleanup(worldTerm.subscribeShape(this));
+        }
+        this._initializeFromWorld();
+    }
+    /**
+     * Build a plain predicate term for a `{ test, watch }` DSL node.
+     *
+     * Subscribes to the world leaf plus any watched component leaves so the
+     * predicate is re-evaluated whenever watched component data changes.
+     *
+     * @param world - Owning world.
+     * @param dsl - DSL node with a `test` function and optional `watch` list.
+     * @param key - Canonical cache key for this term.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static buildPredicate(world, dsl, key, getTerm, onDestroy) {
+        const watch = normalizeWatch(dsl.watch);
+        const worldTerm = getTerm(world, true);
+        const watchedTerms = watch.map((eid) => getTerm(world, eid));
+        return new PredicateTerm(world, key, "predicate", dsl.test, worldTerm, watchedTerms, false, onDestroy);
+    }
+    /**
+     * Build a merged (diamond-collapsed) predicate term for an `all`/`any`
+     * subtree.
+     *
+     * The predicate is compiled from the full subtree DSL via `_compile` so no
+     * composite child terms need to be constructed and then torn down. The
+     * `worldTerm` leaf is included only when the subtree depends on world
+     * lifecycle; shape-refresh subscription is added only when the subtree
+     * contains an `only(...)` node.
+     *
+     * @param world - Owning world.
+     * @param dsl - The original subtree DSL to compile into a predicate.
+     * @param key - Canonical cache key for this term.
+     * @param info - Pre-computed analysis of the subtree (from `_allAnyPrecheck`).
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static buildMerged(world, dsl, key, info, getTerm, onDestroy) {
+        const predicate = _compile(world, dsl);
+        const worldTerm = info.dependsOnWorld ? getTerm(world, true) : undefined;
+        const watchedTerms = [...info.componentEids].map((eid) => getTerm(world, eid));
+        return new PredicateTerm(world, key, "merged", predicate, worldTerm, watchedTerms, info.containsOnly, onDestroy);
+    }
+    /** Direct shape-channel invalidation from `WorldTerm.subscribeShape`. */
+    onTermRefresh(entity) {
+        this._sync(entity);
+    }
+    /**
+     * @internal React to a child term refresh.
+     *
+     * For the plain-predicate variant (`_usesShapeRefresh === false`) only
+     * component-kind children trigger a re-evaluation — shape changes on the
+     * world leaf are irrelevant. For the merged variant, world-kind refreshes
+     * are also relevant when the subtree contained an `only(...)` node (because
+     * `only` is sensitive to which components an entity currently has, not just
+     * whether a specific one is present).
+     */
+    _onChildRefresh(entity, child) {
+        if (child.kind === "component" || (this._usesShapeRefresh && child.kind === "world")) {
+            this._sync(entity);
+        }
+    }
+    /** @internal */
+    _matches(entity) {
+        return !entity._destroyed && (this._worldTerm?.has(entity) ?? true) && this._predicate(entity);
+    }
+}
+/** @internal Deduplicate and sort a `watch` list of component eids. */
+export function normalizeWatch(watch) {
+    if (watch === undefined) {
+        return [];
+    }
+    return [...new Set((watch instanceof Array ? watch : [watch]))].sort((a, b) => a - b);
+}
+//# sourceMappingURL=predicate_term.js.map

package/dist/terms/predicate_term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate_term.js","sourceRoot":"","sources":["../../src/terms/predicate_term.ts"],"names":[],"mappings":"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"}

package/dist/terms/target_term.d.ts

@@ -0,0 +1,43 @@
+import type { QueryDSL } from "../dsl.js";
+import type { World } from "../world/index.js";
+import { Term } from "./term.js";
+import type { getTerm as GetTermFn } from "./build.js";
+/**
+ * Composite term that matches entities whose relationship target satisfies a
+ * given inner predicate.
+ *
+ * An entity `e` matches when it carries the relationship component
+ * `_relationshipEid` **and** the target entity stored in that component
+ * satisfies `_innerTerm`.
+ *
+ * Children: `[relationshipTerm, innerTerm]`.
+ * - `children[0]` (`relationshipTerm`): the `ComponentTerm` for the
+ *   relationship eid — fires when the relationship is added/removed from `e`.
+ * - `children[1]` (`innerTerm`): the term for the inner DSL — fires when the
+ *   target entity transitions in or out.
+ *
+ * ## Non-standard event routing
+ *
+ * `TargetTerm` overrides `_onChildEvent` and `_onChildRefresh` to implement
+ * a **fan-out** strategy: when the inner term changes (the target enters or
+ * exits), all *sources* that point at that target via the relationship must be
+ * re-evaluated. This reverses the normal bottom-up signal direction. The
+ * fan-out is why `TargetTerm` subtrees are excluded from diamond collapsing —
+ * a plain compiled predicate cannot replicate this per-source walk.
+ */
+export declare class TargetTerm extends Term {
+    private readonly _relationshipEid;
+    private readonly _innerTerm;
+    constructor(world: World, key: string, _relationshipEid: number, relationshipTerm: Term, _innerTerm: Term, onDestroy: (term: Term) => void);
+    /**
+     * Build a `TargetTerm` for the given relationship eid and inner DSL.
+     *
+     * @param world - Owning world.
+     * @param relationshipEid - Numeric eid of the relationship component type.
+     * @param innerDSL - DSL expression the relationship target must satisfy.
+     * @param key - Canonical cache key.
+     * @param getTerm - Term canonicalizer / cache accessor.
+     * @param onDestroy - Called when the last consumer unsubscribes.
+     */
+    static build(world: World, relationshipEid: number, innerDSL: QueryDSL, key: string, getTerm: typeof GetTermFn, onDestroy: (term: Term) => void): TargetTerm;
+}