Merge pull request #51 from boostcampwm-snu-2026-1/docs/plan-persistence-length-export-features

docs: plan persistence length and export features

Author: britle20

PLANS.md

@@ -29,8 +29,11 @@ M1 should include:
 
 Use this section as the current execution order for agent work. Feature document numbering describes the planned product sequence, but actual issue order may change as dependencies, review feedback, or implementation risks become clearer.
 
-1. #41 Arrangement clip placement and playback -> `docs/features/16-arrangement-clip-placement-and-playback.md`
-2. #43 Mixer audio routing and track controls -> `docs/features/17-mixer-audio-routing-and-track-controls.md`
+1. #43 Mixer audio routing and track controls -> `docs/features/17-mixer-audio-routing-and-track-controls.md`
+2. #47 IndexedDB project persistence -> `docs/features/18-indexeddb-project-persistence.md`
+3. #48 Variable hybrid clip length -> `docs/features/19-variable-hybrid-clip-length.md`
+4. #49 Adjustable arrangement length -> `docs/features/20-adjustable-arrangement-length.md`
+5. #50 Arrangement WAV export -> `docs/features/21-arrangement-wav-export.md`
 
 ## Planned Milestones
 
@@ -51,10 +54,12 @@ Use this section as the current execution order for agent work. Feature document
 15. WAV file import as audio clip.
 16. Arrangement clip placement and playback.
 17. Mixer audio routing and track controls.
-18. Project export/import.
-19. IndexedDB autosave.
-20. Arrangement data model refinements.
-21. Basic effects.
+18. IndexedDB project persistence.
+19. Variable hybrid clip length.
+20. Adjustable arrangement length.
+21. Arrangement WAV export.
+22. Project JSON export/import.
+23. Basic effects.
 
 ## Backlog
 

README.md

@@ -69,6 +69,10 @@ Feature task specs:
 - [15 WAV File Import as Audio Clip](docs/features/15-wav-file-import-as-audio-clip.md)
 - [16 Arrangement Clip Placement and Playback](docs/features/16-arrangement-clip-placement-and-playback.md)
 - [17 Mixer Audio Routing and Track Controls](docs/features/17-mixer-audio-routing-and-track-controls.md)
+- [18 IndexedDB Project Persistence](docs/features/18-indexeddb-project-persistence.md)
+- [19 Variable Hybrid Clip Length](docs/features/19-variable-hybrid-clip-length.md)
+- [20 Adjustable Arrangement Length](docs/features/20-adjustable-arrangement-length.md)
+- [21 Arrangement WAV Export](docs/features/21-arrangement-wav-export.md)
 
 ## Initial Roadmap
 
@@ -81,7 +85,9 @@ Feature task specs:
 7. Import local WAV files as audio clips.
 8. Place clips on the arrangement timeline and play the arranged song.
 9. Connect mixer faders, mute, solo, and meters to real audio routing.
-10. Add project export/import and persistence features.
+10. Add browser-local project persistence with IndexedDB.
+11. Support longer hybrid clips and adjustable arrangement length.
+12. Render the arrangement to a downloadable WAV file.
 
 ## Notes
 

docs/architecture.md

@@ -15,7 +15,9 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - Display audio state such as stopped, playing, paused, and playhead position.
 - Render song-level UI shells such as arrangement and mixer panels.
 - Let users place, move, select, and delete arrangement clip instances.
+- Let users adjust clip and arrangement lengths through model-backed controls.
 - Dispatch mixer control edits such as volume, mute, solo, and master volume.
+- Trigger save, restore, import, and export workflows through persistence/audio APIs.
 - Use `requestAnimationFrame` for visual playheads where needed.
 - Avoid owning exact audio timing.
 
@@ -24,6 +26,7 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - Define serializable project data types.
 - Store musical time in ticks.
 - Provide pure transformations for creating, editing, duplicating, and deleting clips and events.
+- Store clip length and arrangement length as serializable musical values.
 - Provide pure transformations for creating, moving, and deleting arrangement clip instances.
 - Store serializable mixer settings such as track volume, mute, solo, and master volume when mixer routing exists.
 - Avoid references to Web Audio runtime objects.
@@ -36,6 +39,7 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - Schedule audio against `AudioContext.currentTime`.
 - Schedule arrangement playback from placed clip instances when `SONG` mode is active.
 - Own mixer routing, track gain nodes, master gain, runtime meters, and effect nodes when those features exist.
+- Provide an offline rendering path for arrangement WAV export when that feature exists.
 - Expose a small typed API to the UI and feature code.
 - Never depend on React components.
 
@@ -46,7 +50,8 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - Store sample references by stable IDs or metadata, not decoded buffers.
 - Handle browser file import boundaries for user-provided audio files.
 - Keep `File`, `Blob`, object URL, IndexedDB handles, and decoded audio buffers out of model data.
-- Later, support local storage or IndexedDB.
+- Persist the active browser project and imported sample blobs through IndexedDB.
+- Export rendered arrangement audio as WAV without storing runtime audio objects in project JSON.
 
 ### Utilities
 
@@ -79,12 +84,14 @@ src/
 
 ## Runtime vs Serializable Data
 
-Serializable data includes projects, tracks, clips, clip instances, drum events, note events, sample metadata, tempo, and time signature.
+Serializable data includes projects, tracks, clips, clip instances, drum events, note events, sample metadata, tempo, time signature, clip length, arrangement length, arrangement loop ranges, and mixer settings.
 
 Runtime data includes `AudioContext`, `AudioBuffer`, audio nodes, scheduler timers, decoded sample caches, and currently playing source nodes. Runtime data must not be written into project JSON.
 
 Imported browser files are also runtime or persistence-layer data. Project JSON may reference imported audio by stable sample IDs and metadata such as file name, MIME type, and duration, but it must not embed `File`, `Blob`, object URL, or decoded PCM data.
 
+IndexedDB may store imported sample blobs or bytes outside the project JSON document. The model should reference those blobs by stable sample IDs so the audio engine can rebuild decoded runtime caches after restore.
+
 Mixer settings such as volume, mute, solo, and master volume are serializable project or app-model data once real mixer routing exists. Mixer runtime data, including `GainNode`, `AnalyserNode`, effect nodes, meter buffers, and active routing graphs, belongs to the audio engine runtime and must not be stored in project JSON.
 
 Arrangement placement data is serializable. A placed clip should be represented by a `ClipInstance` with stable IDs, `startTick`, `lengthTicks`, and track membership. Drag state, pointer coordinates, DOM measurements, scheduler timers, decoded buffers, and active audio nodes are runtime-only and must not be persisted.

docs/audio-engine.md

@@ -34,7 +34,7 @@ In the browser implementation, decoded buffers should live in the audio engine r
 
 Imported WAV files should follow the same runtime rule. The file picker may provide a `File` or `Blob`, but the audio engine should only keep decoded buffers in a runtime cache keyed by a stable imported sample ID. Project JSON stores metadata such as file name, MIME type, and duration, not the `File`, `Blob`, object URL, or `AudioBuffer`.
 
-Until IndexedDB or another persistence layer stores imported file bytes, imported audio clips may be session-only. The audio engine should fail clearly if project metadata references an imported sample whose runtime file data is no longer available.
+IndexedDB persistence may store imported file bytes outside project JSON. After restore, the audio engine should rebuild decoded buffers from those persistent blobs on demand. If project metadata references an imported sample whose bytes are unavailable, the engine should fail clearly instead of silently skipping playback.
 
 ## Imported Audio Clip Playback
 
@@ -65,7 +65,7 @@ Arrangement playback should:
 - Respect `clipInstance.lengthTicks` as the visible and playable duration boundary.
 - Keep play, pause, resume, and stop behavior separate from React render timing.
 
-The first arrangement playback implementation may play linearly from tick 0 through the end of the last placed clip instance, then stop. Arrangement loop regions can be added later.
+Arrangement playback should derive its outer bounds from arrangement state, such as `arrangement.lengthBars`, when that state exists. Before adjustable arrangement length exists, a fixed or inferred arrangement range is acceptable if it is documented in the feature PR.
 
 The current first pass reuses the existing lookahead loop scheduler for `SONG` mode by setting a loop range that covers the visible arrangement. This keeps scheduling independent from React and enables pause/resume with the existing transport API, but it is not yet a true one-shot linear song transport. A later transport task should add non-looping arrangement playback that stops at the arrangement end.
 
@@ -75,6 +75,22 @@ Imported audio clips should play at original speed unless a later time-stretchin
 
 Arrangement playback still uses the lookahead scheduler. UI drag state, arrangement DOM geometry, visual playheads, decoded buffers, and active source nodes remain runtime-only.
 
+## Offline WAV Export
+
+Arrangement WAV export should use an offline audio rendering path, not the live React UI or visual playhead.
+
+The first export target should be WAV because the browser can produce it from PCM data without a compressed-audio encoder dependency. A predictable first format is stereo 44.1 kHz 16-bit PCM WAV unless implementation constraints justify another choice in the PR.
+
+Export rendering should:
+
+- Render from arrangement tick 0 through the configured arrangement length.
+- Use the same tick-to-audio-time conversion rules as live playback.
+- Include the clip types, instruments, and mixer routing available at the time of implementation.
+- Block with a clear error when required sample data is missing.
+- Avoid mutating live transport state, active source nodes, or React component state during rendering.
+
+WAV encoding can be a small utility that converts rendered PCM into a Blob. MP3, FLAC, stem export, cloud export, and mastering processors are separate features.
+
 ## Mixer Routing
 
 The first functional mixer should apply to `SONG` arrangement playback. It depends on scheduled sources knowing their arrangement `trackId`.

docs/data-model.md

@@ -8,6 +8,8 @@ For 4/4:
 
 - 1 beat = 480 ticks.
 - 1 bar = 1920 ticks.
+- 2 bars = 3840 ticks.
+- 4 bars = 7680 ticks.
 - 16-step grid step = 120 ticks.
 
 Seconds are derived at playback time from ticks and tempo. Do not store seconds as the primary event position.
@@ -36,10 +38,12 @@ The initial transport UI range is 60 to 180 BPM. Implementations should validate
 
 ## Hybrid Clips
 
-Early clips may contain both drum events and note events. This keeps the M1 editor focused: one 1-bar clip can hold a drum pattern and a piano roll phrase.
+Early clips may contain both drum events and note events. This keeps the M1 editor focused: one clip can hold a drum pattern and a piano roll phrase.
 
 Later, the model can evolve toward separate drum, MIDI, and audio clip types if arrangement and editing workflows need stronger separation.
 
+The initial clip length is 1 bar, represented as `lengthTicks: 1920`. Later clip editing should support 1, 2, and 4 bar hybrid clips by changing `lengthTicks` to 1920, 3840, or 7680 ticks. Event positions and note durations remain tick-based and must stay inside the clip length.
+
 Imported WAV files should use a separate audio clip shape rather than forcing audio file state into the M1 hybrid clip fields.
 
 ## Mixer State
@@ -80,7 +84,7 @@ Effect slots may remain UI placeholders until a basic effects feature introduces
 
 ## M1 Clip Collection and Sidebar Membership
 
-The M1 browser app should maintain an ordered collection of reusable 1-bar hybrid clips. This may live in app-level project state before full export/import exists, but the data itself should be serializable and compatible with the future `Project.clips` field.
+The M1 browser app should maintain an ordered collection of reusable hybrid clips. This may live in app-level project state before full export/import exists, but the data itself should be serializable and compatible with the future `Project.clips` field.
 
 Runtime UI selection, such as `selectedClipId` and the selected sidebar item, may remain app state. The clip list, clip names, drum lane settings, pitched instrument membership, drum events, and note events should be serializable.
 
@@ -121,7 +125,7 @@ The model should keep these concepts separate:
 - Runtime media data: `File`, `Blob`, object URL, decoded `AudioBuffer`, and active source nodes.
 - Future arrangement placement: where a clip instance appears in song time and how long that instance lasts.
 
-Imported file bytes and decoded sample data are not project JSON. Until IndexedDB or another persistence feature stores imported blobs, imported audio clips may be session-only and should be documented in the UI.
+Imported file bytes and decoded sample data are not project JSON. IndexedDB persistence may store imported blobs outside the project document and connect them back through stable sample IDs. Until that persistence feature exists, imported audio clips may be session-only and should be documented in the UI.
 
 Illustrative shape:
 
@@ -158,6 +162,13 @@ The arrangement view places reusable clips on tracks using `ClipInstance` object
 - How long the placed instance lasts in arrangement ticks.
 - Optional source offset for audio clips.
 
+`ArrangementState` owns arrangement-level song settings such as:
+
+- Total arrangement length in bars.
+- Current loop range.
+
+The first adjustable arrangement length feature should default to 16 bars, keep a minimum of 1 bar, and use a practical maximum such as 128 bars. The arrangement ruler, grid, scroll width, loop bounds, playback bounds, and export duration should derive from this state.
+
 `ArrangementLoopRange` owns the current song playback loop boundaries:
 
 - Loop start tick.
@@ -180,6 +191,11 @@ export interface ArrangementLoopRange {
   startTick: Tick;
   endTick: Tick;
 }
+
+export interface ArrangementState {
+  lengthBars: number;
+  loopRange: ArrangementLoopRange;
+}
 ```
 
 The first arrangement placement feature should create, move, select, and delete `ClipInstance` objects without mutating the source `Clip`. Deleting a placed clip from the arrangement removes only that instance. It does not delete the sidebar clip.
@@ -385,6 +401,7 @@ export interface Project {
     denominator: 4;
   };
   ppq: 480;
+  arrangement: ArrangementState;
   tracks: Track[];
   clips: Clip[];
   samples: SampleMeta[];
@@ -436,6 +453,16 @@ export interface ClipInstance {
   sourceOffsetSeconds?: number;
 }
 
+export interface ArrangementState {
+  lengthBars: number;
+  loopRange: ArrangementLoopRange;
+}
+
+export interface ArrangementLoopRange {
+  startTick: Tick;
+  endTick: Tick;
+}
+
 export interface DrumEvent {
   id: string;
   laneId: "kick" | "snare" | "closedHat" | "openHat" | string;

docs/features/18-indexeddb-project-persistence.md

@@ -0,0 +1,81 @@
+# Feature: 18 IndexedDB Project Persistence
+
+## Status
+Planned
+
+## Goal
+
+Persist the user's current project in the browser so a refresh or reopened tab can restore clips, arrangement data, mixer settings, imported sample metadata, and imported sample audio bytes.
+
+## Context
+
+The app is browser-first and project data must remain serializable. Runtime audio objects such as `AudioContext`, `AudioBuffer`, node graphs, object URLs, and decoded sample caches must not be stored in project JSON.
+
+Imported audio files need separate durable storage because object URLs and decoded buffers are session-only. IndexedDB is the first local persistence target.
+
+## Scope
+
+Included:
+
+- Add an IndexedDB persistence layer under `src/persistence/`.
+- Store a versioned project document for the active project.
+- Store imported sample metadata in serializable project state.
+- Store imported sample file bytes or blobs in IndexedDB using stable sample IDs.
+- Restore the last active project on app startup.
+- Rebuild runtime audio caches from stored blobs only when needed.
+- Add debounced autosave for project edits.
+- Show minimal save status, such as saved, saving, or save failed.
+- Add a baseline migration/version field for stored project documents.
+- Handle unavailable storage or quota errors with visible user feedback.
+
+Excluded:
+
+- Cloud sync.
+- User accounts.
+- Multi-device collaboration.
+- A full project browser or multi-project dashboard.
+- File-system project export/import.
+- Final audio rendering/export.
+- Storing `AudioBuffer`, `AudioNode`, `File`, or object URL values in project JSON.
+
+## Constraints
+
+- Keep project JSON serializable.
+- Use stable IDs to connect project sample metadata to IndexedDB blobs.
+- Keep persistence separate from React rendering and audio scheduling.
+- Do not make the audio engine depend on IndexedDB.
+- Do not introduce a runtime dependency unless the implementation clearly needs it and the PR explains why.
+- Tests may use lightweight mocks or adapters for IndexedDB behavior.
+
+## Done when
+
+- Refreshing the browser restores the active project state.
+- Imported WAV clips can still be played after refresh if their blobs were saved successfully.
+- Autosave does not block UI interactions.
+- Save failures are visible and do not corrupt in-memory state.
+- Stored project records include a schema version.
+- Runtime audio caches are rebuilt from persistent data rather than serialized directly.
+
+## Verification
+
+Run:
+
+- `npm run typecheck --if-present`
+- `npm run lint --if-present`
+- `npm run test --if-present`
+- `npm run build --if-present`
+
+Manual check:
+
+- Create or modify a clip.
+- Import a WAV file.
+- Place clips in the arrangement.
+- Refresh the page.
+- Confirm the project, clips, placement, and imported audio references are restored.
+- Confirm the console has no IndexedDB or decoding errors.
+
+## PR notes
+
+- Summarize the IndexedDB stores and schema version.
+- Explain what is persisted and what remains runtime-only.
+- Mention any browser storage limitations or quota behavior.