ecspresso 0.11.0 → 0.12.0

package/dist/{bundles → plugins}/renderers/renderer2D.d.ts

@@ -1,19 +1,20 @@
 /**
- * 2D Renderer Bundle for ECSpresso
+ * 2D Renderer Plugin for ECSpresso
  *
- * An opt-in PixiJS-based 2D rendering bundle that automates scene graph wiring.
- * Import from 'ecspresso/bundles/renderers/renderer2D'
+ * An opt-in PixiJS-based 2D rendering plugin that automates scene graph wiring.
+ * Import from 'ecspresso/plugins/renderers/renderer2D'
  *
- * This bundle includes transform propagation automatically.
+ * This plugin includes transform propagation automatically.
  */
 import type { Application, ApplicationOptions, Container, Sprite, Graphics } from 'pixi.js';
-import { Bundle } from 'ecspresso';
-import { type LocalTransform, type WorldTransform, type TransformComponentTypes, type TransformBundleOptions } from 'ecspresso/bundles/transform';
-import { type BoundsRect } from 'ecspresso/bundles/bounds';
-import type { CameraResourceTypes } from 'ecspresso/bundles/camera';
+import { type Plugin } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../../type-utils';
+import { type LocalTransform, type WorldTransform, type TransformComponentTypes, type TransformPluginOptions } from 'ecspresso/plugins/transform';
+import { type BoundsRect } from 'ecspresso/plugins/bounds';
+import type { CameraResourceTypes } from 'ecspresso/plugins/camera';
 export type { LocalTransform, WorldTransform, TransformComponentTypes };
 export type { BoundsRect };
-export { createTransform, createLocalTransform, createWorldTransform, DEFAULT_LOCAL_TRANSFORM, DEFAULT_WORLD_TRANSFORM } from 'ecspresso/bundles/transform';
+export { createTransform, createLocalTransform, createWorldTransform, DEFAULT_LOCAL_TRANSFORM, DEFAULT_WORLD_TRANSFORM } from 'ecspresso/plugins/transform';
 /**
  * Visibility and alpha component
  */
@@ -22,13 +23,13 @@ export interface Visible {
     alpha?: number;
 }
 /**
- * Aggregate component types for the 2D renderer bundle.
- * Included automatically via `.withBundle(createRenderer2DBundle({ ... }))`.
+ * Aggregate component types for the 2D renderer plugin.
+ * Included automatically via `.withPlugin(createRenderer2DPlugin({ ... }))`.
  *
  * @example
  * ```typescript
  * const ecs = ECSpresso.create()
- *   .withBundle(createRenderer2DBundle({ ... }))
+ *   .withPlugin(createRenderer2DPlugin({ ... }))
  *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
  *   .build();
  * ```
@@ -42,7 +43,7 @@ export interface Renderer2DComponentTypes extends TransformComponentTypes {
     renderLayer: string;
 }
 /**
- * Events emitted by the 2D renderer bundle
+ * Events emitted by the 2D renderer plugin
  */
 export interface Renderer2DEventTypes {
     hierarchyChanged: {
@@ -52,7 +53,7 @@ export interface Renderer2DEventTypes {
     };
 }
 /**
- * Resources provided by the 2D renderer bundle
+ * Resources provided by the 2D renderer plugin
  */
 export interface Renderer2DResourceTypes {
     pixiApp: Application;
@@ -82,21 +83,21 @@ export interface ViewportScaleResourceTypes {
 /**
  * Common options shared between both initialization modes
  */
-interface Renderer2DBundleCommonOptions<G extends string = 'renderer2d'> {
+interface Renderer2DPluginCommonOptions<G extends string = 'renderer2d'> {
     /** Optional custom root container (defaults to app.stage) */
     rootContainer?: Container;
     /** System group name (default: 'renderer2d') */
     systemGroup?: G;
     /** Priority for render sync system (default: 500) */
     renderSyncPriority?: number;
-    /** Options for the included transform bundle */
-    transform?: TransformBundleOptions;
+    /** Options for the included transform plugin */
+    transform?: TransformPluginOptions;
     /** When true, wires up pixiApp.ticker to drive ecs.update() automatically (default: true) */
     startLoop?: boolean;
     /** Ordered render layer names (back-to-front). Entities with a renderLayer component are placed in the corresponding container. */
     renderLayers?: string[];
     /** Automatically apply cameraState resource to rootContainer each frame.
-     *  Requires the camera bundle to be installed. (default: false) */
+     *  Requires the camera plugin to be installed. (default: false) */
     camera?: boolean;
     /** Enforce a logical design resolution with automatic aspect-ratio-aware scaling.
      *  When set, systems work in design-resolution coordinate space. */
@@ -105,37 +106,37 @@ interface Renderer2DBundleCommonOptions<G extends string = 'renderer2d'> {
 /**
  * Options when providing a pre-initialized PixiJS Application
  */
-export interface Renderer2DBundleAppOptions<G extends string = 'renderer2d'> extends Renderer2DBundleCommonOptions<G> {
+export interface Renderer2DPluginAppOptions<G extends string = 'renderer2d'> extends Renderer2DPluginCommonOptions<G> {
     /** The PixiJS Application instance (already initialized) */
     app: Application;
     init?: never;
     container?: never;
 }
 /**
- * Options when letting the bundle create and manage the PixiJS Application
+ * Options when letting the plugin create and manage the PixiJS Application
  */
-export interface Renderer2DBundleManagedOptions<G extends string = 'renderer2d'> extends Renderer2DBundleCommonOptions<G> {
+export interface Renderer2DPluginManagedOptions<G extends string = 'renderer2d'> extends Renderer2DPluginCommonOptions<G> {
     app?: never;
-    /** PixiJS ApplicationOptions - bundle will create and initialize the Application */
+    /** PixiJS ApplicationOptions - plugin will create and initialize the Application */
     init: Partial<ApplicationOptions>;
     /** Container element to append the canvas to, or CSS selector string */
     container?: HTMLElement | string;
 }
 /**
- * Configuration options for the 2D renderer bundle.
+ * Configuration options for the 2D renderer plugin.
  *
  * Supports two modes:
  * 1. **Pre-initialized**: Pass an already-initialized Application via `app`
- * 2. **Managed**: Pass `init` options and the bundle creates the Application during `ecs.initialize()`
+ * 2. **Managed**: Pass `init` options and the plugin creates the Application during `ecs.initialize()`
  *
- * This bundle includes transform propagation automatically - no need to add createTransformBundle() separately.
+ * This plugin includes transform propagation automatically - no need to add createTransformPlugin() separately.
  *
  * @example Pre-initialized mode (full control)
  * ```typescript
  * const app = new Application();
  * await app.init({ resizeTo: window });
  * const ecs = ECSpresso.create()
- *   .withBundle(createRenderer2DBundle({ app }))
+ *   .withPlugin(createRenderer2DPlugin({ app }))
  *   .withComponentTypes<{ player: true }>()
  *   .build();
  * ```
@@ -143,7 +144,7 @@ export interface Renderer2DBundleManagedOptions<G extends string = 'renderer2d'>
  * @example Managed mode (convenience)
  * ```typescript
  * const ecs = ECSpresso.create()
- *   .withBundle(createRenderer2DBundle({
+ *   .withPlugin(createRenderer2DPlugin({
  *     init: { background: '#1099bb', resizeTo: window },
  *     container: document.body,
  *   }))
@@ -152,7 +153,7 @@ export interface Renderer2DBundleManagedOptions<G extends string = 'renderer2d'>
  * await ecs.initialize(); // Application created here
  * ```
  */
-export type Renderer2DBundleOptions<G extends string = 'renderer2d'> = Renderer2DBundleAppOptions<G> | Renderer2DBundleManagedOptions<G>;
+export type Renderer2DPluginOptions<G extends string = 'renderer2d'> = Renderer2DPluginAppOptions<G> | Renderer2DPluginManagedOptions<G>;
 interface PositionOption {
     x?: number;
     y?: number;
@@ -218,9 +219,9 @@ export declare function physicalToLogical(physicalX: number, physicalY: number,
     y: number;
 };
 /**
- * Create a 2D rendering bundle for ECSpresso.
+ * Create a 2D rendering plugin for ECSpresso.
  *
- * This bundle provides:
+ * This plugin provides:
  * - Transform propagation (localTransform -> worldTransform)
  * - Render sync system (updates PixiJS objects from ECS components)
  * - Scene graph management (mirrors ECS hierarchy in PixiJS scene graph)
@@ -231,14 +232,14 @@ export declare function physicalToLogical(physicalX: number, physicalY: number,
  * await app.init({ resizeTo: window });
  *
  * const ecs = ECSpresso.create<GameComponents, {}, {}>()
- *   .withBundle(createRenderer2DBundle({ app }))
+ *   .withPlugin(createRenderer2DPlugin({ app }))
  *   .build();
  * ```
  *
  * @example Managed mode
  * ```typescript
  * const ecs = ECSpresso.create<GameComponents, {}, {}>()
- *   .withBundle(createRenderer2DBundle({
+ *   .withPlugin(createRenderer2DPlugin({
  *     init: { background: '#1099bb', resizeTo: window },
  *     container: document.body,
  *   }))
@@ -248,14 +249,14 @@ export declare function physicalToLogical(physicalX: number, physicalY: number,
  */
 type Renderer2DLabels = 'renderer2d-sync' | 'renderer2d-scene-graph' | 'renderer2d-camera-sync' | 'transform-propagation';
 type Renderer2DReactiveQueryNames = 'renderer2d-sprites' | 'renderer2d-graphics' | 'renderer2d-containers';
-export declare function createRenderer2DBundle<G extends string = 'renderer2d'>(options: Renderer2DBundleOptions<G> & {
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
     screenScale: ScreenScaleOptions;
     camera: true;
-}): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes & CameraResourceTypes, {}, {}, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
-export declare function createRenderer2DBundle<G extends string = 'renderer2d'>(options: Renderer2DBundleOptions<G> & {
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes & CameraResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
     screenScale: ScreenScaleOptions;
-}): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes, {}, {}, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
-export declare function createRenderer2DBundle<G extends string = 'renderer2d'>(options: Renderer2DBundleOptions<G> & {
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
     camera: true;
-}): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & CameraResourceTypes, {}, {}, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
-export declare function createRenderer2DBundle<G extends string = 'renderer2d'>(options: Renderer2DBundleOptions<G>): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes, {}, {}, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & CameraResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G>): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;

package/dist/{bundles → plugins}/spatial-index.d.ts

@@ -1,15 +1,16 @@
 /**
- * Spatial Index Bundle for ECSpresso
+ * Spatial Index Plugin for ECSpresso
  *
  * Provides a uniform-grid spatial hash for broadphase collision detection
  * and proximity queries. Replaces O(n²) brute-force with O(n·d) where
  * d = local density.
  *
  * Standalone usage: queryRect / queryRadius for proximity queries.
- * Automatic acceleration: collision and physics2D bundles detect the
+ * Automatic acceleration: collision and physics2D plugins detect the
  * spatialIndex resource at runtime and use it for broadphase when present.
  */
-import { Bundle } from 'ecspresso';
+import { type Plugin } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
 import type { TransformComponentTypes } from './transform';
 import type { CollisionComponentTypes } from './collision';
 import { type SpatialIndex } from '../utils/spatial-hash';
@@ -19,7 +20,7 @@ export interface SpatialIndexResourceTypes {
 type SpatialIndexComponentTypes = TransformComponentTypes & Pick<CollisionComponentTypes<string>, 'aabbCollider' | 'circleCollider'>;
 export type SpatialIndexPhase = 'fixedUpdate' | 'postUpdate';
 type SpatialIndexLabel = `spatial-index-rebuild-${SpatialIndexPhase}`;
-export interface SpatialIndexBundleOptions<G extends string = 'spatialIndex'> {
+export interface SpatialIndexPluginOptions<G extends string = 'spatialIndex'> {
     /** Cell size for the spatial hash grid (default: 64) */
     cellSize?: number;
     /** System group name (default: 'spatialIndex') */
@@ -30,10 +31,10 @@ export interface SpatialIndexBundleOptions<G extends string = 'spatialIndex'> {
     phases?: ReadonlyArray<SpatialIndexPhase>;
 }
 /**
- * Create a spatial index bundle for ECSpresso.
+ * Create a spatial index plugin for ECSpresso.
  *
  * Provides a uniform-grid spatial hash that accelerates collision detection.
- * When installed alongside the collision or physics2D bundles, they
+ * When installed alongside the collision or physics2D plugins, they
  * automatically use the spatial index for broadphase instead of O(n²)
  * brute-force.
  *
@@ -43,9 +44,9 @@ export interface SpatialIndexBundleOptions<G extends string = 'spatialIndex'> {
  * @example
  * ```typescript
  * const ecs = ECSpresso.create()
- *   .withBundle(createTransformBundle())
- *   .withBundle(createCollisionBundle({ layers }))
- *   .withBundle(createSpatialIndexBundle({ cellSize: 128 }))
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createCollisionPlugin({ layers }))
+ *   .withPlugin(createSpatialIndexPlugin({ cellSize: 128 }))
  *   .build();
  *
  * // Proximity query in a system:
@@ -53,5 +54,5 @@ export interface SpatialIndexBundleOptions<G extends string = 'spatialIndex'> {
  * const nearby = si.queryRadius(playerX, playerY, 200);
  * ```
  */
-export declare function createSpatialIndexBundle<G extends string = 'spatialIndex'>(options?: SpatialIndexBundleOptions<G>): Bundle<SpatialIndexComponentTypes, {}, SpatialIndexResourceTypes, {}, {}, SpatialIndexLabel, G>;
+export declare function createSpatialIndexPlugin<G extends string = 'spatialIndex'>(options?: SpatialIndexPluginOptions<G>): Plugin<WorldConfigFrom<SpatialIndexComponentTypes, {}, SpatialIndexResourceTypes>, EmptyConfig, SpatialIndexLabel, G>;
 export {};

package/dist/plugins/sprite-animation.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Sprite Animation Plugin for ECSpresso
+ *
+ * ECS-native frame-based sprite animation. Advances through spritesheet frames,
+ * handles loop modes (once, loop, pingPong), publishes completion events, and
+ * syncs the current frame's texture to the PixiJS Sprite via structural access.
+ *
+ * Renderer2D is a required dependency — the `sprite` component comes from that plugin.
+ * This plugin declares only `spriteAnimation` as its component type.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { BaseWorld } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+/** BaseWorld narrowed to sprite-animation components for typed access in helpers. */
+type SpriteAnimationWorld = BaseWorld<SpriteAnimationComponentTypes>;
+export type AnimationLoopMode = 'once' | 'loop' | 'pingPong';
+/**
+ * A single animation clip: an ordered sequence of texture frames with timing.
+ * Immutable and shared across entities.
+ */
+export interface SpriteAnimationClip {
+    readonly frames: readonly unknown[];
+    readonly frameDuration: number;
+    readonly frameDurations: readonly number[] | null;
+    readonly loop: AnimationLoopMode;
+}
+/**
+ * Input format for defining a clip. Accepts either uniform or per-frame timing.
+ */
+export interface SpriteAnimationClipInput {
+    /** Array of PixiJS Texture objects */
+    frames: readonly unknown[];
+    /** Uniform seconds-per-frame (used when frameDurations is not provided) */
+    frameDuration?: number;
+    /** Per-frame durations in seconds (overrides frameDuration) */
+    frameDurations?: readonly number[];
+    /** Loop mode (default: 'loop') */
+    loop?: AnimationLoopMode;
+}
+/**
+ * A named collection of animation clips. Immutable and shared across entities.
+ * Parameterized by A (animation name union) for compile-time validation.
+ */
+export interface SpriteAnimationSet<A extends string = string> {
+    readonly id: string;
+    readonly clips: {
+        readonly [K in A]: SpriteAnimationClip;
+    };
+    readonly defaultClip: A;
+}
+/**
+ * Per-entity runtime animation state.
+ */
+export interface SpriteAnimation<A extends string = string> {
+    readonly set: SpriteAnimationSet<A>;
+    current: A;
+    currentFrame: number;
+    elapsed: number;
+    playing: boolean;
+    speed: number;
+    direction: 1 | -1;
+    totalLoops: number;
+    completedLoops: number;
+    justFinished: boolean;
+    onComplete?: (data: SpriteAnimationEventData) => void;
+}
+/**
+ * Component types provided by the sprite animation plugin.
+ */
+export interface SpriteAnimationComponentTypes<A extends string = string> {
+    spriteAnimation: SpriteAnimation<A>;
+}
+/**
+ * Data published when an animation completes.
+ */
+export interface SpriteAnimationEventData {
+    entityId: number;
+    animation: string;
+}
+export interface SpriteAnimationPluginOptions<G extends string = 'spriteAnimation'> extends BasePluginOptions<G> {
+}
+/**
+ * Define a single-clip animation set named 'default'.
+ * For simple use cases like spinning coins, pulsing effects, etc.
+ *
+ * @param id Unique identifier for this animation set
+ * @param clip Clip definition
+ * @returns A frozen SpriteAnimationSet with one clip named 'default'
+ */
+export declare function defineSpriteAnimation(id: string, clip: SpriteAnimationClipInput): SpriteAnimationSet<'default'>;
+/**
+ * Define a multi-clip animation set with named animations.
+ * Animation names are inferred from the keys of the clips object.
+ *
+ * @param id Unique identifier for this animation set
+ * @param clips Object mapping animation names to clip definitions
+ * @param options Optional configuration (defaultClip)
+ * @returns A frozen SpriteAnimationSet with inferred animation name union
+ */
+export declare function defineSpriteAnimations<A extends string>(id: string, clips: Record<A, SpriteAnimationClipInput>, options?: {
+    defaultClip?: NoInfer<A>;
+}): SpriteAnimationSet<A>;
+/**
+ * Create a spriteAnimation component from an animation set.
+ *
+ * @param set The animation set to use
+ * @param options Optional configuration (initial clip, speed, onComplete event)
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createSpriteAnimation<A extends string>(set: SpriteAnimationSet<A>, options?: {
+    initial?: A;
+    speed?: number;
+    totalLoops?: number;
+    onComplete?: (data: SpriteAnimationEventData) => void;
+}): Pick<SpriteAnimationComponentTypes<A>, 'spriteAnimation'>;
+/**
+ * Switch an entity's current animation at runtime.
+ * Resets state if switching to a different animation (or restart=true).
+ *
+ * @returns false if entity has no spriteAnimation or animation name doesn't exist
+ */
+export declare function playAnimation(ecs: SpriteAnimationWorld, entityId: number, animation: string, options?: {
+    restart?: boolean;
+    speed?: number;
+}): boolean;
+/**
+ * Pause an entity's animation.
+ *
+ * @returns false if entity has no spriteAnimation
+ */
+export declare function stopAnimation(ecs: SpriteAnimationWorld, entityId: number): boolean;
+/**
+ * Resume a paused animation.
+ *
+ * @returns false if entity has no spriteAnimation
+ */
+export declare function resumeAnimation(ecs: SpriteAnimationWorld, entityId: number): boolean;
+/**
+ * Create a sprite animation plugin for ECSpresso.
+ *
+ * Provides:
+ * - Frame-based animation system processing spriteAnimation components
+ * - Loop modes: once, loop, pingPong
+ * - justFinished one-frame flag for completion detection
+ * - onComplete event publishing
+ * - Sprite texture sync via structural cross-plugin access
+ * - Change detection via markChanged
+ */
+export declare function createSpriteAnimationPlugin<G extends string = 'spriteAnimation'>(options?: SpriteAnimationPluginOptions<G>): Plugin<WorldConfigFrom<SpriteAnimationComponentTypes>, EmptyConfig, 'sprite-animation-update', G>;
+export {};

package/dist/{bundles → plugins}/state-machine.d.ts

@@ -1,5 +1,5 @@
 /**
- * State Machine Bundle for ECSpresso
+ * State Machine Plugin for ECSpresso
  *
  * Provides ECS-native finite state machines with guard-based transitions,
  * event-driven transitions, and lifecycle hooks (onEnter, onExit, onUpdate).
@@ -7,55 +7,49 @@
  * Each entity gets a `stateMachine` component referencing a shared definition.
  * One system processes all state machine entities each tick.
  */
-import { Bundle } from 'ecspresso';
-import type { SystemPhase } from 'ecspresso';
-/**
- * Structural interface for ECS methods available inside state machine hooks.
- * Uses method syntax for bivariant parameter checking under strictFunctionTypes,
- * allowing users to annotate hooks with their concrete ECSpresso type.
- */
-export interface StateMachineWorld {
-    entityManager: {
-        getComponent(entityId: number, componentName: string): unknown | undefined;
-    };
-    eventBus: {
-        publish(eventType: string, data: unknown): void;
-    };
-    spawn(components: Record<string, unknown>): {
-        id: number;
-    };
-    removeEntity(entityOrId: number): boolean;
-    hasComponent(entityId: number, componentName: string): boolean;
-    getResource(key: string): unknown;
-    hasResource(key: string): boolean;
-    markChanged(entityId: number, componentName: string): void;
-    commands: {
-        spawn(components: Record<string, unknown>): void;
-        removeEntity(entityId: number): void;
-    };
-}
+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 StateMachineWorld = StateMachineWorld> {
+export interface StateConfig<S extends string, W extends BaseWorld<StateMachineComponentTypes> = StateMachineWorld> {
     /** Called when entering this state */
-    onEnter?(ecs: W, entityId: number): void;
+    onEnter?(ctx: {
+        ecs: W;
+        entityId: number;
+    }): void;
     /** Called when exiting this state */
-    onExit?(ecs: W, entityId: number): void;
+    onExit?(ctx: {
+        ecs: W;
+        entityId: number;
+    }): void;
     /** Called each tick while in this state */
-    onUpdate?(ecs: W, entityId: number, deltaTime: number): void;
+    onUpdate?(ctx: {
+        ecs: W;
+        entityId: number;
+        dt: number;
+    }): void;
     /** Guard-based transitions evaluated each tick. First passing guard wins. */
     transitions?: ReadonlyArray<{
         target: S;
-        guard(ecs: W, entityId: number): boolean;
+        guard(ctx: {
+            ecs: W;
+            entityId: number;
+        }): boolean;
     }>;
     /** Event-based transition map: eventName → target state or guarded transition */
     on?: Record<string, S | {
         target: S;
-        guard(ecs: W, entityId: number): boolean;
+        guard(ctx: {
+            ecs: W;
+            entityId: number;
+        }): boolean;
     }>;
 }
 /**
@@ -82,7 +76,7 @@ export interface StateMachine<S extends string = string> {
     stateTime: number;
 }
 /**
- * Component types provided by the state machine bundle.
+ * Component types provided by the state machine plugin.
  *
  * @template S - Union of state name strings (default: string)
  */
@@ -101,7 +95,7 @@ export interface StateTransitionEvent<S extends string = string> {
     definitionId: string;
 }
 /**
- * Event types provided by the state machine bundle.
+ * Event types provided by the state machine plugin.
  *
  * @template S - Union of state name strings (default: string)
  */
@@ -120,15 +114,9 @@ export interface StateMachineEventTypes<S extends string = string> {
  */
 export type StatesOf<D> = D extends StateMachineDefinition<infer S> ? S : never;
 /**
- * Configuration options for the state machine bundle.
+ * Configuration options for the state machine plugin.
  */
-export interface StateMachineBundleOptions<G extends string = 'stateMachine'> {
-    /** System group name (default: 'stateMachine') */
-    systemGroup?: G;
-    /** Priority for state machine system (default: 0) */
-    priority?: number;
-    /** Execution phase (default: 'update') */
-    phase?: SystemPhase;
+export interface StateMachinePluginOptions<G extends string = 'stateMachine'> extends BasePluginOptions<G> {
 }
 /**
  * Define a state machine with type-safe state names.
@@ -144,11 +132,11 @@ export interface StateMachineBundleOptions<G extends string = 'stateMachine'> {
  *   initial: 'idle',
  *   states: {
  *     idle: {
- *       onEnter: (ecs, id) => { ... },
- *       transitions: [{ target: 'chase', guard: (ecs, id) => playerNearby(ecs, id) }],
+ *       onEnter: ({ ecs, entityId }) => { ... },
+ *       transitions: [{ target: 'chase', guard: ({ ecs, entityId }) => playerNearby(ecs, entityId) }],
  *     },
  *     chase: {
- *       onUpdate: (ecs, id, dt) => { ... },
+ *       onUpdate: ({ ecs, entityId, dt }) => { ... },
  *       on: { playerLost: 'idle' },
  *     },
  *   },
@@ -206,62 +194,19 @@ export declare function sendEvent(ecs: StateMachineWorld, entityId: number, even
  */
 export declare function getStateMachineState(ecs: StateMachineWorld, entityId: number): string | undefined;
 /**
- * A typed kit that captures the world type W once, providing helpers
- * where hooks/guards contextually receive W instead of StateMachineWorld.
- *
- * @template W - Concrete ECS world type
+ * 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 StateMachineKit<W extends StateMachineWorld, S extends string = string> {
-    bundle: Bundle<StateMachineComponentTypes<S>, StateMachineEventTypes<S>, {}, {}, {}, 'state-machine-update', 'stateMachine'>;
-    defineStateMachine: <DS extends S>(id: string, config: {
-        initial: NoInfer<DS>;
-        states: Record<DS, StateConfig<NoInfer<DS>, W>>;
-    }) => StateMachineDefinition<DS>;
-    createStateMachine: <DS extends S>(definition: StateMachineDefinition<DS>, options?: {
-        initial?: DS;
-    }) => Pick<StateMachineComponentTypes<S>, 'stateMachine'>;
+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 typed state machine kit that captures the world type W.
- *
- * Hooks and guards in definitions created via the kit's `defineStateMachine`
- * contextually receive W as their `ecs` parameter — no manual annotations needed.
- *
- * @template W - Concrete ECS world type
- * @param options - Optional bundle configuration (same as createStateMachineBundle)
- * @returns A kit object with bundle, defineStateMachine, createStateMachine, transitionTo, sendEvent, getStateMachineState
- *
- * @example
- * ```typescript
- * const ecs = ECSpresso.create()
- *   .withBundle(createStateMachineBundle())
- *   .withComponentTypes<{ enemy: true }>()
- *   .build();
- *
- * type ECS = typeof ecs;
- * const { bundle, defineStateMachine, createStateMachine } =
- *     createStateMachineKit<ECS>();
- *
- * const enemyFSM = defineStateMachine('enemy', {
- *     initial: 'patrol',
- *     states: {
- *         patrol: {
- *             onEnter(ecs, entityId) {
- *                 ecs.getResource('bounds'); // fully typed
- *             },
- *             transitions: [{
- *                 target: 'chase',
- *                 guard: (ecs, entityId) => distanceToPlayer(ecs, entityId) < 180,
- *             }],
- *         },
- *         chase: {},
- *     },
- * });
- * ```
- */
-export declare function createStateMachineKit<W extends StateMachineWorld = StateMachineWorld, S extends string = string>(options?: StateMachineBundleOptions): StateMachineKit<W, S>;
-/**
- * Create a state machine bundle for ECSpresso.
+ * Create a state machine plugin for ECSpresso.
  *
  * Provides:
  * - Lifecycle hooks (onEnter, onExit, onUpdate) per state
@@ -273,17 +218,17 @@ export declare function createStateMachineKit<W extends StateMachineWorld = Stat
  * @example
  * ```typescript
  * const ecs = ECSpresso.create()
- *   .withBundle(createStateMachineBundle())
+ *   .withPlugin(createStateMachinePlugin())
  *   .build();
  *
  * const fsm = defineStateMachine('enemy', {
  *   initial: 'idle',
  *   states: {
  *     idle: {
- *       transitions: [{ target: 'chase', guard: (ecs, id) => playerNearby(ecs, id) }],
+ *       transitions: [{ target: 'chase', guard: ({ ecs, entityId }) => playerNearby(ecs, entityId) }],
  *     },
  *     chase: {
- *       onUpdate: (ecs, id, dt) => moveTowardPlayer(ecs, id, dt),
+ *       onUpdate: ({ ecs, entityId, dt }) => moveTowardPlayer(ecs, entityId, dt),
  *       on: { playerLost: 'idle' },
  *     },
  *   },
@@ -295,4 +240,5 @@ export declare function createStateMachineKit<W extends StateMachineWorld = Stat
  * });
  * ```
  */
-export declare function createStateMachineBundle<S extends string = string, G extends string = 'stateMachine'>(options?: StateMachineBundleOptions<G>): Bundle<StateMachineComponentTypes<S>, StateMachineEventTypes<S>, {}, {}, {}, 'state-machine-update', G>;
+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 {};