@codexo/exojs 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to ExoJS are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-04-26
+
+Pre-1.0 versioning reset. The active development line moves from `2.1.2` to `0.4.0` to honestly reflect that the public API is not yet stable. No runtime behavior change relative to the previous head — this release marks a versioning policy shift, not a code rewrite.
+
+### Notes
+
+- The `2.x` releases (`2.0.0`, `2.1.0`, `2.1.1`, `2.1.2`) remain published on npm as a historical line and will be deprecated with a pointer to the `0.x` line.
+- New work happens on the `0.x` line. Expect breaking changes between `0.x` minors as the scene graph, renderer, and resource boundaries continue to evolve.
+- `1.0.0` will mark the first stable public API contract. Until then, treat any minor version as potentially breaking and pin exact versions in downstream experiments.
+- Past CHANGELOG entries for `2.x` are preserved below as the historical record of work that landed in those releases.
+
+## [2.1.2] - 2026-04-19
+
+Patch release with one runtime fix, a toolchain modernization pass, and a legacy-artifact cleanup. No public API removals or renames.
+
+### Fixed
+
+- **`Signal.dispatch` skipped sibling `once()` handlers.** `once()` wrappers self-remove mid-iteration, which compacts the underlying bindings array; the `for..of` iterator then advanced past the binding that shifted into the just-visited slot. `dispatch` now iterates a snapshot of bindings, so handler-driven mutation is safe. Visible symptom: the Audio Visualisation example received a set-up `Music` but an un-set-up `AudioAnalyser`, so frequency buffers stayed at zero.
+
+### Changed
+
+- Removed the legacy bundled declaration file `dist/exo.d.ts` (emitted via `tsc --outFile` + `module: amd`, both deprecated in TypeScript 6). Modern consumers resolve types through `exports["."].types`, which points at the per-file tree in `dist/esm/`; `dist/exo.d.ts` was never part of the `exports` map. This also removes the `ignoreDeprecations: "6.0"` escape hatch from the build.
+- Build upgraded to TypeScript 6, ESLint 10, Jest 30. Internal imports now use the `@/*` path alias (mapped to `src/*`) and `baseUrl` is no longer required.
+
+## [2.1.1] - 2026-04-19
+
+Patch release fixing a cluster of WebGPU and scene-graph bugs discovered after 2.1.0 shipped. No public API removals or renames; one backward-compatible addition on `Container.addChild`.
+
+### Fixed
+
+- **WebGPU adapter ordering.** `WebGpuRenderManager` now requests the GPU adapter before acquiring the canvas WebGPU context. A null adapter previously locked the canvas into WebGPU mode, preventing `Application`'s automatic WebGL2 fallback from obtaining a context on the same element.
+- **WebGL2 shader program binding.** `WebGl2ShaderRuntime.sync()` now binds the program before writing uniforms. The previous draw pipeline never called `bindShader(shader)` with a non-null shader, so every `uniform*` write targeted the wrong or null program and `drawElements` reported "no valid shader program in use". Exposed by the WebGPU adapter fallback above.
+- **WGSL multi-texture sprite shader** uses `textureSampleGrad` with explicit screen-space derivatives. `textureSample`'s uniformity requirement prevented the 8-slot dispatch from compiling on any sprite batch spanning more than one texture slot.
+- **Sprite index buffer** allocation and lifecycle. Buffer size was 4× larger than intended (`indexData.byteLength * BYTES_PER_ELEMENT` instead of `indexData.byteLength`), and `_ensureBatchCapacity` ran inside the draw loop and could destroy a buffer the render pass had already bound. Capacity is now grown once up front.
+- **Sprite multi-batch rendering.** When a flush contained multiple batches (blend-mode change, texture-slot overflow, or pipeline switch), each batch's `queue.writeBuffer(vertexBuffer, offset: 0, ...)` serialised before the single submit, leaving only the last batch's vertex data in the buffer. All batch vertex data is now packed into one CPU buffer at distinct sprite offsets and uploaded once; `drawIndexed` uses `firstIndex` to target each range.
+- **Particle and primitive multi-drawcall rendering.** Same multi-write-to-offset-0 pattern, plus mid-loop `_ensureCapacity` destroying buffers still referenced by the pass. Particle renderer now submits one command buffer per system. Primitive renderer was rewritten: CPU bakes `view * globalTransform` into `vec4` clip-space positions per vertex, pipeline has no bind-group, one render pass per flush with packed vertex/index buffers.
+- **Primitive combine order.** `_combinedTransform.copy(view).combine(global)` produced `global * view` (`Matrix.combine` applies the argument on the left, confirmed by `SceneNode.getGlobalTransform` which chains `local.combine(parent.global)` to yield `parent.global * local`). Swapped to `copy(global).combine(view)` = `view * global`.
+- **WebGPU mipmap generation.** The full-screen downsample triangle's UVs are no longer Y-flipped relative to framebuffer orientation. Every odd mip level was being rendered upside-down, producing a visible sprite flip whenever the view zoomed far enough for the LOD selector to cross an odd/even boundary.
+
+### Added
+
+- `Container.addChild` accepts multiple children via rest args (`addChild(...children)`). The previous single-argument signature silently dropped the tail of `addChild(a, b, c, d)`; callers only saw `a` in the scene graph. Single-child usage stays backward compatible.
+- Doc comment on `ParticleOptions.position` clarifying it is in the owning `ParticleSystem`'s local coordinate space. The shader applies the system's global transform on top, so passing world coordinates double-translates the emitter.
+
+## [2.1.0] - 2026-04-18
+
+Product-readiness release. Additive across assets, game-feel, visuals, performance, optional physics, and WebGPU parity. No public contracts were removed or renamed since v2.0.0.
+
+### Highlights
+
+- Typed asset manifests and bundle loading workflow.
+- `AnimatedSprite` with named clips, loop control, and frame signals.
+- Scene stacking with participation policies, input routing, and fade transitions.
+- View/camera polish: follow with lerp, bounds clamp, zoom, shake.
+- Audio sprites and sound pooling.
+- Visual capability wave: filter pipeline, masking, render passes, cache-as-bitmap, multi-texture batching on the WebGPU backend.
+- Automatic off-screen culling with observable render stats.
+- Optional Rapier physics integration behind an optional peer dependency.
+- WebGPU parity improvements and clearer initialization failure semantics.
+- Docs and examples overhaul; release verification hardening.
+
+### Assets / workflow
+
+- `defineAssetManifest`, `AssetEntry`, and `loadBundle` with progress callbacks.
+- `BundleLoadError` surfaces per-entry failures with the responsible loader token.
+- Strict manifest validation runs at definition time.
+- `CacheStore` + `IndexedDbStore` remain the persistence path; strategy classes (`CacheFirstStrategy`, `NetworkOnlyStrategy`) are exposed for custom pipelines.
+
+### Game-feel
+
+- `AnimatedSprite`: `defineClip`, `setClips`, `play`, `stop`, `loop` override, `onComplete` and `onFrame` signals.
+- `SceneManager` is now a real stack: `pushScene`, `popScene`, `setScene` with resolved `SceneParticipationPolicy` covering stack mode and input mode.
+- `SceneInputEvent` routing honours stack participation so overlay/modal scenes can intercept input cleanly.
+- Fade transitions integrated into scene switching.
+- `View` camera: `follow` with lerp, `setBoundsConstraint`, `zoom`/`setZoom`, `shake` with decay and configurable frequency.
+- `Sound`: `setPoolSize`, `playPooled`, `stopPooled`, `defineSprite`, `setSprites` for audio-sprite playback.
+
+### Rendering / visuals
+
+- Filter pipeline: abstract `Filter` base with `BlurFilter` and `ColorFilter` implementations; per-node filter chains wired through the render runtime.
+- Masking support in both render managers and on `RenderNode`.
+- Render-pass composition: `RenderTargetPass`, `CallbackRenderPass`, `RenderTarget`, and the existing `RenderTexture` for off-screen work.
+- `RenderNode.cacheAsBitmap` flattens expensive subtrees to a cached texture with invalidation.
+- `Container.sortableChildren` + `SceneNode.zIndex` provide depth-sorted rendering with a stable fallback on insertion order.
+- Multi-texture batching on the WebGPU sprite renderer (`textureSlots`, `maxBatchTextures`). See caveat below.
+- WebGPU sprite, particle, and primitive renderers reached functional parity with the WebGL2 equivalents.
+- Context-loss handling preserved.
+
+### Performance
+
+- Automatic off-screen culling: `Drawable` checks `inView(view)` each frame and counts skipped nodes.
+- `RenderStats` exposes `submittedNodes`, `culledNodes`, `drawCalls`, `batches`, `renderPasses`, and `frameTimeMs` for observability.
+- Hot-path cleanup across the renderers.
+- `npm run perf:benchmark` runs the rendering benchmark harness under `test/perf/`.
+
+### Physics
+
+- Optional Rapier integration via `createRapierPhysicsWorld({ gravityY })`.
+- `@dimforge/rapier2d-compat` is declared as an optional `peerDependency`; apps that do not import the physics entry point incur zero runtime cost.
+- Collision groups/masks encoded into Rapier's 16/16 packed format; `PhysicsCollisionFilter` lets you declare membership and what each body collides with.
+- Triggers vs. solid colliders distinguished via `trigger` on the descriptor; `onTriggerEnter` / `onTriggerExit` signals on the body.
+- Transform sync helpers and a `createDebugGraphics`/`updateDebugGraphics` path for debug draw through the existing `Graphics` primitive.
+
+### WebGPU
+
+- Sprite, particle, and primitive renderers now cover the WebGL2 feature surface used by the scene runtime.
+- Explicit `backend: { type: 'webgpu' }` errors out if WebGPU is unavailable or initialization fails — failures are not silently swallowed.
+- `backend: { type: 'auto' }` prefers WebGPU when `navigator.gpu` is present and falls back to WebGL2 only when the WebGPU init path throws.
+- Initialization error paths are now observable through the thrown error rather than partially constructed state.
+
+### Docs / examples
+
+- README rewritten to match the shipped surface.
+- New docs hub under `docs/` with sections for getting-started, core-concepts, assets, scenes, rendering, audio, physics, performance, and examples.
+- New class-focused API pages: `Application`, `Renderer`, `Graphics`, `AnimatedSprite`, `AssetManifests`, `Audio`, `View`, `VisualEffects`, `PhysicsRapier`, `Performance`, `GameFeel`.
+- `examples/` folder contains focused source snippets (`01-quickstart.ts` … `08-physics-rapier.ts`) that are typechecked against the public API via `tsconfig.examples.json`.
+
+### Tooling / release quality
+
+- `npm run typecheck:examples` typechecks the in-repo examples against `src/` to prevent example drift.
+- `npm run verify:exports` validates the package entry graph (`scripts/verify-exports.mjs`).
+- `npm run verify:package` runs build → example typecheck → export verification → `npm pack --dry-run`.
+- `npm run verify:release` is the smallest release gate: typecheck → lint → tests → verify:package.
+- CI runs lint, typecheck, tests, bundle build, declaration build, example typecheck, export verification, and pack dry-run on every PR to `master`.
+
+### Behaviour changes worth knowing
+
+These are minor-level behaviour changes, not source-breaks; flagged here for transparency:
+
+- **Automatic culling**: nodes whose `inView(view)` check is false are no longer submitted and are counted in `RenderStats.culledNodes`. Apps that were already relying on correct bounds see no observable change. If a custom drawable under-reports its bounds, it may now be skipped when it was previously drawn off-screen.
+- **Scene input routing**: with the new stack, input dispatch honours the resolved `SceneInputMode` of each stack entry. Apps that only use `setScene(...)` with no `pushScene` keep single-scene v2.0.0 behaviour.
+- **Explicit WebGPU failures**: `backend: { type: 'webgpu' }` now throws rather than silently picking WebGL2. Apps that want the old "try WebGPU, otherwise WebGL2" behaviour should use `backend: { type: 'auto' }`.
+
+### Known limitations / honest caveats
+
+- **WebGL2 is still single-texture batched.** Multi-texture batching is implemented only in the WebGPU sprite renderer. WebGL2 sprite-heavy scenes will still flush on texture changes.
+- **WebGPU is improved, not "production WebGPU".** Treat the WebGPU backend as functional parity with WebGL2 for the features this library ships, not as a general-purpose WebGPU renderer.
+- **Rapier is optional.** If you never import the physics entry point, Rapier is not installed or loaded. It is not bundled with the library.
+- **Tilemaps are not in scope.** There is no built-in tilemap renderer; engines targeting Tiled-centric games should continue to reach for dedicated tooling.
+- **Bitmap fonts are not shipped.** `Text` renders via Canvas with stroke support; `BitmapText` is not included.
+- **No tween library.** Animation curves and tween orchestration are left to consumer code or external libraries.
+- **Audio remains Web Audio decoded/streaming with pooling and sprites.** Spatial audio (`PannerNode`), effects (`ConvolverNode`, `BiquadFilterNode`, `DynamicsCompressorNode`), and fade helpers are not part of this release.
+- **Particles are still CPU-simulated.** The WebGPU particle renderer is a rendering path, not a GPU compute simulator.
+- **Graphics: no gradients, patterns, caps/joins, or dashing.** Basic fills and strokes only.
+- **Input gaps unchanged from 2.0.0**: no haptics/vibration, no rebinding capture, no gesture library, fixed gamepad dead zones.
+
+### Upgrading from 2.0.0
+
+No code changes are required for typical applications. Review the behaviour-change notes above if your code:
+
+- requests `backend: { type: 'webgpu' }` explicitly and was relying on silent fallback,
+- implements a custom `Drawable` with inexact bounds,
+- pushed multiple scenes via manual orchestration outside `SceneManager`.
+
+## [2.0.0] - previous major
+
+Baseline for the modernized architecture wave (renderer runtime, scene runtime, class-token loader v2, math and rendering contract renames).

package/README.md

@@ -0,0 +1,141 @@
+# ExoJS
+
+ExoJS is a TypeScript-first 2D runtime for browser games and interactive apps. It is designed around explicit scene flow, practical rendering features, and predictable runtime behavior.
+
+## Project status
+
+ExoJS is **pre-1.0**. The public API is still under active design — scene graph, rendering pipeline, and resource lifecycle boundaries may change between minor versions. Pin exact versions in downstream experiments. `1.0.0` will mark the first stable API contract.
+
+## Why ExoJS
+
+- TypeScript-first API surface with strong runtime contracts
+- Scene and asset workflows built for real game loops
+- Modern rendering stack: WebGPU-first with WebGL2 fallback
+- Practical visuals: filters, masks, render passes, cache-as-bitmap
+- Gameplay tools: animated sprites, scene stacking, camera helpers, audio sprites
+- Performance visibility with built-in render stats and benchmark harness
+- Optional Rapier physics integration without forcing physics on every app
+
+## What Is Shipped Today
+
+- `Application`, `Scene`, and scene-manager lifecycle
+- Typed `Loader` with manifest/bundle workflow (`defineAssetManifest`, `registerManifest`, `loadBundle`)
+- Drawables: `Sprite`, `AnimatedSprite`, `Graphics`, `ParticleSystem`, `Text`, `Video`
+- Scene stacking (`overlay` / `modal` / `opaque`) with input routing and fade transitions
+- View/camera helpers (`follow`, bounds clamp, shake, zoom)
+- Rendering composition primitives (`RenderTexture`, `RenderTargetPass`, filter chains, masks, cache-as-bitmap)
+- Render stats (`submittedNodes`, `culledNodes`, `drawCalls`, `batches`, `renderPasses`, ...)
+- Optional Rapier adapter (`createRapierPhysicsWorld`)
+
+## Installation
+
+```bash
+npm install exojs
+```
+
+## Quickstart
+
+```ts
+import { Application, Scene, Graphics, Color, type SceneRenderRuntime } from 'exojs';
+
+class HelloScene extends Scene {
+    private readonly box = new Graphics();
+
+    public constructor() {
+        super();
+
+        this.box.fillColor = Color.white;
+        this.box.drawRectangle(-32, -32, 64, 64);
+        this.box.setPosition(400, 300);
+
+        this.addChild(this.box);
+    }
+
+    public override update(delta: import('exojs').Time): void {
+        this.box.rotation += delta.seconds * 45;
+    }
+
+    public override draw(runtime: SceneRenderRuntime): void {
+        this.root.render(runtime);
+    }
+}
+
+const canvas = document.querySelector('canvas');
+
+if (!canvas) {
+    throw new Error('Missing <canvas> element.');
+}
+
+const app = new Application({
+    canvas,
+    width: 800,
+    height: 600,
+    clearColor: Color.cornflowerBlue,
+});
+
+await app.start(new HelloScene());
+```
+
+## Next Steps
+
+- Documentation hub: [docs/README.md](docs/README.md)
+- Getting started: [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
+- Core concepts: [docs/core-concepts/overview.md](docs/core-concepts/overview.md)
+- Assets and bundles: [docs/assets/loader-and-bundles.md](docs/assets/loader-and-bundles.md)
+- Scenes and stack flow: [docs/scenes/scene-flow.md](docs/scenes/scene-flow.md)
+- Rendering and visuals: [docs/rendering/visual-capabilities.md](docs/rendering/visual-capabilities.md)
+- Audio workflow: [docs/audio/audio-workflow.md](docs/audio/audio-workflow.md)
+- Optional physics: [docs/physics/rapier-integration.md](docs/physics/rapier-integration.md)
+- Performance/debugging: [docs/performance/performance-and-debugging.md](docs/performance/performance-and-debugging.md)
+- API reference: [docs/api/README.md](docs/api/README.md)
+- In-repo examples: [examples/README.md](examples/README.md)
+
+## WebGPU and WebGL2
+
+`Application` defaults to backend auto-selection:
+
+- prefers WebGPU when available
+- falls back to WebGL2 if WebGPU is unavailable or initialization fails
+
+You can force backend selection when needed:
+
+```ts
+new Application({ backend: { type: 'webgpu' } });
+new Application({ backend: { type: 'webgl2' } });
+new Application({ backend: { type: 'auto' } });
+```
+
+## Optional Rapier Physics
+
+Rapier integration is opt-in and loaded only when you use it.
+
+```ts
+import { createRapierPhysicsWorld } from 'exojs';
+
+const physics = await createRapierPhysicsWorld({ gravityY: 9.81 });
+```
+
+If Rapier is unavailable, creation fails with a clear setup error.
+
+## Examples
+
+The runnable live site (Astro + Lit + Monaco preview) lives in [`examples/`](examples/README.md) and is deployed as the repository's GitHub Pages site at <https://exoridus.github.io/ExoJS/>.
+
+## Development
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run verify:package
+npm run perf:benchmark
+```
+
+Internal imports use the `@/*` path alias (mapped to `src/*`) — the same convention used by Vite, Next.js, and other modern TypeScript setups. Building the library requires TypeScript 6.
+
+## Links
+
+- Repository: <https://github.com/Exoridus/ExoJS>
+- Issues: <https://github.com/Exoridus/ExoJS/issues>
+- Changelog: [CHANGELOG.md](CHANGELOG.md)

package/dist/esm/audio/AbstractMedia.d.ts

@@ -0,0 +1,45 @@
+import type { Media } from '@/audio/Media';
+import { Signal } from '@/core/Signal';
+import type { PlaybackOptions } from '@/core/types';
+export interface AbstractMediaInitialState extends Omit<PlaybackOptions, 'time'> {
+    duration: number;
+}
+export declare abstract class AbstractMedia implements Media {
+    readonly onStart: Signal<[]>;
+    readonly onStop: Signal<[]>;
+    protected readonly _duration: number;
+    protected _volume: number;
+    protected _playbackRate: number;
+    protected _loop: boolean;
+    protected _muted: boolean;
+    abstract get paused(): boolean;
+    abstract set paused(paused: boolean);
+    abstract get analyserTarget(): AudioNode | null;
+    get duration(): number;
+    get volume(): number;
+    set volume(volume: number);
+    get loop(): boolean;
+    set loop(loop: boolean);
+    get playbackRate(): number;
+    set playbackRate(playbackRate: number);
+    get currentTime(): number;
+    set currentTime(currentTime: number);
+    get muted(): boolean;
+    set muted(muted: boolean);
+    get progress(): number;
+    get playing(): boolean;
+    set playing(playing: boolean);
+    protected constructor(initialState: AbstractMediaInitialState);
+    abstract play(options?: Partial<PlaybackOptions>): this;
+    abstract pause(options?: Partial<PlaybackOptions>): this;
+    abstract setVolume(volume: number): this;
+    abstract setLoop(loop: boolean): this;
+    abstract setPlaybackRate(playbackRate: number): this;
+    abstract getTime(): number;
+    abstract setTime(time: number): this;
+    abstract setMuted(muted: boolean): this;
+    stop(options?: Partial<PlaybackOptions>): this;
+    toggle(options?: Partial<PlaybackOptions>): this;
+    applyOptions(options?: Partial<PlaybackOptions>): this;
+    destroy(): void;
+}

package/dist/esm/audio/AbstractMedia.js

@@ -0,0 +1,103 @@
+import { Signal } from '../core/Signal.js';
+
+class AbstractMedia {
+    onStart = new Signal();
+    onStop = new Signal();
+    _duration;
+    _volume;
+    _playbackRate;
+    _loop;
+    _muted;
+    get duration() {
+        return this._duration;
+    }
+    get volume() {
+        return this._volume;
+    }
+    set volume(volume) {
+        this.setVolume(volume);
+    }
+    get loop() {
+        return this._loop;
+    }
+    set loop(loop) {
+        this.setLoop(loop);
+    }
+    get playbackRate() {
+        return this._playbackRate;
+    }
+    set playbackRate(playbackRate) {
+        this.setPlaybackRate(playbackRate);
+    }
+    get currentTime() {
+        return this.getTime();
+    }
+    set currentTime(currentTime) {
+        this.setTime(currentTime);
+    }
+    get muted() {
+        return this._muted;
+    }
+    set muted(muted) {
+        this.setMuted(muted);
+    }
+    get progress() {
+        const elapsed = this.currentTime;
+        const duration = this.duration;
+        return ((elapsed % duration) / duration);
+    }
+    get playing() {
+        return !this.paused;
+    }
+    set playing(playing) {
+        if (playing) {
+            this.play();
+        }
+        else {
+            this.pause();
+        }
+    }
+    constructor(initialState) {
+        const { duration, volume, playbackRate, loop, muted } = initialState;
+        this._duration = duration;
+        this._volume = volume;
+        this._playbackRate = playbackRate;
+        this._loop = loop;
+        this._muted = muted;
+    }
+    stop(options) {
+        this.pause(options);
+        this.currentTime = 0;
+        return this;
+    }
+    toggle(options) {
+        return this.paused ? this.play(options) : this.pause(options);
+    }
+    applyOptions(options = {}) {
+        const { volume, loop, playbackRate, time, muted } = options;
+        if (volume !== undefined) {
+            this.volume = volume;
+        }
+        if (loop !== undefined) {
+            this.loop = loop;
+        }
+        if (playbackRate !== undefined) {
+            this.playbackRate = playbackRate;
+        }
+        if (time !== undefined) {
+            this.currentTime = time;
+        }
+        if (muted !== undefined) {
+            this.muted = muted;
+        }
+        return this;
+    }
+    destroy() {
+        this.stop();
+        this.onStart.destroy();
+        this.onStop.destroy();
+    }
+}
+
+export { AbstractMedia };
+//# sourceMappingURL=AbstractMedia.js.map

package/dist/esm/audio/AbstractMedia.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractMedia.js","sources":["../../../../src/audio/AbstractMedia.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/audio/AudioAnalyser.d.ts

@@ -0,0 +1,30 @@
+import type { Media } from '@/audio/Media';
+export interface AudioAnalyserOptions {
+    fftSize: number;
+    minDecibels: number;
+    maxDecibels: number;
+    smoothingTimeConstant: number;
+}
+export declare class AudioAnalyser {
+    private readonly _media;
+    private readonly _fftSize;
+    private readonly _minDecibels;
+    private readonly _maxDecibels;
+    private readonly _smoothingTimeConstant;
+    private readonly _frequencyBinCount;
+    private readonly _timeDomainData;
+    private readonly _frequencyData;
+    private readonly _preciseTimeDomainData;
+    private readonly _preciseFrequencyData;
+    private _analyser;
+    private _audioContext;
+    private _analyserTarget;
+    constructor(media: Media, options?: Partial<AudioAnalyserOptions>);
+    connect(): this;
+    get timeDomainData(): Uint8Array;
+    get frequencyData(): Uint8Array;
+    get preciseTimeDomainData(): Float32Array;
+    get preciseFrequencyData(): Float32Array;
+    destroy(): void;
+    private setupWithAudioContext;
+}

package/dist/esm/audio/AudioAnalyser.js

@@ -0,0 +1,92 @@
+import { isAudioContextReady, getAudioContext, onAudioContextReady } from './audio-context.js';
+
+class AudioAnalyser {
+    _media;
+    _fftSize;
+    _minDecibels;
+    _maxDecibels;
+    _smoothingTimeConstant;
+    _frequencyBinCount;
+    _timeDomainData;
+    _frequencyData;
+    _preciseTimeDomainData;
+    _preciseFrequencyData;
+    _analyser = null;
+    _audioContext = null;
+    _analyserTarget = null;
+    constructor(media, options = {}) {
+        const { fftSize, minDecibels, maxDecibels, smoothingTimeConstant } = options;
+        this._media = media;
+        this._fftSize = fftSize ?? 2048;
+        this._minDecibels = minDecibels ?? -100;
+        this._maxDecibels = maxDecibels ?? -30;
+        this._smoothingTimeConstant = smoothingTimeConstant ?? 0.8;
+        this._frequencyBinCount = this._fftSize / 2;
+        this._timeDomainData = new Uint8Array(this._frequencyBinCount);
+        this._frequencyData = new Uint8Array(this._frequencyBinCount);
+        this._preciseTimeDomainData = new Float32Array(this._frequencyBinCount);
+        this._preciseFrequencyData = new Float32Array(this._frequencyBinCount);
+        if (isAudioContextReady()) {
+            this.setupWithAudioContext(getAudioContext());
+        }
+        else {
+            onAudioContextReady.once(this.setupWithAudioContext, this);
+        }
+    }
+    connect() {
+        if (!this._analyser || this._analyserTarget !== null) {
+            return this;
+        }
+        const analyserTarget = this._media.analyserTarget;
+        if (!analyserTarget) {
+            throw new Error('No AudioNode on property analyserTarget.');
+        }
+        this._analyserTarget = analyserTarget;
+        analyserTarget.connect(this._analyser);
+        return this;
+    }
+    get timeDomainData() {
+        if (this._analyser) {
+            this.connect();
+            this._analyser.getByteTimeDomainData(this._timeDomainData);
+        }
+        return this._timeDomainData;
+    }
+    get frequencyData() {
+        if (this._analyser) {
+            this.connect();
+            this._analyser.getByteFrequencyData(this._frequencyData);
+        }
+        return this._frequencyData;
+    }
+    get preciseTimeDomainData() {
+        if (this._analyser) {
+            this.connect();
+            this._analyser.getFloatTimeDomainData(this._preciseTimeDomainData);
+        }
+        return this._preciseTimeDomainData;
+    }
+    get preciseFrequencyData() {
+        if (this._analyser) {
+            this.connect();
+            this._analyser.getFloatFrequencyData(this._preciseFrequencyData);
+        }
+        return this._preciseFrequencyData;
+    }
+    destroy() {
+        onAudioContextReady.clearByContext(this);
+        this._analyserTarget?.disconnect();
+        this._analyser?.disconnect();
+    }
+    setupWithAudioContext(audioContext) {
+        this._audioContext = audioContext;
+        this._analyser = audioContext.createAnalyser();
+        this._analyser.fftSize = this._fftSize;
+        this._analyser.minDecibels = this._minDecibels;
+        this._analyser.maxDecibels = this._maxDecibels;
+        this._analyser.smoothingTimeConstant = this._smoothingTimeConstant;
+    }
+}
+
+export { AudioAnalyser };
+//# sourceMappingURL=AudioAnalyser.js.map

package/dist/esm/audio/AudioAnalyser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioAnalyser.js","sources":["../../../../src/audio/AudioAnalyser.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/audio/Media.d.ts

@@ -0,0 +1,25 @@
+import type { PlaybackOptions } from '@/core/types';
+export interface Media {
+    readonly duration: number;
+    readonly progress: number;
+    readonly analyserTarget: AudioNode | null;
+    volume: number;
+    loop: boolean;
+    playbackRate: number;
+    currentTime: number;
+    muted: boolean;
+    paused: boolean;
+    playing: boolean;
+    play(options?: Partial<PlaybackOptions>): this;
+    pause(options?: Partial<PlaybackOptions>): this;
+    stop(options?: Partial<PlaybackOptions>): this;
+    toggle(options?: Partial<PlaybackOptions>): this;
+    applyOptions(options: Partial<PlaybackOptions>): this;
+    setVolume(volume: number): this;
+    setLoop(loop: boolean): this;
+    setPlaybackRate(playbackRate: number): this;
+    getTime(): number;
+    setTime(time: number): this;
+    setMuted(muted: boolean): this;
+    destroy(): void;
+}

package/dist/esm/audio/Music.d.ts

@@ -0,0 +1,20 @@
+import type { PlaybackOptions } from '@/core/types';
+import { AbstractMedia } from '@/audio/AbstractMedia';
+export declare class Music extends AbstractMedia {
+    private readonly _audioElement;
+    private _audioSetup;
+    constructor(audioElement: HTMLAudioElement, options?: Partial<PlaybackOptions>);
+    setVolume(value: number): this;
+    setLoop(loop: boolean): this;
+    setPlaybackRate(value: number): this;
+    getTime(): number;
+    setTime(currentTime: number): this;
+    setMuted(muted: boolean): this;
+    get paused(): boolean;
+    set paused(paused: boolean);
+    get analyserTarget(): AudioNode | null;
+    play(options?: Partial<PlaybackOptions>): this;
+    pause(options?: Partial<PlaybackOptions>): this;
+    destroy(): void;
+    private setupWithAudioContext;
+}