ecspresso 0.10.2 → 0.12.0

package/dist/entity-manager.d.ts

@@ -15,6 +15,11 @@ export default class EntityManager<ComponentTypes> {
      * Hierarchy manager for parent-child relationships
      */
     private hierarchyManager;
+    /**
+     * Per-type component dispose callbacks.
+     * Called when a component is removed (explicit removal, entity destruction, or replacement).
+     */
+    private disposeCallbacks;
     /**
      * Per-entity per-component change sequence tracking.
      * Maps entityId -> (componentName -> sequence number when last changed)
@@ -25,24 +30,59 @@ export default class EntityManager<ComponentTypes> {
      * Each markChanged call increments this and stamps the new value.
      */
     private _changeSeq;
+    private _afterComponentAddedHooks;
+    private _afterEntityMutatedHooks;
+    private _afterComponentRemovedHooks;
+    private _beforeEntityRemovedHooks;
+    private _afterParentChangedHooks;
+    private _batchingDepth;
+    private _batchedEntityIds;
+    /** Component keys being added in the current addComponents batch, if any.
+     *  Used by required component resolution to skip auto-adding explicitly provided components. */
+    _pendingBatchKeys: ReadonlySet<keyof ComponentTypes> | null;
+    get entityCount(): number;
     createEntity(): Entity<ComponentTypes>;
-    addComponent<ComponentName extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: ComponentName, data: ComponentTypes[ComponentName]): this;
+    /**
+     * Register a dispose callback for a component type.
+     * Called when a component is removed (explicit removal, entity destruction, or replacement).
+     * Later registrations replace earlier ones for the same component type.
+     * @param componentName The component type to register disposal for
+     * @param callback Function receiving the component value being disposed and the entity ID
+     */
+    registerDispose<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, callback: (ctx: {
+        value: ComponentTypes[ComponentName];
+        entityId: number;
+    }) => void): void;
+    /**
+     * Get all registered dispose callbacks.
+     * @internal Used by ECSpresso for plugin installation
+     */
+    getDisposeCallbacks(): Map<keyof ComponentTypes, (ctx: {
+        value: unknown;
+        entityId: number;
+    }) => void>;
+    /**
+     * Invoke the dispose callback for a component, if registered.
+     * Errors are caught and logged to prevent blocking removal.
+     */
+    private invokeDispose;
+    addComponent<ComponentName extends keyof ComponentTypes>(entityId: number, componentName: ComponentName, data: ComponentTypes[ComponentName]): this;
     /**
      * Add multiple components to an entity at once
-     * @param entityOrId Entity or entity ID to add components to
+     * @param entityId Entity ID to add components to
      * @param components Object with component names as keys and component data as values
      */
     addComponents<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(entityOrId: number | Entity<ComponentTypes>, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): this;
-    removeComponent<ComponentName extends keyof ComponentTypes>(entityOrId: number | Entity<ComponentTypes>, componentName: ComponentName): this;
-    getComponent<ComponentName extends keyof ComponentTypes>(entityId: number, componentName: ComponentName): ComponentTypes[ComponentName] | null;
+    }>(entityId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): this;
+    removeComponent<ComponentName extends keyof ComponentTypes>(entityId: number, componentName: ComponentName): this;
+    getComponent<ComponentName extends keyof ComponentTypes>(entityId: number, componentName: ComponentName): ComponentTypes[ComponentName] | undefined;
     getEntitiesWithQuery<WithComponents extends keyof ComponentTypes = never, WithoutComponents extends keyof ComponentTypes = never>(required?: ReadonlyArray<WithComponents>, excluded?: ReadonlyArray<WithoutComponents>, changed?: ReadonlyArray<keyof ComponentTypes>, changeThreshold?: number, parentHas?: ReadonlyArray<keyof ComponentTypes>): Array<FilteredEntity<ComponentTypes, WithComponents extends never ? never : WithComponents, WithoutComponents extends never ? never : WithoutComponents>>;
     /**
      * Check if an entity's direct parent has all specified components
      */
     private parentHasComponents;
-    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): boolean;
+    removeEntity(entityId: number, options?: RemoveEntityOptions): boolean;
     /**
      * Internal method to remove a single entity without cascade logic
      */
@@ -54,14 +94,25 @@ export default class EntityManager<ComponentTypes> {
      * @param handler Function receiving the new component value and the entity
      * @returns Unsubscribe function to remove the callback
      */
-    onComponentAdded<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (value: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): () => void;
+    onComponentAdded<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (ctx: {
+        value: ComponentTypes[ComponentName];
+        entity: Entity<ComponentTypes>;
+    }) => void): () => void;
     /**
      * Register a callback when a specific component is removed from any entity
      * @param componentName The component key
      * @param handler Function receiving the old component value and the entity
      * @returns Unsubscribe function to remove the callback
      */
-    onComponentRemoved<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (oldValue: ComponentTypes[ComponentName], entity: Entity<ComponentTypes>) => void): () => void;
+    onComponentRemoved<ComponentName extends keyof ComponentTypes>(componentName: ComponentName, handler: (ctx: {
+        value: ComponentTypes[ComponentName];
+        entity: Entity<ComponentTypes>;
+    }) => void): () => void;
+    onAfterComponentAdded(hook: (entityId: number, componentName: keyof ComponentTypes) => void): () => void;
+    onAfterEntityMutated(hook: (entityId: number) => void): () => void;
+    onAfterComponentRemoved(hook: (entityId: number, componentName: keyof ComponentTypes) => void): () => void;
+    onBeforeEntityRemoved(hook: (entityId: number) => void): () => void;
+    onAfterParentChanged(hook: (childId: number) => void): () => void;
     /**
      * The current monotonic change sequence value.
      * Each markChanged call increments this before stamping.
@@ -80,11 +131,6 @@ export default class EntityManager<ComponentTypes> {
      * @returns The sequence number when last changed, or -1 if never changed
      */
     getChangeSeq<K extends keyof ComponentTypes>(entityId: number, componentName: K): number;
-    /**
-     * Clear all change sequences for an entity
-     * @param entityId The entity ID
-     */
-    clearChangeSeqs(entityId: number): void;
     /**
      * Create an entity as a child of another entity with initial components
      * @param parentId The parent entity ID
@@ -93,80 +139,80 @@ export default class EntityManager<ComponentTypes> {
      */
     spawnChild<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes>;
     /**
      * Set the parent of an entity
-     * @param childId The entity to set as a child
-     * @param parentId The entity to set as the parent
+     * @param childId The entity ID to set as a child
+     * @param parentId The entity ID to set as the parent
      */
     setParent(childId: number, parentId: number): this;
     /**
      * Remove the parent relationship for an entity (orphan it)
-     * @param childId The entity to orphan
+     * @param childId The entity ID to orphan
      * @returns true if a parent was removed, false if entity had no parent
      */
     removeParent(childId: number): boolean;
     /**
      * Get the parent of an entity
-     * @param entityId The entity to get the parent of
+     * @param entityId The entity ID to get the parent of
      * @returns The parent entity ID, or null if no parent
      */
     getParent(entityId: number): number | null;
     /**
      * Get all children of an entity in insertion order
-     * @param parentId The parent entity
+     * @param parentId The parent entity ID
      * @returns Readonly array of child entity IDs
      */
     getChildren(parentId: number): readonly number[];
     /**
      * Get a child at a specific index
-     * @param parentId The parent entity
+     * @param parentId The parent entity ID
      * @param index The index of the child
      * @returns The child entity ID, or null if index is out of bounds
      */
     getChildAt(parentId: number, index: number): number | null;
     /**
      * Get the index of a child within its parent's children list
-     * @param parentId The parent entity
-     * @param childId The child entity to find
+     * @param parentId The parent entity ID
+     * @param childId The child entity ID to find
      * @returns The index of the child, or -1 if not found
      */
     getChildIndex(parentId: number, childId: number): number;
     /**
      * Get all ancestors of an entity in order [parent, grandparent, ...]
-     * @param entityId The entity to get ancestors of
+     * @param entityId The entity ID to get ancestors of
      * @returns Readonly array of ancestor entity IDs
      */
     getAncestors(entityId: number): readonly number[];
     /**
      * Get all descendants of an entity in depth-first order
-     * @param entityId The entity to get descendants of
+     * @param entityId The entity ID to get descendants of
      * @returns Readonly array of descendant entity IDs
      */
     getDescendants(entityId: number): readonly number[];
     /**
      * Get the root ancestor of an entity (topmost parent), or self if no parent
-     * @param entityId The entity to get the root of
+     * @param entityId The entity ID to get the root of
      * @returns The root entity ID
      */
     getRoot(entityId: number): number;
     /**
      * Get siblings of an entity (other children of the same parent)
-     * @param entityId The entity to get siblings of
+     * @param entityId The entity ID to get siblings of
      * @returns Readonly array of sibling entity IDs
      */
     getSiblings(entityId: number): readonly number[];
     /**
      * Check if an entity is a descendant of another entity
-     * @param entityId The potential descendant
-     * @param ancestorId The potential ancestor
+     * @param entityId The potential descendant ID
+     * @param ancestorId The potential ancestor ID
      * @returns true if entityId is a descendant of ancestorId
      */
     isDescendantOf(entityId: number, ancestorId: number): boolean;
     /**
      * Check if an entity is an ancestor of another entity
-     * @param entityId The potential ancestor
-     * @param descendantId The potential descendant
+     * @param entityId The potential ancestor ID
+     * @param descendantId The potential descendant ID
      * @returns true if entityId is an ancestor of descendantId
      */
     isAncestorOf(entityId: number, descendantId: number): boolean;

package/dist/event-bus.d.ts

@@ -17,7 +17,12 @@ export default class EventBus<EventTypes> {
      * Internal method to add an event handler
      */
     private addHandler;
-    publish<E extends keyof EventTypes>(eventType: E, data?: EventTypes[E]): void;
+    /**
+     * Publish an event. Data is required unless EventTypes[E] extends void | undefined.
+     * Zero-allocation hot path: uses index-based iteration with a snapshot length
+     * so handlers added mid-publish are not called in the same publish cycle.
+     */
+    publish<E extends keyof EventTypes>(...[eventType, data]: EventTypes[E] extends void | undefined ? [eventType: E, data?: EventTypes[E]] : [eventType: E, data: EventTypes[E]]): void;
     clear(): void;
     clearEvent<E extends keyof EventTypes>(eventType: E): void;
 }

package/dist/index.d.ts

@@ -1,21 +1,14 @@
 import ECSpresso from './ecspresso';
-import { SystemBuilder } from './system-builder';
-import Bundle, { mergeBundles } from './bundle';
+import { SystemBuilder, type ProcessContext } from './system-builder';
+import { type Plugin, type BasePluginOptions, definePlugin } from './plugin';
 export * from './types';
 export * from './asset-types';
 export * from './screen-types';
+export * from './utils/math';
 export type { ReactiveQueryDefinition } from './reactive-query-manager';
-export { default as EntityManager } from './entity-manager';
-export { default as EventBus } from './event-bus';
-export { default as CommandBuffer } from './command-buffer';
-export { default as HierarchyManager } from './hierarchy-manager';
-/**
- * @internal ResourceManager is exported for testing purposes only.
- * Use ECSpresso resource methods instead: getResource(), addResource(), removeResource(), updateResource(), hasResource()
- */
-export { default as ResourceManager } from './resource-manager';
 export { default as AssetManager, createAssetConfigurator } from './asset-manager';
 export { default as ScreenManager, createScreenConfigurator } from './screen-manager';
-export { SystemBuilder };
-export { Bundle, mergeBundles };
+export { SystemBuilder, type ProcessContext };
+export { type Plugin, type BasePluginOptions, definePlugin };
+export { directValue, type ResourceDirectValue } from './resource-manager';
 export default ECSpresso;

package/dist/plugin.d.ts

@@ -0,0 +1,61 @@
+import type ECSpresso from './ecspresso';
+import type { SystemPhase } from './types';
+import type { WorldConfig, EmptyConfig, MergeConfigs, AnyECSpresso, ConfigOf } from './type-utils';
+/**
+ * Plugin interface for ECSpresso. A plugin is a plain object with an `install`
+ * function that configures a world directly, plus phantom properties for
+ * compile-time type extraction.
+ *
+ * @typeParam Cfg - The WorldConfig this plugin provides (components, events, resources, etc.)
+ * @typeParam Requires - The WorldConfig this plugin requires from other plugins
+ */
+export interface Plugin<Cfg extends WorldConfig = EmptyConfig, Requires extends WorldConfig = EmptyConfig, Labels extends string = never, Groups extends string = never, AssetGroupNames extends string = never, ReactiveQueryNames extends string = never> {
+    readonly id: string;
+    readonly install: (world: ECSpresso<MergeConfigs<Cfg, Requires>>) => void;
+    readonly _cfg?: Cfg;
+    readonly _requires?: Requires;
+    readonly _labels?: Labels;
+    readonly _groups?: Groups;
+    readonly _assetGroupNames?: AssetGroupNames;
+    readonly _reactiveQueryNames?: ReactiveQueryNames;
+}
+/**
+ * Common configuration options shared by most plugins.
+ * Plugin-specific options interfaces extend this with additional fields.
+ */
+export interface BasePluginOptions<G extends string = string> {
+    /** System group name for all systems registered by this plugin */
+    systemGroup?: G;
+    /** Priority for the plugin's primary system (default varies per plugin) */
+    priority?: number;
+    /** Execution phase for the plugin's primary system */
+    phase?: SystemPhase;
+}
+/**
+ * Factory function to create a type-safe Plugin with phantom type parameters.
+ * The type assertion adds phantom types without runtime cost.
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Explicit config type param
+ * const myPlugin = definePlugin<WorldConfigFrom<MyComponents, MyEvents, MyResources>>({
+ *   id: 'my-plugin',
+ *   install(world) { ... },
+ * });
+ *
+ * // Option 2: Single world type param (extracts config automatically)
+ * type MyWorld = typeof ecs;
+ * const myPlugin = definePlugin<MyWorld>({
+ *   id: 'my-plugin',
+ *   install(world) { ... },
+ * });
+ * ```
+ */
+export declare function definePlugin<W extends AnyECSpresso, Requires extends WorldConfig = EmptyConfig, Labels extends string = never, Groups extends string = never, AssetGroupNames extends string = never, ReactiveQueryNames extends string = never>(config: {
+    id: string;
+    install: (world: W) => void;
+}): Plugin<ConfigOf<W>, Requires, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
+export declare function definePlugin<Cfg extends WorldConfig = EmptyConfig, Requires extends WorldConfig = EmptyConfig, Labels extends string = never, Groups extends string = never, AssetGroupNames extends string = never, ReactiveQueryNames extends string = never>(config: {
+    id: string;
+    install: (world: ECSpresso<MergeConfigs<Cfg, Requires>>) => void;
+}): Plugin<Cfg, Requires, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;

package/dist/plugins/audio.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Audio Plugin for ECSpresso
+ *
+ * Web Audio API integration via Howler.js for sound effects and music playback.
+ * User-defined channels with type-safe volume control, hybrid resource + component API,
+ * and asset manager integration.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { AssetsOfWorld, AnyECSpresso, ChannelOfWorld } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+import type { Howl } from 'howler';
+/**
+ * Configuration for a single audio channel.
+ */
+export interface AudioChannelConfig {
+    readonly volume: number;
+}
+/**
+ * Define audio channels with type-safe names and initial volumes.
+ * Mirrors `defineCollisionLayers` pattern.
+ *
+ * @param channels Object mapping channel names to their configuration
+ * @returns Frozen channel configuration with inferred channel name union
+ *
+ * @example
+ * ```typescript
+ * const channels = defineAudioChannels({
+ *   sfx: { volume: 1 },
+ *   music: { volume: 0.7 },
+ *   ui: { volume: 0.8 },
+ * });
+ * type Ch = ChannelsOf<typeof channels>; // 'sfx' | 'music' | 'ui'
+ * ```
+ */
+export declare function defineAudioChannels<const T extends Record<string, AudioChannelConfig>>(channels: T): Readonly<T>;
+/**
+ * Extract channel name union from a `defineAudioChannels` result.
+ */
+export type ChannelsOf<T> = T extends Record<infer K extends string, AudioChannelConfig> ? K : never;
+/**
+ * Audio source component attached to entities for positional/entity-bound audio.
+ */
+export interface AudioSource<Ch extends string = string> {
+    /** Asset key for the sound */
+    readonly sound: string;
+    /** Channel this sound plays on */
+    readonly channel: Ch;
+    /** Individual volume (0-1) */
+    volume: number;
+    /** Whether sound loops */
+    loop: boolean;
+    /** Remove entity when sound ends (like timer autoRemove) */
+    autoRemove: boolean;
+    /** Whether sound is currently playing (system-managed) */
+    playing: boolean;
+    /** Howler sound ID (system-managed, -1 = not started) */
+    _soundId: number;
+}
+/**
+ * Component types provided by the audio plugin.
+ */
+export interface AudioComponentTypes<Ch extends string = string> {
+    audioSource: AudioSource<Ch>;
+}
+/**
+ * Event to trigger fire-and-forget sound playback from any system.
+ */
+export interface PlaySoundEvent<Ch extends string = string> {
+    /** Asset key for the sound */
+    sound: string;
+    /** Channel to play on */
+    channel?: Ch;
+    /** Individual volume (0-1) */
+    volume?: number;
+    /** Whether sound loops */
+    loop?: boolean;
+}
+/**
+ * Event to stop music on a channel.
+ */
+export interface StopMusicEvent<Ch extends string = string> {
+    /** Channel to stop music on. If omitted, stops all music. */
+    channel?: Ch;
+}
+/**
+ * Event published when a sound finishes playing.
+ */
+export interface SoundEndedEvent {
+    /** Entity ID if sound was entity-attached, -1 for fire-and-forget */
+    entityId: number;
+    /** Howler sound ID */
+    soundId: number;
+    /** Asset key of the sound */
+    sound: string;
+}
+/**
+ * Event types provided by the audio plugin.
+ */
+export interface AudioEventTypes<Ch extends string = string> {
+    playSound: PlaySoundEvent<Ch>;
+    stopMusic: StopMusicEvent<Ch>;
+    soundEnded: SoundEndedEvent;
+}
+/**
+ * Play options for fire-and-forget sound effects.
+ */
+export interface PlayOptions<Ch extends string = string> {
+    /** Channel to play on (uses first defined channel if omitted) */
+    channel?: Ch;
+    /** Individual volume (0-1, default: 1) */
+    volume?: number;
+    /** Whether to loop (default: false) */
+    loop?: boolean;
+}
+/**
+ * Music playback options.
+ */
+export interface MusicOptions<Ch extends string = string> {
+    /** Channel to play music on (uses first defined channel if omitted) */
+    channel?: Ch;
+    /** Volume (0-1, default: 1) */
+    volume?: number;
+    /** Whether to loop (default: true) */
+    loop?: boolean;
+}
+/**
+ * Audio state resource providing fire-and-forget SFX and music control.
+ * Effective volume = individual * channel * master.
+ */
+export interface AudioState<Ch extends string = string> {
+    /** Play a fire-and-forget sound effect. Returns the Howler sound ID. */
+    play(sound: string, options?: PlayOptions<Ch>): number;
+    /** Stop a specific sound by its Howler sound ID. */
+    stop(soundId: number): void;
+    /** Play music on a channel. Stops any existing music on that channel first. */
+    playMusic(sound: string, options?: MusicOptions<Ch>): void;
+    /** Stop music on a channel. If omitted, stops all music. */
+    stopMusic(channel?: Ch): void;
+    /** Pause music on a channel. If omitted, pauses all music. */
+    pauseMusic(channel?: Ch): void;
+    /** Resume music on a channel. If omitted, resumes all music. */
+    resumeMusic(channel?: Ch): void;
+    /** Set volume for a channel (0-1). */
+    setChannelVolume(channel: Ch, volume: number): void;
+    /** Get current volume for a channel. */
+    getChannelVolume(channel: Ch): number;
+    /** Set master volume (0-1). */
+    setMasterVolume(volume: number): void;
+    /** Get current master volume. */
+    getMasterVolume(): number;
+    /** Mute all audio. */
+    mute(): void;
+    /** Unmute all audio. */
+    unmute(): void;
+    /** Toggle mute state. */
+    toggleMute(): void;
+    /** Check if audio is muted. */
+    isMuted(): boolean;
+}
+/**
+ * Resource types provided by the audio plugin.
+ */
+export interface AudioResourceTypes<Ch extends string = string> {
+    audioState: AudioState<Ch>;
+}
+/**
+ * Configuration options for the audio plugin.
+ */
+export interface AudioPluginOptions<Ch extends string, G extends string = 'audio'> extends BasePluginOptions<G> {
+    /** Channel definitions from defineAudioChannels */
+    channels: Readonly<Record<Ch, AudioChannelConfig>>;
+}
+/**
+ * Create an audioSource component for entity-attached audio.
+ *
+ * @param sound Asset key for the sound
+ * @param channel Channel to play on
+ * @param options Optional configuration
+ * @returns Component object suitable for spreading into spawn()
+ *
+ * @example
+ * ```typescript
+ * ecs.spawn({
+ *   ...createAudioSource('explosion', 'sfx'),
+ *   ...createTransform(100, 200),
+ * });
+ * ```
+ */
+export declare function createAudioSource<Ch extends string>(sound: string, channel: Ch, options?: {
+    volume?: number;
+    loop?: boolean;
+    autoRemove?: boolean;
+}): Pick<AudioComponentTypes<Ch>, 'audioSource'>;
+/**
+ * Create a loader function for use with the asset manager.
+ * Returns a factory function that loads a Howl when called.
+ *
+ * @param src URL(s) for the sound file
+ * @param options Optional Howl configuration
+ * @returns Factory function compatible with asset manager's loader parameter
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withAssets(a => a
+ *     .add('explosion', loadSound('/sounds/explosion.mp3'))
+ *     .add('bgm', loadSound(['/sounds/bgm.webm', '/sounds/bgm.mp3']))
+ *   )
+ *   .build();
+ * ```
+ */
+export declare function loadSound(src: string | string[], options?: {
+    html5?: boolean;
+    preload?: boolean;
+}): () => Promise<Howl>;
+/**
+ * Create an audio plugin for ECSpresso.
+ *
+ * Provides:
+ * - `audioState` resource for fire-and-forget SFX and music
+ * - `audioSource` component for entity-attached sounds
+ * - Volume hierarchy: individual * channel * master
+ * - `playSound` / `stopMusic` event handlers
+ * - `soundEnded` event on completion
+ * - Automatic cleanup on entity removal (dispose callback)
+ *
+ * Sounds must be preloaded through the asset pipeline (`loadSound` helper).
+ *
+ * @example
+ * ```typescript
+ * const channels = defineAudioChannels({
+ *   sfx: { volume: 1 },
+ *   music: { volume: 0.7 },
+ * });
+ *
+ * const ecs = ECSpresso.create()
+ *   .withAssets(a => a.add('explosion', loadSound('/sfx/boom.mp3')))
+ *   .withPlugin(createAudioPlugin({ channels }))
+ *   .build();
+ *
+ * await ecs.initialize();
+ * const audio = ecs.getResource('audioState');
+ * audio.play('explosion', { channel: 'sfx' });
+ * ```
+ */
+export declare function createAudioPlugin<Ch extends string, G extends string = 'audio'>(options: AudioPluginOptions<Ch, G>): Plugin<WorldConfigFrom<AudioComponentTypes<Ch>, AudioEventTypes<Ch>, AudioResourceTypes<Ch>>, EmptyConfig, 'audio-sync', G, never, 'audio-sources'>;
+/**
+ * Typed helpers for the audio plugin.
+ * Creates helpers that validate sound keys and channel names against the world type W.
+ * Call after .build() using typeof ecs.
+ *
+ * @template W - Concrete ECS world type (e.g. `typeof ecs`)
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createAudioPlugin({ channels }))
+ *   .withAssets(a => a.add('boom', loadSound('/sfx/boom.mp3')))
+ *   .build();
+ *
+ * const { createAudioSource } = createAudioHelpers<typeof ecs>();
+ * // Type-safe: 'boom' must be a registered asset, 'sfx' a valid channel
+ * createAudioSource('boom', 'sfx');
+ * ```
+ */
+export interface AudioHelpers<W extends AnyECSpresso> {
+    createAudioSource: (sound: keyof AssetsOfWorld<W> & string, channel: ChannelOfWorld<W>, options?: {
+        volume?: number;
+        loop?: boolean;
+        autoRemove?: boolean;
+    }) => Pick<AudioComponentTypes<ChannelOfWorld<W>>, 'audioSource'>;
+}
+export declare function createAudioHelpers<W extends AnyECSpresso>(_world?: W): AudioHelpers<W>;