ecspresso 0.10.2 → 0.12.0

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

@@ -1,13 +1,13 @@
 /**
- * Bounds Bundle for ECSpresso
+ * Bounds Plugin for ECSpresso
  *
  * Provides screen bounds enforcement for entities with transforms.
  * Reads worldTransform for position checking; modifies localTransform for corrections.
  * Supports destroy, clamp, and wrap behaviors.
  */
-import { Bundle } from 'ecspresso';
-import type { SystemPhase } from 'ecspresso';
-import type { TransformComponentTypes } from './transform';
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom } from '../type-utils';
+import type { TransformWorldConfig } from './transform';
 /**
  * Component that marks an entity for destruction when outside bounds.
  */
@@ -30,14 +30,16 @@ export interface WrapAtBounds {
     padding?: number;
 }
 /**
- * Component types provided by the bounds bundle.
- * Extend your component types with this interface.
+ * Component types provided by the bounds plugin.
+ * Included automatically via `.withPlugin(createBoundsPlugin())`.
  *
  * @example
  * ```typescript
- * interface GameComponents extends TransformComponentTypes, BoundsComponentTypes {
- *   sprite: Sprite;
- * }
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createBoundsPlugin({ width: 800, height: 600 }))
+ *   .withComponentTypes<{ sprite: Sprite }>()
+ *   .build();
  * ```
  */
 export interface BoundsComponentTypes {
@@ -59,7 +61,7 @@ export interface BoundsRect {
     height: number;
 }
 /**
- * Resource types provided by the bounds bundle.
+ * Resource types provided by the bounds plugin.
  */
 export interface BoundsResourceTypes {
     bounds: BoundsRect;
@@ -74,25 +76,19 @@ export interface EntityOutOfBoundsEvent {
     exitEdge: 'top' | 'bottom' | 'left' | 'right';
 }
 /**
- * Event types provided by the bounds bundle.
+ * Event types provided by the bounds plugin.
  */
 export interface BoundsEventTypes {
     entityOutOfBounds: EntityOutOfBoundsEvent;
 }
 /**
- * Configuration options for the bounds bundle.
+ * Configuration options for the bounds plugin.
  */
-export interface BoundsBundleOptions {
-    /** System group name (default: 'physics') */
-    systemGroup?: string;
-    /** Priority for bounds systems (default: 50) */
-    priority?: number;
+export interface BoundsPluginOptions<G extends string = 'physics'> extends BasePluginOptions<G> {
     /** Resource key for bounds rectangle (default: 'bounds') */
     boundsResourceKey?: string;
     /** Whether to auto-remove entities when out of bounds (default: true) */
     autoRemove?: boolean;
-    /** Execution phase (default: 'postUpdate') */
-    phase?: SystemPhase;
 }
 /**
  * Create a bounds rectangle resource.
@@ -156,11 +152,10 @@ export declare function createClampToBounds(margin?: number): Pick<BoundsCompone
  * ```
  */
 export declare function createWrapAtBounds(padding?: number): Pick<BoundsComponentTypes, 'wrapAtBounds'>;
-type CombinedComponentTypes = BoundsComponentTypes & TransformComponentTypes;
 /**
- * Create a bounds bundle for ECSpresso.
+ * Create a bounds plugin for ECSpresso.
  *
- * This bundle provides:
+ * This plugin provides:
  * - Destroy out of bounds system - removes entities that exit bounds
  * - Clamp to bounds system - constrains entities within bounds
  * - Wrap at bounds system - wraps entities to opposite edge
@@ -174,8 +169,8 @@ type CombinedComponentTypes = BoundsComponentTypes & TransformComponentTypes;
  * const ecs = ECSpresso
  *   .create<Components, Events, Resources>()
  *   .withResource('bounds', createBounds(800, 600))
- *   .withBundle(createTransformBundle())
- *   .withBundle(createBoundsBundle())
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createBoundsPlugin())
  *   .build();
  *
  * // Entity that gets destroyed when leaving screen
@@ -185,5 +180,4 @@ type CombinedComponentTypes = BoundsComponentTypes & TransformComponentTypes;
  * });
  * ```
  */
-export declare function createBoundsBundle<ResourceTypes extends BoundsResourceTypes = BoundsResourceTypes>(options?: BoundsBundleOptions): Bundle<CombinedComponentTypes, BoundsEventTypes, ResourceTypes>;
-export {};
+export declare function createBoundsPlugin<ResourceTypes extends BoundsResourceTypes = BoundsResourceTypes, G extends string = 'physics'>(options?: BoundsPluginOptions<G>): Plugin<WorldConfigFrom<BoundsComponentTypes, BoundsEventTypes, ResourceTypes>, TransformWorldConfig, 'bounds-destroy' | 'bounds-clamp' | 'bounds-wrap', G>;

package/dist/plugins/camera.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Camera / Viewport Plugin for ECSpresso
+ *
+ * Provides a camera entity with world/screen coordinate conversion, smooth follow,
+ * trauma-based shake, bounds clamping, and logical viewport dimensions.
+ *
+ * This plugin is renderer-agnostic. PixiJS or other renderer integration (applying
+ * cameraState to a container/stage transform) is the consumer's responsibility.
+ *
+ * Camera uses its own x/y/zoom/rotation rather than localTransform/worldTransform.
+ * It reads the target entity's worldTransform for follow, but doesn't participate
+ * in the transform hierarchy itself.
+ */
+import { type Plugin } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type ECSpresso from 'ecspresso';
+import type { WorldConfigFrom } from '../type-utils';
+import type { TransformWorldConfig } from './transform';
+export interface Camera {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+}
+export interface CameraFollow {
+    target: number;
+    smoothing: number;
+    deadzoneX: number;
+    deadzoneY: number;
+    offsetX: number;
+    offsetY: number;
+}
+export interface CameraShake {
+    trauma: number;
+    traumaDecay: number;
+    maxOffsetX: number;
+    maxOffsetY: number;
+    maxRotation: number;
+}
+export interface CameraBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface CameraComponentTypes {
+    camera: Camera;
+    cameraFollow: CameraFollow;
+    cameraShake: CameraShake;
+    cameraBounds: CameraBounds;
+}
+export interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+    shakeOffsetX: number;
+    shakeOffsetY: number;
+    shakeRotation: number;
+    viewportWidth: number;
+    viewportHeight: number;
+}
+export interface CameraResourceTypes {
+    cameraState: CameraState;
+}
+export interface CameraPluginOptions<G extends string = 'camera'> {
+    viewportWidth?: number;
+    viewportHeight?: number;
+    systemGroup?: G;
+    phase?: SystemPhase;
+    randomFn?: () => number;
+}
+export declare const DEFAULT_CAMERA: Readonly<Camera>;
+export declare const DEFAULT_CAMERA_STATE: Readonly<CameraState>;
+export declare function createCamera(x?: number, y?: number, zoom?: number, rotation?: number): Pick<CameraComponentTypes, 'camera'>;
+export declare function createCameraFollow(target: number, options?: Partial<Omit<CameraFollow, 'target'>>): Pick<CameraComponentTypes, 'cameraFollow'>;
+export declare function createCameraShake(options?: Partial<CameraShake>): Pick<CameraComponentTypes, 'cameraShake'>;
+export declare function createCameraBounds(minX: number, minY: number, maxX: number, maxY: number): Pick<CameraComponentTypes, 'cameraBounds'>;
+export declare function addTrauma<Cfg extends WorldConfigFrom<CameraComponentTypes, {}, CameraResourceTypes>>(ecs: ECSpresso<Cfg>, entityId: number, amount: number): void;
+export declare function worldToScreen(worldX: number, worldY: number, state: CameraState): {
+    x: number;
+    y: number;
+};
+export declare function screenToWorld(screenX: number, screenY: number, state: CameraState): {
+    x: number;
+    y: number;
+};
+export declare function createCameraPlugin<G extends string = 'camera'>(options?: CameraPluginOptions<G>): Plugin<WorldConfigFrom<CameraComponentTypes, {}, CameraResourceTypes>, TransformWorldConfig, 'camera-follow' | 'camera-shake-update' | 'camera-bounds' | 'camera-state-sync', G>;

package/dist/plugins/collision.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Collision Plugin for ECSpresso
+ *
+ * Provides layer-based collision detection with events.
+ * Uses worldTransform for position (world-space collision).
+ * Supports AABB and circle colliders.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { WorldConfigFrom } from '../type-utils';
+import type { TransformWorldConfig } from './transform';
+/**
+ * Axis-Aligned Bounding Box collider.
+ */
+export interface AABBCollider {
+    /** Width of the bounding box */
+    width: number;
+    /** Height of the bounding box */
+    height: number;
+    /** X offset from entity position (default: 0) */
+    offsetX?: number;
+    /** Y offset from entity position (default: 0) */
+    offsetY?: number;
+}
+/**
+ * Circle collider.
+ */
+export interface CircleCollider {
+    /** Radius of the circle */
+    radius: number;
+    /** X offset from entity position (default: 0) */
+    offsetX?: number;
+    /** Y offset from entity position (default: 0) */
+    offsetY?: number;
+}
+/**
+ * Collision layer configuration.
+ */
+export interface CollisionLayer<L extends string = never> {
+    /** The layer this entity belongs to */
+    layer: L;
+    /** Layers this entity can collide with */
+    collidesWith: readonly L[];
+}
+/**
+ * Component types provided by the collision plugin.
+ * Included automatically via `.withPlugin(createCollisionPlugin())`.
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createCollisionPlugin())
+ *   .withComponentTypes<{ sprite: Sprite; enemy: boolean }>()
+ *   .build();
+ * ```
+ */
+export interface CollisionComponentTypes<L extends string = never> {
+    aabbCollider: AABBCollider;
+    circleCollider: CircleCollider;
+    collisionLayer: CollisionLayer<L>;
+}
+/**
+ * Event fired when two entities collide.
+ */
+export interface CollisionEvent<L extends string = never> {
+    /** First entity in the collision */
+    entityA: number;
+    /** Second entity in the collision */
+    entityB: number;
+    /** Layer of the first entity */
+    layerA: L;
+    /** Layer of the second entity */
+    layerB: L;
+    /** Contact normal pointing from entityA toward entityB */
+    normal: {
+        x: number;
+        y: number;
+    };
+    /** Penetration depth (positive = overlapping) */
+    depth: number;
+}
+/**
+ * Event types provided by the collision plugin.
+ */
+export interface CollisionEventTypes<L extends string = never> {
+    collision: CollisionEvent<L>;
+}
+/**
+ * Configuration options for the collision plugin.
+ */
+export interface CollisionPluginOptions<G extends string = 'physics'> extends BasePluginOptions<G> {
+    /** Name of the collision event (default: 'collision') */
+    collisionEventName?: string;
+}
+/**
+ * Create an AABB collider component.
+ *
+ * @param width Width of the bounding box
+ * @param height Height of the bounding box
+ * @param offsetX X offset from entity position
+ * @param offsetY Y offset from entity position
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ * });
+ * ```
+ */
+export declare function createAABBCollider(width: number, height: number, offsetX?: number, offsetY?: number): {
+    aabbCollider: AABBCollider;
+};
+/**
+ * Create a circle collider component.
+ *
+ * @param radius Radius of the circle
+ * @param offsetX X offset from entity position
+ * @param offsetY Y offset from entity position
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createCircleCollider(25),
+ * });
+ * ```
+ */
+export declare function createCircleCollider(radius: number, offsetX?: number, offsetY?: number): {
+    circleCollider: CircleCollider;
+};
+/**
+ * Create a collision layer component.
+ *
+ * @param layer The layer this entity belongs to
+ * @param collidesWith Layers this entity can collide with
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...createCollisionLayer('player', ['enemy', 'obstacle']),
+ * });
+ * ```
+ */
+export declare function createCollisionLayer<L extends string>(layer: L, collidesWith: readonly L[]): Pick<CollisionComponentTypes<L>, 'collisionLayer'>;
+/**
+ * Layer factory result from defineCollisionLayers.
+ */
+export type LayerFactories<T extends Record<string, readonly string[]>> = {
+    [K in keyof T]: () => Pick<CollisionComponentTypes<Extract<keyof T, string>>, 'collisionLayer'>;
+};
+/**
+ * Extract layer names from a `defineCollisionLayers` result for use with
+ * `createCollisionPairHandler`'s `L` type parameter.
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * type Layer = LayersOf<typeof layers>;
+ * const handler = createCollisionPairHandler<ECS, Layer>({
+ *   'player:enemy': (playerId, enemyId, ecs) => { ... },
+ * });
+ * ```
+ */
+export type LayersOf<T> = Extract<keyof T, string>;
+/**
+ * Define collision layer relationships and get factory functions.
+ *
+ * @param rules Object mapping layer names to arrays of layers they collide with
+ * @returns Object with factory functions for each layer
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({
+ *   player: ['enemy', 'enemyProjectile'],
+ *   playerProjectile: ['enemy'],
+ *   enemy: ['playerProjectile'],
+ *   enemyProjectile: ['player'],
+ * });
+ *
+ * // Usage
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...layers.player(),
+ * });
+ * ```
+ */
+/**
+ * Validates that all `collidesWith` values reference actual layer keys.
+ * Catches typos at compile time.
+ */
+type ValidateCollidesWith<T> = {
+    [K in keyof T]: T[K] extends readonly (infer V)[] ? [V] extends [Extract<keyof T, string>] ? T[K] : readonly Extract<keyof T, string>[] : never;
+};
+export declare function defineCollisionLayers<const T extends Record<string, readonly string[]>>(rules: T & ValidateCollidesWith<T>): LayerFactories<T>;
+/**
+ * Callback for a collision pair handler.
+ *
+ * @param firstEntityId Entity belonging to the first layer in the pair key
+ * @param secondEntityId Entity belonging to the second layer in the pair key
+ * @param ecs The ECS world instance (passed through from the subscriber)
+ */
+export type CollisionPairCallback<W = unknown> = (firstEntityId: number, secondEntityId: number, ecs: W) => void;
+/**
+ * Create a collision pair handler that routes collision events to
+ * layer-pair-specific callbacks.
+ *
+ * Registering `"a:b"` automatically handles both `(layerA=a, layerB=b)` and
+ * `(layerA=b, layerB=a)`. Entity arguments are swapped to match the declared
+ * key order. If both `"a:b"` and `"b:a"` are explicitly registered, each gets
+ * its own handler with no implicit reverse.
+ *
+ * @typeParam W - The ECS world type (e.g. `ECSpresso<C, E, R>`). Defaults to `unknown`.
+ * @typeParam L - Union of valid layer names. Defaults to `string`.
+ *   Provide specific layer names for compile-time key validation:
+ *   `createCollisionPairHandler<ECS, keyof typeof layers>({...})`
+ *
+ * @param pairs Object mapping `"layerA:layerB"` keys to callbacks
+ * @returns A dispatch function to call with collision event data and ECS instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage:
+ * const handler = createCollisionPairHandler<ECS>({
+ *   'playerProjectile:enemy': (projectileId, enemyId, ecs) => {
+ *     ecs.commands.removeEntity(projectileId);
+ *   },
+ * });
+ *
+ * // With layer name validation:
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * type Layer = LayersOf<typeof layers>;
+ * const handler = createCollisionPairHandler<ECS, Layer>({
+ *   'player:enemy': (playerId, enemyId, ecs) => { ... },
+ * });
+ *
+ * ecs.eventBus.subscribe('collision', (data) => handler({ data, ecs }));
+ * ```
+ */
+export declare function createCollisionPairHandler<W = unknown, L extends string = string>(pairs: {
+    [K in `${L}:${L}`]?: CollisionPairCallback<W>;
+}): (ctx: {
+    data: CollisionEvent<L>;
+    ecs: W;
+}) => void;
+/**
+ * Create a collision plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - Collision detection between entities with colliders
+ * - AABB-AABB, circle-circle, and AABB-circle collision
+ * - Layer-based filtering for collision pairs
+ * - Deduplication of A-B / B-A collisions
+ * - Automatic broadphase acceleration when spatialIndex resource is present
+ *
+ * Uses worldTransform for position (world-space collision detection).
+ * The `layers` parameter is required for type inference — at runtime the
+ * plugin does not consume it.
+ *
+ * @example
+ * ```typescript
+ * const layers = defineCollisionLayers({ player: ['enemy'], enemy: ['player'] });
+ * const ecs = ECSpresso
+ *   .create()
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createCollisionPlugin({ layers }))
+ *   .build();
+ *
+ * // Entity with collision
+ * ecs.spawn({
+ *   ...createTransform(100, 200),
+ *   ...createAABBCollider(50, 30),
+ *   ...layers.player(),
+ * });
+ * ```
+ */
+export declare function createCollisionPlugin<L extends string, G extends string = 'physics'>(options: CollisionPluginOptions<G> & {
+    layers: LayerFactories<Record<L, readonly string[]>>;
+}): Plugin<WorldConfigFrom<CollisionComponentTypes<L>, CollisionEventTypes<L>>, TransformWorldConfig, 'collision-detection', G>;
+export {};

package/dist/plugins/coroutine.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Coroutine Plugin for ECSpresso
+ *
+ * ES6 generator-based coroutines for multi-step, frame-spanning scripted sequences.
+ * A `coroutine` component holds a live generator. A system ticks all generators each
+ * frame via `.next(dt)`. Helper generators (`waitSeconds`, `waitFrames`, `waitUntil`,
+ * `waitForEvent`, `parallel`, `race`) compose via `yield*`.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { EventsOfWorld, AnyECSpresso } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+/**
+ * Yields void, returns void, receives deltaTime (number) via `.next(dt)`.
+ * First `.next(dt)` initializes the generator (runs to first yield, dt discarded per JS spec).
+ * Subsequent `.next(dt)` resume from yield with dt as the yield expression value.
+ */
+export type CoroutineGenerator = Generator<void, void, number>;
+export interface CoroutineEventData {
+    entityId: number;
+}
+export interface CoroutineState {
+    generator: CoroutineGenerator;
+    onComplete?: (data: CoroutineEventData) => void;
+}
+export interface CoroutineComponentTypes {
+    coroutine: CoroutineState;
+}
+export interface CoroutinePluginOptions<G extends string = 'coroutines'> extends BasePluginOptions<G> {
+}
+export interface CoroutineOptions {
+    onComplete?: (data: CoroutineEventData) => void;
+}
+/**
+ * Create a coroutine component for spawning or adding to an entity.
+ *
+ * @param generator - The generator function to drive
+ * @param options - Optional configuration (onComplete event)
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createCoroutine(generator: CoroutineGenerator, options?: CoroutineOptions): Pick<CoroutineComponentTypes, 'coroutine'>;
+/**
+ * Wait for a specified number of seconds. Accumulates dt until elapsed >= seconds.
+ * If seconds <= 0, returns immediately.
+ */
+export declare function waitSeconds(seconds: number): CoroutineGenerator;
+/**
+ * Wait for a specified number of frames. Yields `frames` times.
+ * If frames <= 0, returns immediately.
+ */
+export declare function waitFrames(frames: number): CoroutineGenerator;
+/**
+ * Wait until a predicate returns true. Yields each frame until predicate is satisfied.
+ * User closes over ecs if needed for state checks.
+ */
+export declare function waitUntil(predicate: () => boolean): CoroutineGenerator;
+/**
+ * Run multiple coroutines in parallel. Completes when all finish.
+ * Initializes all sub-generators, ticks all each frame.
+ * Empty array = immediate return.
+ */
+export declare function parallel(...coroutines: CoroutineGenerator[]): CoroutineGenerator;
+/**
+ * Run multiple coroutines, completing when the first one finishes.
+ * Calls `.return()` on remaining generators (triggers finally blocks).
+ * Empty array = immediate return.
+ */
+export declare function race(...coroutines: CoroutineGenerator[]): CoroutineGenerator;
+/**
+ * Wait until a matching event fires on the event bus.
+ * Subscribes via eventBus.subscribe, yields until event received, unsubscribes in finally block.
+ *
+ * @param eventBus - Object with subscribe method (typically ecs.eventBus)
+ * @param eventType - Event type name to listen for
+ * @param filter - Optional predicate to filter events
+ */
+export declare function waitForEvent<ET extends Record<string, any>, E extends keyof ET & string>(eventBus: {
+    subscribe(type: E, cb: (data: ET[E]) => void): () => void;
+}, eventType: E, filter?: (data: ET[E]) => boolean): CoroutineGenerator;
+/**
+ * Structural interface for ECS methods used by cancelCoroutine.
+ */
+export interface CoroutineWorld {
+    getComponent(entityId: number, componentName: string): unknown | undefined;
+    commands: {
+        removeComponent(entityId: number, componentName: string): void;
+    };
+}
+/**
+ * Cancel a running coroutine on an entity. Calls generator.return() (triggers finally blocks)
+ * and queues component removal.
+ *
+ * @returns true if the entity had a coroutine that was cancelled, false otherwise
+ */
+export declare function cancelCoroutine(ecs: CoroutineWorld, entityId: number): boolean;
+/**
+ * Type-safe coroutine helpers that validate event names against a world's event types.
+ * Use `createCoroutineHelpers<typeof ecs>()` to get compile-time validation.
+ */
+export interface CoroutineHelpers<W extends AnyECSpresso> {
+    createCoroutine: (generator: CoroutineGenerator, options?: {
+        onComplete?: (data: CoroutineEventData) => void;
+    }) => Pick<CoroutineComponentTypes, 'coroutine'>;
+    waitForEvent: <E extends keyof EventsOfWorld<W> & string>(eventBus: {
+        subscribe(type: E, cb: (data: EventsOfWorld<W>[E]) => void): () => void;
+    }, eventType: E, filter?: (data: EventsOfWorld<W>[E]) => boolean) => CoroutineGenerator;
+}
+/**
+ * Create typed coroutine helpers that validate event names at compile time.
+ *
+ * @example
+ * ```typescript
+ * const { createCoroutine, waitForEvent } = createCoroutineHelpers<typeof ecs>();
+ * ecs.spawn({ ...createCoroutine(myGen(), { onComplete: (data) => console.log(data.entityId) }) });
+ * ```
+ */
+export declare function createCoroutineHelpers<W extends AnyECSpresso>(_world?: W): CoroutineHelpers<W>;
+/**
+ * Create a coroutine plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - Coroutine system that ticks all generator-based coroutines each frame
+ * - Automatic cleanup via dispose callback (triggers generator finally blocks)
+ * - `onComplete` callback invocation
+ * - Component removal on completion
+ */
+export declare function createCoroutinePlugin<G extends string = 'coroutines'>(options?: CoroutinePluginOptions<G>): Plugin<WorldConfigFrom<CoroutineComponentTypes>, EmptyConfig, 'coroutine-update', G>;

package/dist/plugins/diagnostics.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Diagnostics Plugin for ECSpresso
+ *
+ * Runtime diagnostics: FPS, entity count, per-system timing, per-phase timing,
+ * and an optional DOM overlay for visual debugging.
+ */
+import { type Plugin } from 'ecspresso';
+import type { SystemPhase } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+export interface DiagnosticsData {
+    fps: number;
+    entityCount: number;
+    systemTimings: ReadonlyMap<string, number>;
+    phaseTimings: Readonly<Record<SystemPhase, number>>;
+    averageFrameTime: number;
+}
+export interface DiagnosticsResourceTypes {
+    diagnostics: DiagnosticsData;
+}
+export interface DiagnosticsPluginOptions<G extends string = 'diagnostics'> {
+    /** System group name (default: 'diagnostics') */
+    systemGroup?: G;
+    /** Enable timing collection on initialize (default: true) */
+    enableTimingOnInit?: boolean;
+    /** Number of frames to sample for FPS average (default: 60) */
+    fpsSampleCount?: number;
+}
+export interface DiagnosticsOverlayOptions {
+    /** Corner position (default: 'top-left') */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /** Milliseconds between DOM updates (default: 200) */
+    updateInterval?: number;
+    /** Show per-system timings (default: true) */
+    showSystemTimings?: boolean;
+    /** Maximum systems to show in overlay (default: 10) */
+    maxSystemsShown?: number;
+}
+export declare function createDiagnosticsPlugin<G extends string = 'diagnostics'>(options?: DiagnosticsPluginOptions<G>): Plugin<WorldConfigFrom<{}, {}, DiagnosticsResourceTypes>, EmptyConfig, 'diagnostics-collect', G>;
+/**
+ * Create a DOM overlay that displays diagnostics data.
+ * Returns a cleanup function that removes the element and clears the interval.
+ *
+ * @param ecs An ECSpresso instance with the diagnostics resource
+ * @param options Overlay configuration
+ * @returns Cleanup function
+ */
+export declare function createDiagnosticsOverlay<R extends DiagnosticsResourceTypes>(ecs: {
+    getResource<K extends keyof R>(key: K): R[K];
+}, options?: DiagnosticsOverlayOptions): () => void;