ecspresso 0.10.2 → 0.12.0

package/dist/plugins/state-machine.d.ts

@@ -0,0 +1,244 @@
+/**
+ * State Machine Plugin for ECSpresso
+ *
+ * Provides ECS-native finite state machines with guard-based transitions,
+ * event-driven transitions, and lifecycle hooks (onEnter, onExit, onUpdate).
+ *
+ * Each entity gets a `stateMachine` component referencing a shared definition.
+ * One system processes all state machine entities each tick.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { BaseWorld } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+/** BaseWorld narrowed to state-machine components for typed access in helpers. */
+type StateMachineWorld = BaseWorld<StateMachineComponentTypes>;
+/**
+ * Configuration for a single state in a state machine definition.
+ *
+ * @template S - Union of state name strings
+ * @template W - World interface type for hooks/guards (default: StateMachineWorld)
+ */
+export interface StateConfig<S extends string, W extends BaseWorld<StateMachineComponentTypes> = StateMachineWorld> {
+    /** Called when entering this state */
+    onEnter?(ctx: {
+        ecs: W;
+        entityId: number;
+    }): void;
+    /** Called when exiting this state */
+    onExit?(ctx: {
+        ecs: W;
+        entityId: number;
+    }): void;
+    /** Called each tick while in this state */
+    onUpdate?(ctx: {
+        ecs: W;
+        entityId: number;
+        dt: number;
+    }): void;
+    /** Guard-based transitions evaluated each tick. First passing guard wins. */
+    transitions?: ReadonlyArray<{
+        target: S;
+        guard(ctx: {
+            ecs: W;
+            entityId: number;
+        }): boolean;
+    }>;
+    /** Event-based transition map: eventName → target state or guarded transition */
+    on?: Record<string, S | {
+        target: S;
+        guard(ctx: {
+            ecs: W;
+            entityId: number;
+        }): boolean;
+    }>;
+}
+/**
+ * Immutable definition of a state machine. Shared across entities.
+ *
+ * @template S - Union of state name strings
+ */
+export interface StateMachineDefinition<S extends string> {
+    readonly id: string;
+    readonly initial: S;
+    readonly states: {
+        readonly [K in S]: StateConfig<S>;
+    };
+}
+/**
+ * Runtime state machine component stored on each entity.
+ *
+ * @template S - Union of state name strings (default: string)
+ */
+export interface StateMachine<S extends string = string> {
+    readonly definition: StateMachineDefinition<string>;
+    current: S;
+    previous: S | null;
+    stateTime: number;
+}
+/**
+ * Component types provided by the state machine plugin.
+ *
+ * @template S - Union of state name strings (default: string)
+ */
+export interface StateMachineComponentTypes<S extends string = string> {
+    stateMachine: StateMachine<S>;
+}
+/**
+ * Event published on every state transition.
+ *
+ * @template S - Union of state name strings (default: string)
+ */
+export interface StateTransitionEvent<S extends string = string> {
+    entityId: number;
+    from: S;
+    to: S;
+    definitionId: string;
+}
+/**
+ * Event types provided by the state machine plugin.
+ *
+ * @template S - Union of state name strings (default: string)
+ */
+export interface StateMachineEventTypes<S extends string = string> {
+    stateTransition: StateTransitionEvent<S>;
+}
+/**
+ * Extract the state name union from a StateMachineDefinition.
+ *
+ * @example
+ * ```typescript
+ * const enemyFSM = defineStateMachine('enemy', { initial: 'idle', states: { idle: {}, chase: {} } });
+ * type EnemyStates = StatesOf<typeof enemyFSM>; // 'idle' | 'chase'
+ * type AllStates = StatesOf<typeof enemyFSM> | StatesOf<typeof playerFSM>;
+ * ```
+ */
+export type StatesOf<D> = D extends StateMachineDefinition<infer S> ? S : never;
+/**
+ * Configuration options for the state machine plugin.
+ */
+export interface StateMachinePluginOptions<G extends string = 'stateMachine'> extends BasePluginOptions<G> {
+}
+/**
+ * Define a state machine with type-safe state names.
+ *
+ * @template S - Union of state name strings, inferred from `states` keys
+ * @param id - Unique identifier for this definition
+ * @param config - Initial state and state configurations
+ * @returns A frozen StateMachineDefinition
+ *
+ * @example
+ * ```typescript
+ * const enemyFSM = defineStateMachine('enemy', {
+ *   initial: 'idle',
+ *   states: {
+ *     idle: {
+ *       onEnter: ({ ecs, entityId }) => { ... },
+ *       transitions: [{ target: 'chase', guard: ({ ecs, entityId }) => playerNearby(ecs, entityId) }],
+ *     },
+ *     chase: {
+ *       onUpdate: ({ ecs, entityId, dt }) => { ... },
+ *       on: { playerLost: 'idle' },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineStateMachine<S extends string>(id: string, config: {
+    initial: NoInfer<S>;
+    states: Record<S, StateConfig<NoInfer<S>>>;
+}): StateMachineDefinition<S>;
+/**
+ * Create a stateMachine component from a definition.
+ *
+ * @param definition - The state machine definition to use
+ * @param options - Optional overrides (e.g., initial state)
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createStateMachine(enemyFSM),
+ *   position: { x: 100, y: 200 },
+ * });
+ * ```
+ */
+export declare function createStateMachine<S extends string>(definition: StateMachineDefinition<S>, options?: {
+    initial?: S;
+}): Pick<StateMachineComponentTypes<S>, 'stateMachine'>;
+/**
+ * Directly transition an entity's state machine to a target state.
+ * Fires onExit, onEnter hooks and publishes stateTransition event.
+ *
+ * @param ecs - ECS instance (structural typing)
+ * @param entityId - Entity to transition
+ * @param targetState - State to transition to
+ * @returns true if transition succeeded, false if entity has no stateMachine or target state doesn't exist
+ */
+export declare function transitionTo(ecs: StateMachineWorld, entityId: number, targetState: string): boolean;
+/**
+ * Send a named event to an entity's state machine.
+ * Checks the current state's `on` handlers for a matching event.
+ *
+ * @param ecs - ECS instance (structural typing)
+ * @param entityId - Entity to send event to
+ * @param eventName - Event name to match against `on` handlers
+ * @returns true if a transition occurred, false otherwise
+ */
+export declare function sendEvent(ecs: StateMachineWorld, entityId: number, eventName: string): boolean;
+/**
+ * Get the current state of an entity's state machine.
+ *
+ * @param ecs - ECS instance (structural typing)
+ * @param entityId - Entity to query
+ * @returns The current state string, or undefined if entity has no stateMachine
+ */
+export declare function getStateMachineState(ecs: StateMachineWorld, entityId: number): string | undefined;
+/**
+ * Typed helpers for the state machine plugin.
+ * Creates helpers that validate hook parameters against the world type W.
+ * Call after .build() using typeof ecs.
+ */
+export interface StateMachineHelpers<W extends BaseWorld<StateMachineComponentTypes>> {
+    defineStateMachine: <S extends string>(id: string, config: {
+        initial: NoInfer<S>;
+        states: Record<S, StateConfig<NoInfer<S>, W>>;
+    }) => StateMachineDefinition<S>;
+}
+export declare function createStateMachineHelpers<W extends BaseWorld<StateMachineComponentTypes> = StateMachineWorld>(_world?: W): StateMachineHelpers<W>;
+/**
+ * Create a state machine plugin for ECSpresso.
+ *
+ * Provides:
+ * - Lifecycle hooks (onEnter, onExit, onUpdate) per state
+ * - Guard-based automatic transitions evaluated each tick
+ * - Event-based transitions via `sendEvent()`
+ * - Direct transitions via `transitionTo()`
+ * - stateTransition events published on every transition
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createStateMachinePlugin())
+ *   .build();
+ *
+ * const fsm = defineStateMachine('enemy', {
+ *   initial: 'idle',
+ *   states: {
+ *     idle: {
+ *       transitions: [{ target: 'chase', guard: ({ ecs, entityId }) => playerNearby(ecs, entityId) }],
+ *     },
+ *     chase: {
+ *       onUpdate: ({ ecs, entityId, dt }) => moveTowardPlayer(ecs, entityId, dt),
+ *       on: { playerLost: 'idle' },
+ *     },
+ *   },
+ * });
+ *
+ * ecs.spawn({
+ *   ...createStateMachine(fsm),
+ *   position: { x: 0, y: 0 },
+ * });
+ * ```
+ */
+export declare function createStateMachinePlugin<S extends string = string, G extends string = 'stateMachine'>(options?: StateMachinePluginOptions<G>): Plugin<WorldConfigFrom<StateMachineComponentTypes<S>, StateMachineEventTypes<S>>, EmptyConfig, 'state-machine-update', G>;
+export {};

package/dist/plugins/timers.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Timer Plugin for ECSpresso
+ *
+ * Provides ECS-native timers following the "data, not callbacks" philosophy.
+ * Timers are components processed each frame, automatically cleaned up when entities are removed.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+/**
+ * Data structure passed to onComplete callbacks when a timer completes.
+ *
+ * @example
+ * ```typescript
+ * createTimer(1.5, {
+ *   onComplete: (data) => {
+ *     console.log(`Timer on entity ${data.entityId} finished after ${data.elapsed}s`);
+ *   }
+ * });
+ * ```
+ */
+export interface TimerEventData {
+    /** The entity ID that the timer belongs to */
+    entityId: number;
+    /** The timer's configured duration in seconds */
+    duration: number;
+    /** The actual elapsed time (may exceed duration slightly) */
+    elapsed: number;
+}
+/**
+ * Timer component data structure.
+ * Use `justFinished` to detect timer completion in your systems.
+ */
+export interface Timer {
+    /** Time accumulated so far (seconds) */
+    elapsed: number;
+    /** Target duration (seconds) */
+    duration: number;
+    /** Whether timer repeats after completion */
+    repeat: boolean;
+    /** Whether timer is currently running */
+    active: boolean;
+    /** True for one frame after timer completes */
+    justFinished: boolean;
+    /** Optional callback invoked when timer completes */
+    onComplete?: (data: TimerEventData) => void;
+}
+/**
+ * Component types provided by the timer plugin.
+ * Included automatically via `.withPlugin(createTimerPlugin())`.
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createTimerPlugin())
+ *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
+ *   .build();
+ * ```
+ */
+export interface TimerComponentTypes {
+    timer: Timer;
+}
+/**
+ * Configuration options for the timer plugin.
+ */
+export interface TimerPluginOptions<G extends string = 'timers'> extends BasePluginOptions<G> {
+}
+/**
+ * Options for timer creation
+ */
+export interface TimerOptions {
+    /** Callback invoked when timer completes */
+    onComplete?: (data: TimerEventData) => void;
+}
+/**
+ * Create a one-shot timer that fires once after the specified duration.
+ *
+ * @param duration Duration in seconds until the timer completes
+ * @param options Optional configuration including onComplete callback
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * // Timer without callback
+ * ecs.spawn({
+ *   ...createTimer(2),
+ *   explosion: true,
+ * });
+ *
+ * // Timer with onComplete callback
+ * ecs.spawn({
+ *   ...createTimer(1.5, { onComplete: (data) => console.log('done', data.entityId) }),
+ * });
+ * ```
+ */
+export declare function createTimer(duration: number, options?: TimerOptions): Pick<TimerComponentTypes, 'timer'>;
+/**
+ * Create a repeating timer that fires every `duration` seconds.
+ *
+ * @param duration Duration in seconds between each timer completion
+ * @param options Optional configuration including onComplete callback
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * // Timer without callback
+ * ecs.spawn({
+ *   ...createRepeatingTimer(5),
+ *   spawner: true,
+ * });
+ *
+ * // Repeating timer with onComplete callback
+ * ecs.spawn({
+ *   ...createRepeatingTimer(3, { onComplete: (data) => console.log('cycle', data.elapsed) }),
+ * });
+ * ```
+ */
+export declare function createRepeatingTimer(duration: number, options?: TimerOptions): Pick<TimerComponentTypes, 'timer'>;
+/**
+ * Create a timer plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - Timer update system that processes all timer components each frame
+ * - `justFinished` flag pattern for one-frame completion detection
+ * - Automatic cleanup when entities are removed
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso
+ *   .create<Components, Events, Resources>()
+ *   .withPlugin(createTimerPlugin())
+ *   .build();
+ *
+ * // Spawn entity with timer
+ * ecs.spawn({
+ *   ...createRepeatingTimer(5),
+ *   spawner: true,
+ * });
+ *
+ * // React to timer completion in a system
+ * ecs.addSystem('spawn-on-timer')
+ *   .addQuery('spawners', { with: ['timer', 'spawner'] })
+ *   .setProcess((queries, _dt, ecs) => {
+ *     for (const { components } of queries.spawners) {
+ *       if (components.timer.justFinished) {
+ *         ecs.spawn({ enemy: true });
+ *       }
+ *     }
+ *   });
+ * ```
+ */
+export declare function createTimerPlugin<G extends string = 'timers'>(options?: TimerPluginOptions<G>): Plugin<WorldConfigFrom<TimerComponentTypes>, EmptyConfig, 'timer-update', G>;

package/dist/{bundles/utils → plugins}/transform.d.ts

@@ -1,13 +1,13 @@
 /**
- * Transform Bundle for ECSpresso
+ * Transform Plugin for ECSpresso
  *
  * Provides hierarchical transform propagation following Bevy's Transform/GlobalTransform pattern.
  * LocalTransform is modified by user code; WorldTransform is computed automatically.
  *
  * @see https://docs.rs/bevy/latest/bevy/transform/components/struct.GlobalTransform.html
  */
-import { Bundle } from 'ecspresso';
-import type { SystemPhase } from 'ecspresso';
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
 /**
  * Local transform relative to parent (or world if no parent).
  * This is the transform you modify directly.
@@ -31,15 +31,15 @@ export interface WorldTransform {
     scaleY: number;
 }
 /**
- * Component types provided by the transform bundle.
- * Extend your component types with this interface.
+ * Component types provided by the transform plugin.
+ * Included automatically via `.withPlugin(createTransformPlugin())`.
  *
  * @example
  * ```typescript
- * interface GameComponents extends TransformComponentTypes {
- *   sprite: Sprite;
- *   velocity: { x: number; y: number };
- * }
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createTransformPlugin())
+ *   .withComponentTypes<{ sprite: Sprite; velocity: { x: number; y: number } }>()
+ *   .build();
  * ```
  */
 export interface TransformComponentTypes {
@@ -47,15 +47,14 @@ export interface TransformComponentTypes {
     worldTransform: WorldTransform;
 }
 /**
- * Configuration options for the transform bundle.
+ * WorldConfig representing the transform plugin's provided components.
+ * Used as the `Requires` type parameter by plugins that depend on transform.
+ */
+export type TransformWorldConfig = WorldConfigFrom<TransformComponentTypes>;
+/**
+ * Configuration options for the transform plugin.
  */
-export interface TransformBundleOptions {
-    /** System group name (default: 'transform') */
-    systemGroup?: string;
-    /** Priority for transform propagation (default: 500, runs after physics/movement) */
-    priority?: number;
-    /** Execution phase (default: 'postUpdate') */
-    phase?: SystemPhase;
+export interface TransformPluginOptions<G extends string = 'transform'> extends BasePluginOptions<G> {
 }
 /**
  * Default local transform values.
@@ -126,9 +125,9 @@ export interface TransformOptions {
  */
 export declare function createTransform(x: number, y: number, options?: TransformOptions): TransformComponentTypes;
 /**
- * Create a transform bundle for ECSpresso.
+ * Create a transform plugin for ECSpresso.
  *
- * This bundle provides:
+ * This plugin provides:
  * - Transform propagation system that computes world transforms from local transforms
  * - Parent-first traversal ensures parents are processed before children
  * - Supports full transform hierarchy (position, rotation, scale)
@@ -137,8 +136,8 @@ export declare function createTransform(x: number, y: number, options?: Transfor
  * ```typescript
  * const ecs = ECSpresso
  *   .create<Components, Events, Resources>()
- *   .withBundle(createTransformBundle())
- *   .withBundle(createMovementBundle())
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createPhysics2DPlugin())
  *   .build();
  *
  * // Spawn entity with transform
@@ -148,4 +147,4 @@ export declare function createTransform(x: number, y: number, options?: Transfor
  * });
  * ```
  */
-export declare function createTransformBundle(options?: TransformBundleOptions): Bundle<TransformComponentTypes, {}, {}>;
+export declare function createTransformPlugin<G extends string = 'transform'>(options?: TransformPluginOptions<G>): Plugin<WorldConfigFrom<TransformComponentTypes>, EmptyConfig, 'transform-propagation', G>;

package/dist/plugins/tween.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Tween Plugin for ECSpresso
+ *
+ * Declarative property animation within the ECS. Tween any numeric component
+ * field over time with standard easing functions, sequences, and completion events.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { ComponentsOfWorld, AnyECSpresso } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+import { type EasingFn } from '../utils/easing';
+/**
+ * Data structure published when a tween completes.
+ * Use this type when defining tween completion events in your EventTypes interface.
+ */
+export interface TweenEventData {
+    /** The entity ID the tween belongs to */
+    entityId: number;
+    /** Number of steps in the tween */
+    stepCount: number;
+}
+export interface TweenTarget {
+    /** Component name on the entity */
+    component: string;
+    /** Pre-split field path (e.g., ['position', 'x']) */
+    path: readonly string[];
+    /** Starting value. null = resolve from current value on first tick */
+    from: number | null;
+    /** Target value */
+    to: number;
+}
+export interface TweenStep {
+    targets: TweenTarget[];
+    duration: number;
+    easing: EasingFn;
+}
+export interface Tween {
+    steps: TweenStep[];
+    currentStep: number;
+    elapsed: number;
+    loop: LoopMode;
+    totalLoops: number;
+    completedLoops: number;
+    direction: 1 | -1;
+    state: 'pending' | 'active' | 'complete';
+    onComplete?: (data: TweenEventData) => void;
+    justFinished: boolean;
+}
+export type LoopMode = 'once' | 'loop' | 'yoyo';
+/**
+ * Component types provided by the tween plugin.
+ */
+export interface TweenComponentTypes {
+    tween: Tween;
+}
+export interface TweenPluginOptions<G extends string = 'tweens'> extends BasePluginOptions<G> {
+}
+export interface TweenOptions {
+    /** Explicit starting value (default: captures current value on first tick) */
+    from?: number;
+    /** Easing function (default: linear) */
+    easing?: EasingFn;
+    /** Loop mode (default: 'once') */
+    loop?: LoopMode;
+    /** Number of loops. -1 = infinite (default: 1) */
+    loops?: number;
+    /** Callback invoked when tween completes */
+    onComplete?: (data: TweenEventData) => void;
+}
+/**
+ * Create a single-target tween component.
+ *
+ * @param component Component name on the entity
+ * @param field Field path (dot-separated for nested, e.g. 'position.x')
+ * @param to Target value
+ * @param duration Duration in seconds
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createTween(component: string, field: string, to: number, duration: number, options?: TweenOptions): Pick<TweenComponentTypes, 'tween'>;
+export interface TweenSequenceStepInput {
+    targets: ReadonlyArray<{
+        component: string;
+        field: string;
+        to: number;
+        from?: number;
+    }>;
+    duration: number;
+    easing?: EasingFn;
+}
+export interface TweenSequenceOptions {
+    /** Loop mode (default: 'once') */
+    loop?: LoopMode;
+    /** Number of loops. -1 = infinite (default: 1) */
+    loops?: number;
+    /** Callback invoked when tween completes */
+    onComplete?: (data: TweenEventData) => void;
+}
+/**
+ * Create a multi-step tween sequence. Each step can have parallel targets.
+ *
+ * @param steps Array of step definitions
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createTweenSequence(steps: ReadonlyArray<TweenSequenceStepInput>, options?: TweenSequenceOptions): Pick<TweenComponentTypes, 'tween'>;
+/**
+ * Recursively produce a union of dot-separated paths that resolve to `number`
+ * within type T. Depth-limited to 4 levels to prevent TS recursion errors.
+ *
+ * @example
+ * NumericPaths<{ x: number; y: number }> // 'x' | 'y'
+ * NumericPaths<{ position: { x: number }; rotation: number }> // 'position.x' | 'rotation'
+ */
+export type NumericPaths<T, Depth extends readonly unknown[] = []> = Depth['length'] extends 4 ? never : T extends readonly unknown[] ? never : T extends Record<string, unknown> ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends number ? K : NonNullable<T[K]> extends readonly unknown[] ? never : NonNullable<T[K]> extends Record<string, unknown> ? `${K}.${NumericPaths<NonNullable<T[K]>, [...Depth, unknown]>}` : never;
+}[keyof T & string] : never;
+/**
+ * Discriminated union over component names: each variant constrains `field`
+ * to the numeric paths of that component. TS narrows inline object literals
+ * by `component` discriminant — zero runtime overhead.
+ */
+export type TypedTweenTargetInput<C extends Record<string, any>> = {
+    [K in keyof C & string]: {
+        component: K;
+        field: NumericPaths<C[K]>;
+        to: number;
+        from?: number;
+    };
+}[keyof C & string];
+export interface TypedTweenSequenceStepInput<C extends Record<string, any>> {
+    targets: ReadonlyArray<TypedTweenTargetInput<C>>;
+    duration: number;
+    easing?: EasingFn;
+}
+export interface TweenHelpers<W extends AnyECSpresso> {
+    createTween: <K extends keyof ComponentsOfWorld<W> & string>(component: K, field: NumericPaths<ComponentsOfWorld<W>[K]>, to: number, duration: number, options?: {
+        from?: number;
+        easing?: EasingFn;
+        loop?: LoopMode;
+        loops?: number;
+        onComplete?: (data: TweenEventData) => void;
+    }) => Pick<TweenComponentTypes, 'tween'>;
+    createTweenSequence: (steps: ReadonlyArray<TypedTweenSequenceStepInput<ComponentsOfWorld<W>>>, options?: {
+        loop?: LoopMode;
+        loops?: number;
+        onComplete?: (data: TweenEventData) => void;
+    }) => Pick<TweenComponentTypes, 'tween'>;
+}
+export declare function createTweenHelpers<W extends AnyECSpresso>(_world?: W): TweenHelpers<W>;
+/**
+ * Create a tween plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - Tween system that processes all tween components each frame
+ * - Support for single-field, multi-target, and multi-step sequences
+ * - 31 standard easing functions
+ * - Loop modes: once, loop, yoyo
+ * - `justFinished` flag for one-frame completion detection
+ * - `onComplete` callback on completion
+ * - Change detection via markChanged
+ */
+export declare function createTweenPlugin<G extends string = 'tweens'>(options?: TweenPluginOptions<G>): Plugin<WorldConfigFrom<TweenComponentTypes>, EmptyConfig, 'tween-update', G>;

package/dist/reactive-query-manager.d.ts

@@ -20,7 +20,7 @@ export interface ReactiveQueryDefinition<ComponentTypes extends Record<string, a
 /**
  * Manages reactive queries that trigger callbacks when entities enter/exit query matches
  */
-export default class ReactiveQueryManager<ComponentTypes extends Record<string, any>> {
+export default class ReactiveQueryManager<ComponentTypes extends Record<string, any>, QueryNames extends string = string> {
     private queries;
     private entityManager;
     /** Whether any registered query uses parentHas */
@@ -35,17 +35,22 @@ export default class ReactiveQueryManager<ComponentTypes extends Record<string,
      * @param name Unique name for the query
      * @param definition Query definition with callbacks
      */
-    addQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never>(name: string, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>): void;
+    addQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never>(name: QueryNames, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>): void;
     /**
      * Remove a reactive query
      * @param name Name of the query to remove
      * @returns true if the query existed and was removed
      */
-    removeQuery(name: string): boolean;
+    removeQuery(name: QueryNames): boolean;
     /**
      * Check if an entity matches a query definition
      */
     private entityMatchesQuery;
+    /**
+     * Apply enter/exit transitions for a single query against an entity.
+     * Fires onEnter when entity starts matching, onExit when it stops.
+     */
+    private _applyQueryTransition;
     /**
      * Called when a component is added to an entity
      * Checks all queries for potential enter/exit events
@@ -66,6 +71,12 @@ export default class ReactiveQueryManager<ComponentTypes extends Record<string,
      * Fires enter/exit callbacks as appropriate based on current state vs tracked state
      */
     recheckEntity(entity: Entity<ComponentTypes>): void;
+    /**
+     * Recheck an entity and its children against all queries.
+     * Used after component mutations to handle both the entity's own queries
+     * and parentHas queries on its children.
+     */
+    recheckEntityAndChildren(entity: Entity<ComponentTypes>): void;
     /**
      * Recheck all children of a parent entity against parentHas queries.
      * Called when a component is added/removed from a parent entity.