feat(workspace): Add Storybook docs and interpolation strategy packages

Author: cutterbl

.github/copilot-instructions.md

@@ -0,0 +1,24 @@
+# Copilot Workspace Instructions
+
+## Local Environment
+
+- Operating system: macOS
+- Preferred shell: zsh
+- `rg` (ripgrep) is not available in this environment
+
+## Terminal Command Guidance
+
+- Use `zsh`-compatible commands and syntax.
+- Do not assume `rg` exists.
+- For file discovery, use alternatives such as:
+  - `find . -type f`
+  - `ls -R`
+- For text search, use alternatives such as:
+  - `grep -R "pattern" .`
+  - `grep -Rin "pattern" .`
+
+## Behavior Expectation
+
+- Always adapt command suggestions and scripts to this macOS + zsh setup.
+- If a command example would normally use `rg`, replace it with `find`/`grep` equivalents.
+- Keep documentation synchronized with code changes. When behavior, public APIs, defaults, or workflows change, update the relevant README/docs files in the same change.

.github/instructions/documentation.instructions.md

@@ -0,0 +1,24 @@
+---
+description: 'Use when modifying public behavior, APIs, package exports, configuration, or developer workflows. Keep docs synchronized with code changes.'
+applyTo: '**/*.{ts,tsx,js,jsx,mjs,cjs,json,yml,yaml}'
+---
+
+# Documentation Maintenance
+
+When code changes alter behavior, APIs, configuration, defaults, workflows, or package structure, update relevant documentation in the same change.
+
+## Required actions
+
+- Update package README files when user-facing usage, options, defaults, or examples change.
+- Update docs indexes and per-API docs under `packages/*/docs/` when public exports change.
+- Ensure examples compile conceptually with current constructor signatures and option names.
+- Add or adjust cross-links so new docs are discoverable from related READMEs.
+- If no documentation changes are needed, explicitly state why in the PR or summary.
+
+## Minimum checklist for API-affecting changes
+
+- `packages/core/README.md` reviewed
+- `packages/core/docs/README.md` reviewed
+- `packages/audio-worklet/README.md` reviewed (if worklet behavior is affected)
+- `packages/audio-worklet/docs/README.md` reviewed (if worklet exports are affected)
+- Relevant strategy package README reviewed when interpolation behavior or registration changes

.gitignore

@@ -1,5 +1,6 @@
 node_modules
 dist
+.dist
 .nx
 *.tsbuildinfo
 .idea

AGENTS.md

@@ -1,5 +1,12 @@
 # SoundTouchJS Monorepo
 
+## Local Environment
+
+- OS: macOS
+- Shell: zsh
+- `rg` (ripgrep) is not installed
+- Prefer `find` and `grep` when searching files/content
+
 ## Architecture
 
 Nx monorepo with pnpm workspaces and TypeScript project references.
@@ -32,14 +39,22 @@ pnpm dev                  # Start demo dev server (Vite on port 8080)
 pnpm prettier             # Format all files
 ```
 
+Test execution rule:
+
+- Always run Vitest with `--run` (never watch mode), e.g. `pnpm exec vitest --run`.
+
 Individual project commands:
 
 ```sh
-pnpm nx build core        # Build the library (TSC → packages/core/dist/)
+pnpm nx build core        # Build the library (TSC → packages/core/.dist/)
 pnpm nx build demo        # Build the demo app (Vite → apps/demo/dist/)
 pnpm nx dev demo          # Dev server with HMR
 ```
 
+Package build output convention:
+
+- Publishable packages build to `.dist/` (dot-prefixed) and publish ESM outputs from there.
+
 ## Conventions
 
 - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) with **sentence-case** subjects, enforced by commitlint + husky
@@ -48,11 +63,12 @@ pnpm nx dev demo          # Dev server with HMR
 - Workspace dependency uses `"workspace:*"` protocol (pnpm)
 - CI runs on GitHub Actions (`.github/workflows/main.yml`)
 - Pre-commit hook runs typecheck (skipped in CI via `$CI` env var)
+- Keep docs up to date with code changes: update affected README/docs files whenever public behavior, APIs, defaults, or workflows are changed
 
 ## Do Not
 
 - Do not add comments or docstrings to code unless the logic is non-obvious
 - Do not use CommonJS (`require`/`module.exports`) anywhere
 - Do not use `any` type — use `unknown` with narrowing or proper generics
 - Do not add dependencies to the core library — it has zero runtime dependencies
-- Do not commit `dist/`, `.nx/`, or `*.tsbuildinfo` files
+- Do not commit `.dist/`, `dist/`, `.nx/`, or `*.tsbuildinfo` files

README.md

@@ -4,12 +4,14 @@ A real-time audio processing library for pitch shifting, tempo adjustment, and r
 
 ## Monorepo
 
-This project is an [Nx](https://nx.dev) monorepo managed with [pnpm](https://pnpm.io/) workspaces. It publishes two packages:
+This project is an [Nx](https://nx.dev) monorepo managed with [pnpm](https://pnpm.io/) workspaces. It publishes four packages:
 
-| Package                                                           | npm                                       | Description                                                              |
-| ----------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
-| [`@soundtouchjs/core`](packages/core/README.md)                   | `npm install @soundtouchjs/core`          | Core processing library — `SoundTouch`, `PitchShifter`, buffers, filters |
-| [`@soundtouchjs/audio-worklet`](packages/audio-worklet/README.md) | `npm install @soundtouchjs/audio-worklet` | AudioWorklet implementation with `AudioParam`-based controls             |
+| Package                                                                                      | npm                                                 | Description                                                              |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
+| [`@soundtouchjs/core`](packages/core/README.md)                                              | `npm install @soundtouchjs/core`                    | Core processing library — `SoundTouch`, `PitchShifter`, buffers, filters |
+| [`@soundtouchjs/audio-worklet`](packages/audio-worklet/README.md)                            | `npm install @soundtouchjs/audio-worklet`           | AudioWorklet implementation with `AudioParam`-based controls             |
+| [`@cxing/interpolation-strategy-lanczos`](packages/interpolation-strategy-lanczos/README.md) | `npm install @cxing/interpolation-strategy-lanczos` | Lanczos interpolation strategy plugin (default strategy id: `lanczos8`)  |
+| [`@cxing/interpolation-strategy-linear`](packages/interpolation-strategy-linear/README.md)   | `npm install @cxing/interpolation-strategy-linear`  | Linear interpolation strategy plugin (strategy id: `linear`)             |
 
 A development [demo app](apps/demo/) is included for testing both packages in a browser.
 
@@ -18,7 +20,11 @@ If you are new to Web Audio, start with the demo guide: [apps/demo/README.md](ap
 ## Documentation
 
 - Core package API and concepts: [packages/core/README.md](packages/core/README.md)
+- Core API reference index: [packages/core/docs/README.md](packages/core/docs/README.md)
 - AudioWorklet package API and setup: [packages/audio-worklet/README.md](packages/audio-worklet/README.md)
+- AudioWorklet API reference index: [packages/audio-worklet/docs/README.md](packages/audio-worklet/docs/README.md)
+- SoundTouchNode reference: [packages/audio-worklet/docs/sound-touch-node.md](packages/audio-worklet/docs/sound-touch-node.md)
+- Interpolation strategy plugins: [packages/interpolation-strategy-lanczos/README.md](packages/interpolation-strategy-lanczos/README.md), [packages/interpolation-strategy-linear/README.md](packages/interpolation-strategy-linear/README.md)
 - Beginner Web Audio + demo architecture guide: [apps/demo/README.md](apps/demo/README.md)
 
 ## Quick start
@@ -33,7 +39,7 @@ import { SoundTouchNode } from '@soundtouchjs/audio-worklet';
 const audioCtx = new AudioContext();
 await SoundTouchNode.register(audioCtx, '/soundtouch-processor.js');
 
-const stNode = new SoundTouchNode(audioCtx);
+const stNode = new SoundTouchNode({ context: audioCtx });
 stNode.connect(audioCtx.destination);
 
 const source = audioCtx.createBufferSource();
@@ -47,6 +53,8 @@ source.start();
 
 The audio-worklet package exposes wider real-time control ranges for `pitch`, `tempo`, `rate`, and `playbackRate` than earlier releases. Those controls are intentionally capped to balance flexibility with predictable real-time behavior: more extreme values can increase artifacts, reduce output quality, and make buffer behavior less stable on small AudioWorklet render blocks.
 
+Interpolation defaults to `lanczos8` (Lanczos kernel plugin) in both core and audio-worklet flows. You can opt into `linear` for A/B testing and latency/quality comparisons.
+
 ### PitchShifter (ScriptProcessorNode)
 
 The `@soundtouchjs/core` package provides a higher-level `PitchShifter` class with built-in playback tracking. This uses `ScriptProcessorNode`, which is deprecated but widely supported.
@@ -55,7 +63,11 @@ The `@soundtouchjs/core` package provides a higher-level `PitchShifter` class wi
 import { PitchShifter } from '@soundtouchjs/core';
 
 const audioCtx = new AudioContext();
-const shifter = new PitchShifter(audioCtx, audioBuffer, 16384);
+const shifter = new PitchShifter({
+  context: audioCtx,
+  buffer: audioBuffer,
+  bufferSize: 16384,
+});
 shifter.tempo = 1.2;
 shifter.pitch = 0.9;
 
@@ -68,6 +80,18 @@ shifter.connect(audioCtx.destination);
 
 See each package's README for full API documentation.
 
+### Constructor API change
+
+As of the latest release line, constructor calls use named options objects instead of positional arguments. Example:
+
+```ts
+// before
+// new SoundTouchNode(audioCtx)
+
+// now
+new SoundTouchNode({ context: audioCtx });
+```
+
 ## Development
 
 ### Prerequisites
@@ -95,6 +119,8 @@ Individual project commands via Nx:
 ```sh
 pnpm nx build core           # Build @soundtouchjs/core
 pnpm nx build audio-worklet  # Build @soundtouchjs/audio-worklet
+pnpm nx build @cxing/interpolation-strategy-lanczos
+pnpm nx build @cxing/interpolation-strategy-linear
 pnpm nx test core            # Run core tests
 pnpm nx test audio-worklet   # Run audio-worklet tests
 pnpm nx dev demo             # Dev server with HMR
@@ -120,6 +146,7 @@ The `v0.4` release is a ground-up modernization:
 - **TypeScript**: Full rewrite — strict mode, no `any`, complete type exports
 - **ESM only**: Pure ES modules targeting ES2024 (no CommonJS)
 - **AudioWorklet**: New `@soundtouchjs/audio-worklet` package replaces the [separate AudioWorklet repo](https://github.com/cutterbl/soundtouchjs-audio-worklet)
+- **Interpolation plugin model**: Strategy registry with plugin packages; `lanczos8` as default, `linear` as optional override
 - **ES2024 optimizations**: Resizable `ArrayBuffer` in `FifoSampleBuffer`, scratch buffer reuse, dirty-flag overlap buffers
 - **pnpm workspaces**: Workspace protocol (`workspace:*`) for inter-package dependencies
 - **Tooling**: Vite dev server, Vitest test runner, Prettier formatting, commitlint + husky, GitHub Actions CI, `nx release` for versioning and publishing
@@ -139,16 +166,10 @@ LGPL-3.0 — see [LICENSE](LICENSE) for details.
 
 [I accept cash](https://paypal.me/cutterbl?locale.x=en_US) if you like what's been done.
 
-## In Case You Are Interested
-
-SoundTouchJS is based on the C++ implementation of [Soundtouch](https://www.surina.net/soundtouch/) by Olli Parviainen. The earliest implementation in JavaScript was written by [Ryan Berdeen](https://github.com/also/soundtouch-js) and later expanded by [Jakub Faila](https://github.com/jakubfiala/soundtouch-js). I have further expanded this library into a distributable package, refactored for es2015 development.
-
-This package includes the `getWebAudioNode` utility written by [Adrian Holovaty](https://github.com/adrianholovaty), as well as the user-friendly `PitchShifter` wrapper from [Jakub Faila](https://github.com/jakubfiala/soundtouch-js).
-
 ## Contributors
 
 - [Steve 'Cutter' Blades](https://cutterscrossing.com)
 - [Olli Parviainen](https://www.surina.net/soundtouch/)
-- [Ray Berdeen](http://ryanberdeen.com)
-- [Jakub Faila](http://fiala.space)
+- [Ryan Berdeen](http://ryanberdeen.com)
+- [Jakub Fiala](http://fiala.space)
 - [Adrian Holovaty](http://www.holovaty.com)

apps/demo/README.md

@@ -12,28 +12,34 @@ Web Audio is a graph of connected nodes:
 In this demo, that graph is:
 
 1. Source:
+
 - `AudioBufferSourceNode` in Buffer mode
 - `HTMLAudioElement` (wrapped by `MediaElementAudioSourceNode`) in Element mode
 
 2. Processor:
+
 - `SoundTouchNode` from `@soundtouchjs/audio-worklet`
 
 3. Output control:
+
 - `GainNode` for volume
 
 4. Speakers:
+
 - `audioCtx.destination`
 
 ## Why there are two playback modes
 
 The demo shows two common Web Audio input strategies:
 
 1. Buffer mode:
+
 - You fetch/decode audio into an `AudioBuffer`
 - You create an `AudioBufferSourceNode` to play it
 - Good for precise seeking and custom transport logic
 
 2. Element mode:
+
 - You use a regular `<audio>` element as source
 - Good when you want native media controls or browser buffering behavior
 
@@ -42,21 +48,26 @@ Both modes route through `SoundTouchNode` so pitch and tempo controls are consis
 ## Important Web Audio behavior (newcomer checklist)
 
 1. `AudioContext` starts suspended in many browsers until user interaction.
+
 - That is why the demo calls `audioCtx.resume()` in play paths.
 
 2. `AudioBufferSourceNode` is one-shot.
+
 - After `start()`, you cannot restart the same node.
 - Pause/resume works by creating a new source node and starting from an offset.
 
 3. `createMediaElementSource()` should be done once per media element and context.
+
 - The demo stores `elementSourceNode` and reuses it.
 
 4. Time domains matter.
+
 - `audioCtx.currentTime` is wall-clock time in the audio engine.
 - `pauseOffset` is source time (position in track).
 - With tempo changes, converting between these domains is required for accurate progress/seek.
 
 5. Looping belongs to the source transport.
+
 - Buffer mode: `sourceNode.loop`
 - Element mode: `audioEl.loop`
 - `SoundTouchNode` does processing, not transport lifecycle.
@@ -66,19 +77,23 @@ Both modes route through `SoundTouchNode` so pitch and tempo controls are consis
 The demo uses a recommended pairing:
 
 1. Set source playback speed with transport playback rate:
+
 - Buffer mode: `sourceNode.playbackRate.value = tempo`
 - Element mode: `audioEl.playbackRate = tempo`
 
 2. Mirror that rate to SoundTouch:
+
 - `stNode.playbackRate.value = tempo`
 
 This keeps SoundTouch's pitch compensation aligned with source speed.
 
 3. Apply pitch controls separately:
+
 - `stNode.pitch.value` for continuous ratio
 - `stNode.pitchSemitones.value` for key changes in semitones
 
 4. Set output volume after processing:
+
 - `gainNode.gain.value`
 
 ## Why `preservesPitch = false` is set for HTML audio
@@ -93,12 +108,15 @@ Setting `audioEl.preservesPitch = false` ensures SoundTouch is the single pitch
 Buffer mode tracks three things:
 
 1. `playStartTime`:
+
 - `audioCtx.currentTime` at the moment playback started/resumed
 
 2. `pauseOffset`:
+
 - Source position in seconds where playback should start next
 
 3. `currentTempo`:
+
 - Needed to convert elapsed wall time into elapsed source time
 
 When pausing or changing tempo during playback, the demo does:
@@ -119,18 +137,23 @@ Without wrapped progress, UI would pin at 100% while audio continues looping.
 ## Common mistakes and symptoms
 
 1. Forgot `await SoundTouchNode.register(...)`
+
 - Symptom: node creation fails because processor is unknown.
 
 2. Source playback rate and `stNode.playbackRate` are out of sync
+
 - Symptom: pitch sounds wrong when changing tempo.
 
 3. Reusing a started `AudioBufferSourceNode`
+
 - Symptom: no sound after pause/resume attempt.
 
 4. Not calling `audioCtx.resume()` from a user gesture path
+
 - Symptom: graph appears connected but silent.
 
 5. Leaving `audioEl.preservesPitch` enabled
+
 - Symptom: double pitch handling artifacts.
 
 ## Fast map from concepts to code
@@ -147,3 +170,27 @@ Without wrapped progress, UI would pin at 100% while audio continues looping.
 2. Verify both modes after every change.
 3. Keep comments focused on cause/effect, not UI wording.
 4. If behavior differs between modes, check source-specific APIs first.
+
+## API references
+
+- SoundTouchNode (AudioWorklet main-thread API): [../../packages/audio-worklet/docs/sound-touch-node.md](../../packages/audio-worklet/docs/sound-touch-node.md)
+- AudioWorklet docs index: [../../packages/audio-worklet/docs/README.md](../../packages/audio-worklet/docs/README.md)
+- Core docs index: [../../packages/core/docs/README.md](../../packages/core/docs/README.md)
+
+## Sample buffer A/B toggle
+
+The demo uses circular sample buffers by default and can be switched to FIFO buffers:
+
+1. URL: open the demo with `?sampleBufferType=fifo`
+2. UI: use the "Use FIFO sample buffers" checkbox (it reloads with the query flag)
+
+Default (no query flag) keeps circular sample buffers enabled.
+
+## Interpolation A/B toggle
+
+The demo defaults to Lanczos interpolation (`lanczos8`) and supports a linear override.
+
+1. URL: open the demo with `?interpolationStrategy=linear`
+2. UI: use the "Use linear interpolation" checkbox (it reloads with the query flag)
+
+Unchecked uses default Lanczos behavior. Checked forces linear interpolation for side-by-side listening tests.

apps/demo/index.html

@@ -72,6 +72,16 @@ <h3>SoundTouchJS AudioWorklet Demo</h3>
       <button id="modeBuffer" class="active">AudioBuffer</button>
       <button id="modeElement">Audio Element</button>
     </div>
+    <label style="display: flex; gap: 1rem">
+      <input type="checkbox" id="circularAdapterToggle" />
+      Use FIFO sample buffers (reloads demo)
+    </label>
+    <div id="adapterMode"></div>
+    <label style="display: flex; gap: 1rem">
+      <input type="checkbox" id="interpolationToggle" />
+      Use linear interpolation (reloads demo)
+    </label>
+    <div id="interpolationMode"></div>
     <div id="bufferControls">
       <button id="play" disabled>Play</button>
       <button id="stop">Pause</button>