Merge pull request #53 from boostcampwm-snu-2026-1/feat/47-indexeddb-project-persistence

feat: persist active project in IndexedDB

Author: britle20

PLANS.md

@@ -29,11 +29,10 @@ 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. #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`
+1. #47 IndexedDB project persistence -> `docs/features/18-indexeddb-project-persistence.md`
+2. #48 Variable hybrid clip length -> `docs/features/19-variable-hybrid-clip-length.md`
+3. #49 Adjustable arrangement length -> `docs/features/20-adjustable-arrangement-length.md`
+4. #50 Arrangement WAV export -> `docs/features/21-arrangement-wav-export.md`
 
 ## Planned Milestones
 

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`.
 
-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.
+IndexedDB persistence may store imported file bytes outside project JSON. After restore, the app passes those persistent blobs back through the audio engine's typed import API so decoded buffers can be rebuilt on demand. The audio engine should not depend on IndexedDB directly. If project metadata references an imported sample whose bytes are unavailable, the engine or feature orchestration should fail clearly instead of silently skipping playback.
 
 ## Imported Audio Clip Playback
 

docs/data-model.md

@@ -131,6 +131,8 @@ The model should keep these concepts separate:
 
 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.
 
+The first IndexedDB persistence implementation stores the active project document separately from imported sample blobs. The project document may include clips, arrangement tracks, clip instances, loop range, sample metadata, tempo, track mixer state, and master mixer state. Imported sample blobs are stored in a blob store keyed by `sampleId` and are not embedded inside the project document.
+
 Illustrative shape:
 
 ```ts
@@ -542,3 +544,5 @@ export interface SamplerEnvelopeMeta {
 `AudioBuffer` and decoded sample data are runtime-only. Project files should reference samples by stable IDs, paths, or metadata. They must not embed `AudioBuffer`, `AudioNode`, object URLs, or decoded sample contents.
 
 Use a runtime sample cache keyed by `sampleId` when playback needs decoded audio.
+
+After restoring an imported audio clip from IndexedDB, the app should decode the stored blob back into the audio engine runtime cache on demand, such as when previewing the clip or starting arrangement playback.

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

@@ -1,7 +1,7 @@
 # Feature: 18 IndexedDB Project Persistence
 
 ## Status
-Planned
+In Review
 
 ## Goal
 

docs/testing.md

@@ -24,6 +24,7 @@ CI uses `--if-present` while the repository is still before the Vite scaffold.
 - Arrangement clip instance creation, movement, deletion, and snapping: unit tests.
 - Arrangement scheduler event expansion from clip instances: unit tests where practical.
 - IndexedDB persistence adapters, migrations, and serialization boundaries: unit or integration tests with mocked storage where practical.
+- Project autosave/manual restore checks should verify that imported audio metadata and blobs remain separated.
 - WAV encoder header, duration, and sample conversion helpers: unit tests.
 - Pitched instrument metadata and sample-zone mapping: unit tests.
 - Tempo control and scheduler tempo update behavior: unit tests where practical.

docs/ui-design.md

@@ -294,6 +294,8 @@ The first audio clip selected view may be a simple placeholder or detail panel:
 
 Use clear copy for limitations. If imported files are not persisted yet, the UI should not imply that they survive refresh or project export.
 
+When IndexedDB persistence is available, imported audio clip details may indicate that the clip is stored locally. The top transport/status area should show minimal project save status such as loading, saving, saved, or save failed.
+
 Future arrangement duration resizing should happen in the arrangement view, not during import. The UI should treat that as non-destructive trimming or clip-instance length editing unless a later time-stretching feature explicitly adds stretch behavior.
 
 ## Sample Display Names