ecspresso 0.10.2 → 0.11.0

package/dist/bundles/renderers/renderer2D.d.ts

@@ -8,11 +8,12 @@
  */
 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/utils/transform';
-import { type BoundsRect } from 'ecspresso/bundles/utils/bounds';
+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';
 export type { LocalTransform, WorldTransform, TransformComponentTypes };
 export type { BoundsRect };
-export { createTransform, createLocalTransform, createWorldTransform } from 'ecspresso/bundles/utils/transform';
+export { createTransform, createLocalTransform, createWorldTransform, DEFAULT_LOCAL_TRANSFORM, DEFAULT_WORLD_TRANSFORM } from 'ecspresso/bundles/transform';
 /**
  * Visibility and alpha component
  */
@@ -22,14 +23,14 @@ export interface Visible {
 }
 /**
  * Aggregate component types for the 2D renderer bundle.
- * Users should extend this interface with their own component types.
+ * Included automatically via `.withBundle(createRenderer2DBundle({ ... }))`.
  *
  * @example
  * ```typescript
- * interface GameComponents extends Renderer2DComponentTypes {
- *   velocity: { x: number; y: number };
- *   player: true;
- * }
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createRenderer2DBundle({ ... }))
+ *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
+ *   .build();
  * ```
  */
 export interface Renderer2DComponentTypes extends TransformComponentTypes {
@@ -59,14 +60,33 @@ export interface Renderer2DResourceTypes {
     /** Screen bounds derived from PixiJS screen dimensions, updated on resize */
     bounds: BoundsRect;
 }
+export type ScaleMode = 'fit' | 'cover' | 'stretch';
+export interface ScreenScaleOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly mode?: ScaleMode;
+}
+export interface ViewportScale {
+    scaleX: number;
+    scaleY: number;
+    offsetX: number;
+    offsetY: number;
+    physicalWidth: number;
+    physicalHeight: number;
+    readonly designWidth: number;
+    readonly designHeight: number;
+}
+export interface ViewportScaleResourceTypes {
+    viewportScale: ViewportScale;
+}
 /**
  * Common options shared between both initialization modes
  */
-interface Renderer2DBundleCommonOptions {
+interface Renderer2DBundleCommonOptions<G extends string = 'renderer2d'> {
     /** Optional custom root container (defaults to app.stage) */
     rootContainer?: Container;
     /** System group name (default: 'renderer2d') */
-    systemGroup?: string;
+    systemGroup?: G;
     /** Priority for render sync system (default: 500) */
     renderSyncPriority?: number;
     /** Options for the included transform bundle */
@@ -75,11 +95,17 @@ interface Renderer2DBundleCommonOptions {
     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) */
+    camera?: boolean;
+    /** Enforce a logical design resolution with automatic aspect-ratio-aware scaling.
+     *  When set, systems work in design-resolution coordinate space. */
+    screenScale?: ScreenScaleOptions;
 }
 /**
  * Options when providing a pre-initialized PixiJS Application
  */
-export interface Renderer2DBundleAppOptions extends Renderer2DBundleCommonOptions {
+export interface Renderer2DBundleAppOptions<G extends string = 'renderer2d'> extends Renderer2DBundleCommonOptions<G> {
     /** The PixiJS Application instance (already initialized) */
     app: Application;
     init?: never;
@@ -88,7 +114,7 @@ export interface Renderer2DBundleAppOptions extends Renderer2DBundleCommonOption
 /**
  * Options when letting the bundle create and manage the PixiJS Application
  */
-export interface Renderer2DBundleManagedOptions extends Renderer2DBundleCommonOptions {
+export interface Renderer2DBundleManagedOptions<G extends string = 'renderer2d'> extends Renderer2DBundleCommonOptions<G> {
     app?: never;
     /** PixiJS ApplicationOptions - bundle will create and initialize the Application */
     init: Partial<ApplicationOptions>;
@@ -108,31 +134,25 @@ export interface Renderer2DBundleManagedOptions extends Renderer2DBundleCommonOp
  * ```typescript
  * const app = new Application();
  * await app.init({ resizeTo: window });
- * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ * const ecs = ECSpresso.create()
  *   .withBundle(createRenderer2DBundle({ app }))
+ *   .withComponentTypes<{ player: true }>()
  *   .build();
  * ```
  *
  * @example Managed mode (convenience)
  * ```typescript
- * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ * const ecs = ECSpresso.create()
  *   .withBundle(createRenderer2DBundle({
  *     init: { background: '#1099bb', resizeTo: window },
  *     container: document.body,
  *   }))
+ *   .withComponentTypes<{ player: true }>()
  *   .build();
  * await ecs.initialize(); // Application created here
  * ```
  */
-export type Renderer2DBundleOptions = Renderer2DBundleAppOptions | Renderer2DBundleManagedOptions;
-/**
- * Default local transform values
- */
-export declare const DEFAULT_LOCAL_TRANSFORM: Readonly<LocalTransform>;
-/**
- * Default world transform values
- */
-export declare const DEFAULT_WORLD_TRANSFORM: Readonly<WorldTransform>;
+export type Renderer2DBundleOptions<G extends string = 'renderer2d'> = Renderer2DBundleAppOptions<G> | Renderer2DBundleManagedOptions<G>;
 interface PositionOption {
     x?: number;
     y?: number;
@@ -188,6 +208,15 @@ export declare function createGraphicsComponents(graphics: Graphics, position?:
  * ```
  */
 export declare function createContainerComponents(container: Container, position?: PositionOption, options?: TransformOptions): Pick<Renderer2DComponentTypes, 'container' | 'localTransform' | 'worldTransform' | 'visible'>;
+export declare function computeViewportScale(physicalW: number, physicalH: number, designW: number, designH: number, mode: ScaleMode): ViewportScale;
+/**
+ * Convert physical canvas pixel coordinates to design-resolution (logical) coordinates.
+ * Compose with camera `screenToWorld()` for full physical→world conversion.
+ */
+export declare function physicalToLogical(physicalX: number, physicalY: number, viewport: ViewportScale): {
+    x: number;
+    y: number;
+};
 /**
  * Create a 2D rendering bundle for ECSpresso.
  *
@@ -217,4 +246,16 @@ export declare function createContainerComponents(container: Container, position
  * await ecs.initialize();
  * ```
  */
-export declare function createRenderer2DBundle(options: Renderer2DBundleOptions): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes>;
+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> & {
+    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> & {
+    screenScale: ScreenScaleOptions;
+}): Bundle<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes, {}, {}, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DBundle<G extends string = 'renderer2d'>(options: Renderer2DBundleOptions<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>;

package/dist/bundles/spatial-index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Spatial Index Bundle 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
+ * spatialIndex resource at runtime and use it for broadphase when present.
+ */
+import { Bundle } from 'ecspresso';
+import type { TransformComponentTypes } from './transform';
+import type { CollisionComponentTypes } from './collision';
+import { type SpatialIndex } from '../utils/spatial-hash';
+export interface SpatialIndexResourceTypes {
+    spatialIndex: SpatialIndex;
+}
+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'> {
+    /** Cell size for the spatial hash grid (default: 64) */
+    cellSize?: number;
+    /** System group name (default: 'spatialIndex') */
+    systemGroup?: G;
+    /** Priority for rebuild systems (default: 2000, before collision) */
+    priority?: number;
+    /** Phases to register rebuild systems in (default: ['fixedUpdate', 'postUpdate']) */
+    phases?: ReadonlyArray<SpatialIndexPhase>;
+}
+/**
+ * Create a spatial index bundle for ECSpresso.
+ *
+ * Provides a uniform-grid spatial hash that accelerates collision detection.
+ * When installed alongside the collision or physics2D bundles, they
+ * automatically use the spatial index for broadphase instead of O(n²)
+ * brute-force.
+ *
+ * Also provides proximity query methods for game logic (e.g. "find all
+ * enemies within 200 units").
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createTransformBundle())
+ *   .withBundle(createCollisionBundle({ layers }))
+ *   .withBundle(createSpatialIndexBundle({ cellSize: 128 }))
+ *   .build();
+ *
+ * // Proximity query in a system:
+ * const si = ecs.getResource('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 {};

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

@@ -0,0 +1,298 @@
+/**
+ * State Machine Bundle 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 { 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;
+    };
+}
+/**
+ * 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> {
+    /** Called when entering this state */
+    onEnter?(ecs: W, entityId: number): void;
+    /** Called when exiting this state */
+    onExit?(ecs: W, entityId: number): void;
+    /** Called each tick while in this state */
+    onUpdate?(ecs: W, entityId: number, deltaTime: number): void;
+    /** Guard-based transitions evaluated each tick. First passing guard wins. */
+    transitions?: ReadonlyArray<{
+        target: S;
+        guard(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;
+    }>;
+}
+/**
+ * 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 bundle.
+ *
+ * @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 bundle.
+ *
+ * @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 bundle.
+ */
+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;
+}
+/**
+ * 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, id) => { ... },
+ *       transitions: [{ target: 'chase', guard: (ecs, id) => playerNearby(ecs, id) }],
+ *     },
+ *     chase: {
+ *       onUpdate: (ecs, id, 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;
+/**
+ * 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
+ */
+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'>;
+}
+/**
+ * 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.
+ *
+ * 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()
+ *   .withBundle(createStateMachineBundle())
+ *   .build();
+ *
+ * const fsm = defineStateMachine('enemy', {
+ *   initial: 'idle',
+ *   states: {
+ *     idle: {
+ *       transitions: [{ target: 'chase', guard: (ecs, id) => playerNearby(ecs, id) }],
+ *     },
+ *     chase: {
+ *       onUpdate: (ecs, id, dt) => moveTowardPlayer(ecs, id, dt),
+ *       on: { playerLost: 'idle' },
+ *     },
+ *   },
+ * });
+ *
+ * ecs.spawn({
+ *   ...createStateMachine(fsm),
+ *   position: { x: 0, y: 0 },
+ * });
+ * ```
+ */
+export declare function createStateMachineBundle<S extends string = string, G extends string = 'stateMachine'>(options?: StateMachineBundleOptions<G>): Bundle<StateMachineComponentTypes<S>, StateMachineEventTypes<S>, {}, {}, {}, 'state-machine-update', G>;

package/dist/bundles/{utils/timers.d.ts → timers.d.ts}

@@ -55,16 +55,17 @@ export interface Timer<EventTypes extends Record<string, any>> {
 }
 /**
  * Component types provided by the timer bundle.
- * Extend your component types with this interface.
+ * Included automatically via `.withBundle(createTimerBundle<Events>())`.
+ * The EventTypes generic constrains which events can be used with `onComplete`.
  *
  * @template EventTypes The event types from your ECS
  *
  * @example
  * ```typescript
- * interface GameComponents extends TimerComponentTypes<GameEvents> {
- *   velocity: { x: number; y: number };
- *   player: true;
- * }
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createTimerBundle<{ respawn: TimerEventData }>())
+ *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
+ *   .build();
  * ```
  */
 export interface TimerComponentTypes<EventTypes extends Record<string, any>> {
@@ -73,9 +74,9 @@ export interface TimerComponentTypes<EventTypes extends Record<string, any>> {
 /**
  * Configuration options for the timer bundle.
  */
-export interface TimerBundleOptions {
+export interface TimerBundleOptions<G extends string = 'timers'> {
     /** System group name (default: 'timers') */
-    systemGroup?: string;
+    systemGroup?: G;
     /** Priority for timer update system (default: 0) */
     priority?: number;
     /** Execution phase (default: 'preUpdate') */
@@ -169,4 +170,4 @@ export declare function createRepeatingTimer<EventTypes extends Record<string, a
  *   });
  * ```
  */
-export declare function createTimerBundle<EventTypes extends Record<string, any>>(options?: TimerBundleOptions): Bundle<TimerComponentTypes<EventTypes>, EventTypes, {}>;
+export declare function createTimerBundle<EventTypes extends Record<string, any>, G extends string = 'timers'>(options?: TimerBundleOptions<G>): Bundle<TimerComponentTypes<EventTypes>, EventTypes, {}, {}, {}, 'timer-update', G>;

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

@@ -32,14 +32,14 @@ export interface WorldTransform {
 }
 /**
  * Component types provided by the transform bundle.
- * Extend your component types with this interface.
+ * Included automatically via `.withBundle(createTransformBundle())`.
  *
  * @example
  * ```typescript
- * interface GameComponents extends TransformComponentTypes {
- *   sprite: Sprite;
- *   velocity: { x: number; y: number };
- * }
+ * const ecs = ECSpresso.create()
+ *   .withBundle(createTransformBundle())
+ *   .withComponentTypes<{ sprite: Sprite; velocity: { x: number; y: number } }>()
+ *   .build();
  * ```
  */
 export interface TransformComponentTypes {
@@ -49,10 +49,10 @@ export interface TransformComponentTypes {
 /**
  * Configuration options for the transform bundle.
  */
-export interface TransformBundleOptions {
+export interface TransformBundleOptions<G extends string = 'transform'> {
     /** System group name (default: 'transform') */
-    systemGroup?: string;
-    /** Priority for transform propagation (default: 500, runs after physics/movement) */
+    systemGroup?: G;
+    /** Priority for transform propagation (default: 500, runs after physics) */
     priority?: number;
     /** Execution phase (default: 'postUpdate') */
     phase?: SystemPhase;
@@ -138,7 +138,7 @@ export declare function createTransform(x: number, y: number, options?: Transfor
  * const ecs = ECSpresso
  *   .create<Components, Events, Resources>()
  *   .withBundle(createTransformBundle())
- *   .withBundle(createMovementBundle())
+ *   .withBundle(createPhysics2DBundle())
  *   .build();
  *
  * // Spawn entity with transform
@@ -148,4 +148,4 @@ export declare function createTransform(x: number, y: number, options?: Transfor
  * });
  * ```
  */
-export declare function createTransformBundle(options?: TransformBundleOptions): Bundle<TransformComponentTypes, {}, {}>;
+export declare function createTransformBundle<G extends string = 'transform'>(options?: TransformBundleOptions<G>): Bundle<TransformComponentTypes, {}, {}, {}, {}, 'transform-propagation', G>;