diff --git a/docs/plans/roadmap-themed-sprints-2026-03.md b/docs/plans/roadmap-themed-sprints-2026-03.md new file mode 100644 index 00000000..aea9b6c3 --- /dev/null +++ b/docs/plans/roadmap-themed-sprints-2026-03.md @@ -0,0 +1,98 @@ +# Research Backlog Themed Sprint Roadmap (#942-#975) + +## Scope + +- Sources: + - `origin/claude/research-daw-synths-KU2At:.llm/research/*` + - GitHub issues `#942-#975` + - current `main` code synced on 2026-03-27 +- Goal: + - convert the research backlog into theme-based sprints + - sequence work around shared engine and store dependencies + - keep implementation reviewable through small, testable PRs + +## Planning Principles + +- Ship data model and engine primitives before surface-level UI. +- Preserve dual-surface parity: every sprint must add or extend `window.__store` actions in addition to visual controls. +- Prefer PR slices that touch one interaction family at a time and land with browser-testable workflows. +- Keep dark-theme quality, keyboard access, and agent automation coverage in every sprint, not only at the end. +- Treat issues `#970`, `#974`, and `#975` as trust multipliers: they improve first-run confidence and should progress in parallel with core audio work. + +## Dependency Summary + +| Sprint | Theme | Issues | Depends On | Planned PRs | +|---|---|---|---|---| +| 01 | Synth Foundation | `#942 #943 #944 #945 #946 #953 #964` | none | 4 | +| 02 | Sampling, Drum Rack, and Render Pipeline | `#948 #949 #950 #951 #952 #958 #961` | 01 | 4 | +| 03 | Mixer, Device Graph, and Routing | `#957 #959 #965 #969` | 01 | 4 | +| 04 | MIDI, Rhythm, and Automation Editors | `#967 #968 #973` | 01, 03 | 3 | +| 05 | Arrangement and Recording Workflows | `#966 #972` | 02, 04 | 3 | +| 06 | Onboarding, Library, and Accessibility | `#970 #971 #975` | none | 3 | +| 07 | Collaboration, Cloud, and Project Lifecycle | `#974` | 06 | 4 | +| 08 | Advanced Sound Design Lab | `#947 #954 #955 #956 #960 #962 #963` | 01, 02, 03 | 4 | + +## Execution Lanes + +### Lane A — Audio Platform + +- Sprint 01 +- Sprint 02 +- Sprint 03 +- Sprint 08 + +### Lane B — Editing Workflows + +- Sprint 04 +- Sprint 05 + +### Lane C — Experience and Trust + +- Sprint 06 +- Sprint 07 + +## Recommended Order + +1. Land Sprint 01 first to replace preset-only instrument assumptions with a real instrument state model. +2. Start Sprint 06 in parallel once Sprint 01 is underway, because onboarding/accessibility mostly avoids audio-engine conflict. +3. Run Sprint 02 and Sprint 03 after Sprint 01 because both need richer instrument and effect schemas. +4. Start Sprint 04 once Sprint 03 has automation-arm and device parameter hooks available. +5. Start Sprint 05 after Sprint 02 and Sprint 04 so recording, comping, and clip operations share the new render and editor primitives. +6. Start Sprint 07 after Sprint 06 so first-run and project-library UX do not diverge from cloud and share-player flows. +7. Keep Sprint 08 last because it depends on the synth, sampler, routing, and modulation foundations from Sprints 01-03. + +## Branch and PR Conventions + +- Sprint branches: + - `feat/v0.0.x-sprint-01-synth-foundation` + - `feat/v0.0.x-sprint-02-sampling-drum-render` + - `feat/v0.0.x-sprint-03-mixer-device-routing` + - `feat/v0.0.x-sprint-04-midi-rhythm-automation` + - `feat/v0.0.x-sprint-05-arrangement-recording` + - `feat/v0.0.x-sprint-06-onboarding-library-accessibility` + - `feat/v0.0.x-sprint-07-collaboration-cloud` + - `feat/v0.0.x-sprint-08-advanced-sound-design` +- PR naming: + - `feat: sprint 01 PR1 instrument state model` + - `feat: sprint 03 PR2 device chain UX` + - `feat: sprint 06 PR1 accessible control primitives` + +## Done Criteria For Every Sprint + +- `npx tsc --noEmit` +- `npm run build` +- targeted Vitest coverage for the new engine/store surface +- at least one browser workflow covering human interaction and one `window.__store` workflow covering agent interaction +- no new console noise outside explicit error handlers +- updated docs/plans for any scope change discovered during implementation + +## Sprint Documents + +- [Sprint 01 — Synth Foundation](./sprint-01-synth-foundation.md) +- [Sprint 02 — Sampling, Drum Rack, and Render Pipeline](./sprint-02-sampling-drum-render.md) +- [Sprint 03 — Mixer, Device Graph, and Routing](./sprint-03-mixer-device-routing.md) +- [Sprint 04 — MIDI, Rhythm, and Automation Editors](./sprint-04-midi-rhythm-automation.md) +- [Sprint 05 — Arrangement and Recording Workflows](./sprint-05-arrangement-recording.md) +- [Sprint 06 — Onboarding, Library, and Accessibility](./sprint-06-onboarding-library-accessibility.md) +- [Sprint 07 — Collaboration, Cloud, and Project Lifecycle](./sprint-07-collaboration-cloud.md) +- [Sprint 08 — Advanced Sound Design Lab](./sprint-08-advanced-sound-design.md) diff --git a/docs/plans/sprint-01-synth-foundation.md b/docs/plans/sprint-01-synth-foundation.md new file mode 100644 index 00000000..c1363cdc --- /dev/null +++ b/docs/plans/sprint-01-synth-foundation.md @@ -0,0 +1,86 @@ +# Sprint 01 — Synth Foundation + +## User Stories + +- As a producer, I want every instrument track to expose editable synth parameters, so that I can shape sounds instead of swapping only preset names. +- As a producer, I want subtractive and FM synth building blocks to behave like real DAW instruments, so that ACE-Step can cover bread-and-butter bass, lead, pad, and keys workflows. +- As an AI agent, I want synth state to be represented in the project store instead of hidden inside Tone instances, so that I can automate instrument design through `window.__store`. + +## Problem + +- Issues `#942 #943 #944 #945 #946 #953 #964` all describe expected baseline synth behavior, but the current app still treats instruments as a preset string plus a fixed Tone setup. +- The backlog mixes UI asks with engine asks, yet the real blocker is missing instrument state and routing primitives. + +## Root Cause + +- `src/types/project.ts:7-13` models instruments as `TrackType` plus a `SynthPreset` string, which cannot represent oscillator, filter, modulation, or engine-specific state. +- `src/engine/SynthEngine.ts:10-52` hardcodes six preset branches on `Tone.PolySynth(Tone.Synth)` and never persists parameter snapshots. +- `src/engine/SynthEngine.ts:66-139` caches one synth per track keyed only by preset, so changing a single parameter would currently require replacing the whole instance. +- `src/components/pianoroll/PianoRoll.tsx:122-155` and `src/components/pianoroll/PianoRoll.tsx:224-260` expose sampler config and editor toolbar state, but there is no synth editor surface or store-backed synth parameter UI. + +## Solution + +### Deliverables + +- Introduce a track-level `instrument` model that separates engine kind from preset label. +- Add a subtractive synth schema with oscillator, amp envelope, filter, filter envelope, LFO, and unison settings. +- Add an FM synth schema with at least carrier/modulator ratio, level, waveform, and modulation index. +- Build a synth editor panel with visual envelope sections and collapsible advanced controls. +- Add preset snapshots backed by factory JSON plus IndexedDB user presets. + +### Issue Map + +- `#942` synth parameter editing baseline +- `#943` filter envelope +- `#944` routeable LFO +- `#945` unison/detune +- `#946` FM instrument +- `#953` preset browser/save/load +- `#964` visual synth editor + +### Proposed PR Slices + +1. `feat: add track instrument state model and migration` + - extend `src/types/project.ts` + - add store migration/helpers in `src/store/projectStore.ts` + - expose agent-safe actions in `src/main.tsx` +2. `feat: add subtractive synth parameter engine and editor essentials` + - update `src/engine/SynthEngine.ts` + - add synth editor component under `src/components/pianoroll/` + - support `#942` and `#943` +3. `feat: add LFO, unison, and FM engine support` + - implement `#944 #945 #946` + - add visual status/routing previews +4. `feat: add preset browser and user preset persistence` + - implement `#953 #964` + - ship factory preset JSON and IndexedDB user presets + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/engine/__tests__/SynthEngine.test.ts src/store/__tests__/projectStore.test.ts` +- add E2E coverage: + - create a piano-roll track + - change oscillator, filter, envelope, and preset in UI + - verify the same state through `window.__store.getState().project` +- manual workflow: + - create Bass patch + - duplicate track + - switch duplicate to FM Bell + - save and reload project + - confirm both instruments restore correctly + +## Files To Touch + +- `docs/plans/sprint-01-synth-foundation.md` +- `src/types/project.ts` +- `src/store/projectStore.ts` +- `src/engine/SynthEngine.ts` +- `src/components/pianoroll/PianoRoll.tsx` +- `src/components/pianoroll/` +- `src/main.tsx` +- `src/services/` preset persistence helpers +- `tests/e2e/` +- `src/engine/__tests__/` +- `src/store/__tests__/` diff --git a/docs/plans/sprint-02-sampling-drum-render.md b/docs/plans/sprint-02-sampling-drum-render.md new file mode 100644 index 00000000..071ab5b9 --- /dev/null +++ b/docs/plans/sprint-02-sampling-drum-render.md @@ -0,0 +1,80 @@ +# Sprint 02 — Sampling, Drum Rack, and Render Pipeline + +## User Stories + +- As a producer, I want sampler instruments to use realistic zones, slices, and warp behavior, so that browser-based playback does not feel like a toy pitch shifter. +- As a beat-maker, I want the drum machine to accept my own samples and pad-level shaping, so that I can build real kits instead of only choosing four synthesized kits. +- As a producer and AI agent, I want freeze and bounce workflows to reduce CPU while preserving reversibility, so that large projects stay stable. + +## Problem + +- Issues `#948 #949 #950 #951 #952 #958 #961` all sit on the same missing platform: the app has one-sample playback, synthesized drum pads, and partial bounce primitives, but not a general sample-instrument architecture. + +## Root Cause + +- `src/types/project.ts:57-81` only supports a single `SamplerConfig` buffer with trim and ADSR, and `src/types/project.ts:96-108` only gives each drum pad `sampleKey`, `volume`, and `pan`. +- `src/engine/SamplerEngine.ts:81-220` manages one `AudioBuffer` per track and derives pitch purely from `playbackRate`, which blocks multi-zone, velocity-layer, slice, and pitch-independent stretch workflows. +- `src/engine/DrumEngine.ts:46-220` constructs every drum sound from fixed Tone synth factories instead of per-pad instrument descriptors and effect chains. +- `src/store/projectStore.ts:2292-2385` exposes `freezeTrack`, `unfreezeTrack`, `flattenTrack`, and `bounceInPlace`, but the state model and UX stop short of a complete freeze/unfreeze workflow. +- `src/components/sequencer/DrumMachineEditor.tsx:170-260` only exposes kit selection and per-pad volume details, not sample loading, tuning, or pad processing. + +## Solution + +### Deliverables + +- Replace the single-buffer sampler model with zone-based sampler definitions. +- Add velocity layers, round-robin, and slice maps that remain scriptable through the store. +- Add per-pad sample mode, tune, envelope, filter, drive, and send state to the drum machine. +- Add pitch-independent time stretch and warp markers for sampler clips and slices. +- Complete track freeze/unfreeze/bounce UX on top of the existing offline render hooks. + +### Issue Map + +- `#948` multi-sample zones +- `#949` user sample loading on pads +- `#950` per-pad effects and tuning +- `#951` velocity layers and crossfading +- `#952` audio slice mode +- `#958` warp/time-stretch +- `#961` freeze/bounce track to audio + +### Proposed PR Slices + +1. `feat: add sampler zone model and engine migration` + - zone schema, velocity ranges, round-robin +2. `feat: add drum pad sample mode and per-pad shaping` + - sample loading, choke groups, pad filter/drive/send +3. `feat: add slice mode and warp-ready sample UI` + - transient slicing, manual slices, warp marker model +4. `feat: add freeze-unfreeze workflow and render progress` + - full `#961` UX, store actions, browser tests + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/services/__tests__/bounceInPlace.test.ts src/store/__tests__/drumMachine.test.ts` +- add new unit coverage: + - sampler zone selection by pitch and velocity + - slice-to-MIDI mapping + - freeze/unfreeze persistence +- browser workflows: + - drag a sample onto a drum pad, trigger it, reload project + - load a sample into sampler, create slices, trigger them from piano roll + - freeze a synth track, confirm CPU-saving audio playback, unfreeze it + +## Files To Touch + +- `docs/plans/sprint-02-sampling-drum-render.md` +- `src/types/project.ts` +- `src/store/projectStore.ts` +- `src/engine/SamplerEngine.ts` +- `src/engine/DrumEngine.ts` +- `src/components/pianoroll/QuickSamplerEditor.tsx` +- `src/components/sequencer/DrumMachineEditor.tsx` +- `src/components/pianoroll/` +- `src/hooks/useTransport.ts` +- `src/services/bounceInPlace.ts` +- `src/services/audioFileManager.ts` +- `tests/e2e/` +- `src/store/__tests__/` diff --git a/docs/plans/sprint-03-mixer-device-routing.md b/docs/plans/sprint-03-mixer-device-routing.md new file mode 100644 index 00000000..8456ff0d --- /dev/null +++ b/docs/plans/sprint-03-mixer-device-routing.md @@ -0,0 +1,75 @@ +# Sprint 03 — Mixer, Device Graph, and Routing + +## User Stories + +- As a mixer, I want channel strips and device chains to expose real routing, metering, and insert behavior, so that I can mix inside ACE-Step without treating the mixer as a placeholder. +- As a producer, I want routing-heavy effects such as convolution reverb and sidechain ducking, so that modern mix workflows are possible. +- As an AI agent, I want device parameters and routing choices to exist in store state, so that automated mix flows can modify them safely. + +## Problem + +- Issues `#957 #959 #965 #969` look separate, but they are all symptoms of one limitation: there is no unified device graph between the effect model, mixer surface, and audio routing layer. + +## Root Cause + +- `src/components/mixer/MixerPanel.tsx:12-18` caps inserts and sends at four and two, and `src/components/mixer/MixerPanel.tsx:144-247` renders fixed sections without I/O routing, dB markings, or advanced metering. +- `src/components/mixer/EffectChain.tsx:51-141` encodes effect presets inline and `src/components/mixer/EffectChain.tsx:171-279` renders a basic device card row without rack nesting, A/B states, preset library, or searchable add flow. +- `src/engine/EffectsEngine.ts:97-227` builds linear Tone node chains, ships only algorithmic reverb, and has no first-class effect-rack or sidechain input abstraction. +- `src/engine/EffectsEngine.ts:233-247` rebuilds a single linear chain per track, which is insufficient for parallel racks, convolution branches, and visual routing feedback. + +## Solution + +### Deliverables + +- Introduce a track device graph abstraction that supports serial and parallel chains. +- Upgrade channel strips with RMS plus peak metering, dB scale, insert management, pre/post sends, solo-safe, and simple I/O routing. +- Rebuild the device chain UX with searchable add, collapse, reorder, preset persistence, and rack containers. +- Add convolution reverb and sidechain routing as first-class graph nodes. + +### Issue Map + +- `#957` convolution reverb +- `#959` sidechain routing UI +- `#965` pro-grade mixer panel +- `#969` device-view redesign + +### Proposed PR Slices + +1. `feat: add mixer meter upgrade and channel-strip state` + - RMS/peak meters, dB scale, insert slot expansion +2. `feat: add searchable device chain UX and drag reorder` + - searchable add menu, collapse, preset surface +3. `feat: add convolution reverb and visual processor feedback` + - IR loading, EQ curve, gain reduction meter +4. `feat: add sidechain routing and send-state upgrades` + - sidechain source selector, pre/post send toggle, solo-safe + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/engine/__tests__/effectsEngineNativeNode.test.ts src/store/__tests__/sendsReturns.test.ts tests/unit/StatusBar.test.tsx` +- add new unit coverage: + - device graph serialization + - sidechain routing selection + - convolution preset persistence +- browser workflows: + - create a reverb rack and reorder devices + - set kick as sidechain source for bass compressor + - verify insert count, send toggles, and meter behavior in mixer + +## Files To Touch + +- `docs/plans/sprint-03-mixer-device-routing.md` +- `src/types/project.ts` +- `src/store/projectStore.ts` +- `src/engine/EffectsEngine.ts` +- `src/components/mixer/MixerPanel.tsx` +- `src/components/mixer/EffectChain.tsx` +- `src/components/mixer/EffectCards.tsx` +- `src/components/mixer/LevelMeter.tsx` +- `src/components/ui/Knob.tsx` +- `src/components/mixer/VerticalFader.tsx` +- `src/engine/__tests__/` +- `src/store/__tests__/` +- `tests/e2e/` diff --git a/docs/plans/sprint-04-midi-rhythm-automation.md b/docs/plans/sprint-04-midi-rhythm-automation.md new file mode 100644 index 00000000..3d55f73e --- /dev/null +++ b/docs/plans/sprint-04-midi-rhythm-automation.md @@ -0,0 +1,68 @@ +# Sprint 04 — MIDI, Rhythm, and Automation Editors + +## User Stories + +- As a composer, I want piano-roll editing tools that feel musical instead of merely technical, so that note editing stays fast. +- As a beat-maker, I want Elektron-style step detail and probability controls, so that the drum workflow moves beyond an on/off grid. +- As a producer, I want automation to support recording, drawing, and modulation tools, so that parameter movement is part of composition instead of an afterthought. + +## Problem + +- Issues `#967 #968 #973` are editor issues, but the shared blocker is that note, step, and automation data are all modeled too simply for advanced interactions. + +## Root Cause + +- `src/components/pianoroll/PianoRoll.tsx:27-120` keeps ghost-note visibility and editor mode state locally and does not derive scale-aware behavior from project harmony. +- `src/components/pianoroll/PianoRollCanvas.tsx:178-238` supports note creation and chord stamping, but the drag model is single-note focused and lacks native operations for humanize, legato, strum, and multi-note stretch. +- `src/components/pianoroll/VelocityLane.tsx:19-99` only draws velocity bars; it does not own an interactive editing model for painted velocity curves. +- `src/engine/DrumEngine.ts:11-27` keeps drum steps to `active` plus `velocity`, which cannot represent probability, micro-timing, ratchets, or per-step parameter locks. +- `src/components/timeline/AutomationLaneView.tsx:37-165` renders a simple polyline editor with draggable points but no recording modes, tool palette, curve handles, or automation-arm state. + +## Solution + +### Deliverables + +- Extend piano-roll actions with scale highlight, lock-to-scale, velocity painting, quantize strength, legato, humanize, strum, and multi-note stretch. +- Extend step data with probability, micro-timing, pitch offset, ratchet, and step-length metadata. +- Add automation editor tool state, recording-arm state, curve handles, LFO tool generation, and copy/paste flows. + +### Issue Map + +- `#967` piano-roll UX +- `#968` drum machine step UX +- `#973` automation recording and toolset + +### Proposed PR Slices + +1. `feat: add piano-roll scale, velocity, and transform tools` +2. `feat: add drum step metadata and Elektron-style editing` +3. `feat: add automation arm, draw tools, and LFO generation` + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/store/__tests__/drumMachine.test.ts src/store/__tests__/projectStore.test.ts` +- add new unit coverage: + - quantize-strength math + - legato and humanize transforms + - step probability and micro-timing evaluation + - automation curve and LFO tool generation +- browser workflows: + - create chord notes, apply strum, paint velocity, legato them + - build a drum pattern with step probability and ratchets + - arm a filter parameter and record automation while transport plays + +## Files To Touch + +- `docs/plans/sprint-04-midi-rhythm-automation.md` +- `src/types/project.ts` +- `src/store/projectStore.ts` +- `src/components/pianoroll/PianoRoll.tsx` +- `src/components/pianoroll/PianoRollCanvas.tsx` +- `src/components/pianoroll/VelocityLane.tsx` +- `src/components/sequencer/` +- `src/engine/DrumEngine.ts` +- `src/components/timeline/AutomationLaneView.tsx` +- `src/store/__tests__/` +- `tests/e2e/` diff --git a/docs/plans/sprint-05-arrangement-recording.md b/docs/plans/sprint-05-arrangement-recording.md new file mode 100644 index 00000000..300f3385 --- /dev/null +++ b/docs/plans/sprint-05-arrangement-recording.md @@ -0,0 +1,65 @@ +# Sprint 05 — Arrangement and Recording Workflows + +## User Stories + +- As a producer, I want clip operations and take comping directly on the arrangement, so that editing audio feels like a real DAW workflow. +- As a vocalist or instrumentalist, I want punch ranges, visual count-in, latency feedback, and comp lanes, so that recording sessions are trustworthy. +- As an AI agent, I want arrangement editing and record-state transitions to be explicit store actions, so that end-to-end browser tests can validate them without canvas-only gestures. + +## Problem + +- Issues `#966` and `#972` both depend on a more deliberate arrangement interaction model. The code already contains pieces of take-lane and punch logic, but the user-facing flow is incomplete. + +## Root Cause + +- `src/components/timeline/Timeline.tsx:208-260` focuses on viewport, selection, and drag windows rather than clip-operation commands such as split, duplicate, loop, reverse, and comp actions. +- `src/hooks/useRecording.ts:64-117` and `src/hooks/useRecording.ts:119-201` already accumulate loop and punch takes, but the workflow ends at saving clips and toggling take-lane visibility. +- `src/engine/RecordingEngine.ts:25-169` captures device, monitoring, and level-meter state, but does not expose latency reporting, pre-roll, tuner state, or input clip warnings as a dedicated recording surface. +- `src/store/projectStore.ts:2292-2385` contains freeze/flatten/bounce primitives that can support arrangement clip ops, yet clip-operation shortcuts and comp editing are not organized around those primitives. + +## Solution + +### Deliverables + +- Add arrangement clip commands for split, duplicate, loop, reverse, fade handles, and crossfade behavior. +- Build a recording panel or transport extensions for punch-in/out, pre-roll, latency display, count-in visuals, tuner, and input clip warnings. +- Complete take-lane selection and comp editing on arrangement tracks. + +### Issue Map + +- `#966` timeline clip operations +- `#972` recording UX + +### Proposed PR Slices + +1. `feat: add arrangement clip operations and shortcuts` +2. `feat: add punch, pre-roll, latency, and visual count-in` +3. `feat: add take-lane comp editing and recording polish` + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/store/__tests__/toggleClipMuted.test.ts src/store/__tests__/splitClipAtZeroCrossing.test.ts` +- add new unit coverage: + - clip split/duplicate/loop actions + - punch-range clip placement + - take comp selection +- browser workflows: + - split and duplicate clips from keyboard shortcuts + - record with punch-in/out and visual count-in + - create loop takes and comp the best parts on take lanes + +## Files To Touch + +- `docs/plans/sprint-05-arrangement-recording.md` +- `src/store/projectStore.ts` +- `src/hooks/useRecording.ts` +- `src/engine/RecordingEngine.ts` +- `src/components/timeline/Timeline.tsx` +- `src/components/timeline/TrackLane.tsx` +- `src/components/timeline/ClipBlock.tsx` +- `src/components/layout/Toolbar.tsx` +- `src/components/tracks/TrackHeader.tsx` +- `src/store/__tests__/` +- `tests/e2e/` diff --git a/docs/plans/sprint-06-onboarding-library-accessibility.md b/docs/plans/sprint-06-onboarding-library-accessibility.md new file mode 100644 index 00000000..b266f4f3 --- /dev/null +++ b/docs/plans/sprint-06-onboarding-library-accessibility.md @@ -0,0 +1,71 @@ +# Sprint 06 — Onboarding, Library, and Accessibility + +## User Stories + +- As a new user, I want the first-run path to get me to music in under 30 seconds, so that ACE-Step feels AI-native instead of empty. +- As a creator, I want a modern sample browser with preview, search, and drag-to-timeline, so that discovery stays inside the app. +- As a keyboard or assistive-tech user, I want the DAW surface to be navigable and legible, so that accessibility is built into the core experience. + +## Problem + +- Issues `#970 #971 #975` all affect first impression and trust. Today ACE-Step has useful starter pieces, but they are fragmented and do not yet form a guided, accessible creation flow. + +## Root Cause + +- `src/components/dialogs/NewProjectDialog.tsx:89-152` and `src/components/dialogs/NewProjectDialog.tsx:207-245` provide templates and demo starters, but there is no first-run path selector, progress tracking, or contextual help system. +- `src/components/assets/LoopBrowser.tsx:74-191` supports categories, search, preview, and drag payloads, but it is still a loop library rather than a full sample browser with BPM/key metadata, favorites collections, recent items, or AI sample generation. +- `src/components/ui/Knob.tsx:137-210` and `src/components/mixer/VerticalFader.tsx:110-127` expose partial ARIA but omit `aria-valuetext`, value announcements, and shared accessibility primitives. +- `rg` coverage shows almost no reduced-motion, high-contrast, color-blind, skip-link, or focus-trap infrastructure beyond isolated `aria-live` regions. + +## Solution + +### Deliverables + +- Build a first-run shell with three entry paths: generate, template, blank. +- Promote Loop Browser into a sample browser service with metadata, favorites, recents, preview sync, and AI sample generation entry points. +- Standardize accessible control primitives, skip links, reduced-motion handling, and dialog focus management. + +### Issue Map + +- `#970` first-run onboarding +- `#971` sample browser +- `#975` accessibility + +### Proposed PR Slices + +1. `feat: add accessible control primitives and navigation affordances` + - slider ARIA, skip links, reduced motion, focus management +2. `feat: add sample browser metadata, preview sync, and collections` + - extend current loop library into a real browser +3. `feat: add AI-first onboarding and contextual quick help` + - welcome dialog, template path, help panel, shortcut overlay + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run tests/unit/statusBarControls.test.ts tests/unit/StatusBar.test.tsx` +- add new unit coverage: + - accessible slider attributes + - sample browser filtering and favorites + - first-run state gating +- browser workflows: + - first launch from clean storage + - choose "Generate a Song", complete quick-start + - preview and drag a sample to timeline + - complete the same key actions with keyboard-only navigation + +## Files To Touch + +- `docs/plans/sprint-06-onboarding-library-accessibility.md` +- `src/components/dialogs/NewProjectDialog.tsx` +- `src/components/assets/LoopBrowser.tsx` +- `src/components/assets/LoopBrowserItems.tsx` +- `src/components/ui/Knob.tsx` +- `src/components/mixer/VerticalFader.tsx` +- `src/components/ui/DualRangeSlider.tsx` +- `src/store/uiStore.ts` +- `src/index.css` +- `src/App.tsx` +- `tests/e2e/` +- `tests/unit/` diff --git a/docs/plans/sprint-07-collaboration-cloud.md b/docs/plans/sprint-07-collaboration-cloud.md new file mode 100644 index 00000000..7d5a5d17 --- /dev/null +++ b/docs/plans/sprint-07-collaboration-cloud.md @@ -0,0 +1,67 @@ +# Sprint 07 — Collaboration, Cloud, and Project Lifecycle + +## User Stories + +- As a creator, I want projects to persist in the cloud with version history and share links, so that my work survives beyond one browser instance. +- As a collaborator, I want shared playback and later real-time sync to build on the same project model, so that collaboration does not fork into a separate product. +- As an AI agent, I want cloud and share actions to be explicit APIs, so that automated flows can publish, restore, and validate remote project state. + +## Problem + +- Issue `#974` is larger than one feature. It combines storage, sharing, project organization, version history, MIDI IO, and collaboration foundations. Shipping it safely requires a dedicated lifecycle sprint rather than scattered UI additions. + +## Root Cause + +- `src/services/cloudStorageService.ts:61-190` stores cloud projects in memory and shared projects in `localStorage`, which makes sharing local-only and non-persistent across environments. +- `src/store/collaborationStore.ts:12-74` tracks viewer mode, share token, and collaborator metadata, but has no backend session model, sync transport, or conflict state. +- `src/services/projectStorage.ts:14-119` is optimized for local IndexedDB project storage, not remote version history, folder organization, or shared ownership. +- `src/main.tsx:122-133` exposes sharing helpers for the local share API, but not a remote repository client or cloud action surface. + +## Solution + +### Deliverables + +- Introduce a project repository abstraction with local and remote implementations. +- Add persistent remote save/load/list/version APIs and wire them into the collaboration store. +- Build a version timeline, hosted share-player load path, project organization metadata, and MIDI import/export integration. +- Define the real-time sync foundation as phase two on top of the same repository and session model. + +### Issue Map + +- `#974` collaboration and cloud workflow foundation + +### Proposed PR Slices + +1. `feat: add project repository abstraction and cloud API client` +2. `feat: add cloud save-load-version history UI` +3. `feat: add hosted share player and project organization metadata` +4. `feat: add collaboration session foundation for cursors and track locks` + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- `npx vitest run src/services/__tests__/aceStepApi.test.ts src/store/__tests__/projectStore.test.ts` +- add new unit coverage: + - remote repository adapter behavior + - version-history restore logic + - share-token load flows +- browser workflows: + - save project to cloud, refresh, restore it + - publish a share page and open it in a clean session + - restore an earlier version from the timeline + +## Files To Touch + +- `docs/plans/sprint-07-collaboration-cloud.md` +- `src/services/cloudStorageService.ts` +- `src/store/collaborationStore.ts` +- `src/services/projectStorage.ts` +- `src/services/projectSharingService.ts` +- `src/components/sharing/` +- `src/components/dialogs/ShareDialog.tsx` +- `src/components/dialogs/ProjectListDialog.tsx` +- `src/main.tsx` +- `src/store/projectStore.ts` +- `tests/e2e/` +- `src/services/__tests__/` diff --git a/docs/plans/sprint-08-advanced-sound-design.md b/docs/plans/sprint-08-advanced-sound-design.md new file mode 100644 index 00000000..2c626760 --- /dev/null +++ b/docs/plans/sprint-08-advanced-sound-design.md @@ -0,0 +1,71 @@ +# Sprint 08 — Advanced Sound Design Lab + +## User Stories + +- As a sound designer, I want wavetable, granular, physical, additive, and spectral engines, so that ACE-Step can move beyond “browser DAW” expectations and become distinctive. +- As an expressive performer, I want MPE and a modulation matrix, so that per-note motion and controller input can shape advanced engines naturally. +- As an AI agent, I want advanced sound engines to reuse the same instrument and modulation model from earlier sprints, so that automation and preset generation remain coherent. + +## Problem + +- Issues `#947 #954 #955 #956 #960 #962 #963` are the most differentiated features in the backlog, but they should not land until the core synth, sampler, and routing layers are stable. + +## Root Cause + +- `src/engine/SynthEngine.ts:10-139` currently assumes `Tone.Synth` or simple preset playback and has no engine plug-in boundary for wavetable or physical modeling voices. +- `src/types/project.ts:9-18` and `src/types/project.ts:113-124` lack engine-specific instrument schemas and per-note expression metadata. +- `src/engine/EffectsEngine.ts:97-247` handles simple Tone node chains, but there is no AudioWorklet DSP layer for granular or spectral processors. +- `src/main.tsx:22-92` exposes store state to agents, yet there is no advanced modulation bus or per-note expression surface for those agents to target. + +## Solution + +### Deliverables + +- Add a pluggable instrument-engine boundary on top of Sprint 01’s track instrument state. +- Add a modulation matrix and per-note expression model that can be shared by wavetable and MPE-enabled engines. +- Implement advanced DSP engines in an AudioWorklet-backed layer where real-time FFT or grain scheduling is required. + +### Issue Map + +- `#947` wavetable +- `#954` granular +- `#955` physical modeling +- `#956` modulation matrix +- `#960` MPE +- `#962` additive +- `#963` spectral processing + +### Proposed PR Slices + +1. `feat: add modulation matrix and wavetable engine` +2. `feat: add granular and physical-modeling instruments` +3. `feat: add additive and spectral processor surfaces` +4. `feat: add MPE and per-note expression UI` + +## Verification + +- `npx tsc --noEmit` +- `npm run build` +- add new unit coverage: + - modulation routing math + - wavetable frame selection + - MPE channel allocation + - spectral processor serialization +- browser workflows: + - load wavetable patch and modulate position with LFO + - play granular instrument from a loaded sample + - record MPE gestures and verify per-note expression state + +## Files To Touch + +- `docs/plans/sprint-08-advanced-sound-design.md` +- `src/types/project.ts` +- `src/store/projectStore.ts` +- `src/engine/SynthEngine.ts` +- `src/engine/` +- `src/components/pianoroll/` +- `src/components/mixer/` +- `src/main.tsx` +- `src/services/` +- `src/engine/__tests__/` +- `tests/e2e/`