Merge pull request #60 from boostcampwm-snu-2026-1/docs/59-multi-project-management

docs: plan multi-project management

Author: britle20

PLANS.md

@@ -29,7 +29,7 @@ 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. #50 Arrangement WAV export -> `docs/features/21-arrangement-wav-export.md`
+1. #59 Multi-project management -> `docs/features/22-multi-project-management.md`
 
 ## Planned Milestones
 
@@ -54,8 +54,9 @@ Use this section as the current execution order for agent work. Feature document
 19. Variable hybrid clip length.
 20. Adjustable arrangement length.
 21. Arrangement WAV export.
-22. Project JSON export/import.
-23. Basic effects.
+22. Multi-project management.
+23. Project JSON export/import.
+24. Basic effects.
 
 ## Backlog
 

README.md

@@ -73,6 +73,7 @@ Feature task specs:
 - [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)
+- [22 Multi-project Management](docs/features/22-multi-project-management.md)
 
 ## Initial Roadmap
 
@@ -88,6 +89,7 @@ Feature task specs:
 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.
+13. Manage multiple browser-local projects.
 
 ## Notes
 

docs/architecture.md

@@ -18,6 +18,7 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - 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.
+- Let users create, select, rename, and delete browser-local projects through project-level UI.
 - Use `requestAnimationFrame` for visual playheads where needed.
 - Avoid owning exact audio timing.
 
@@ -27,6 +28,7 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - 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.
+- Store project identity and project metadata separately from runtime UI selection.
 - 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.
@@ -51,6 +53,8 @@ The main rule is separation of concerns: UI rendering, persistence, and audio sc
 - 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.
 - Persist the active browser project and imported sample blobs through IndexedDB.
+- Persist a browser-local project collection when multi-project management exists.
+- Store the active project ID separately from the project document.
 - Export rendered arrangement audio as WAV without storing runtime audio objects in project JSON.
 
 ### Utilities
@@ -92,6 +96,8 @@ Imported browser files are also runtime or persistence-layer data. Project JSON
 
 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.
 
+When multiple local projects exist, each persisted project should have a stable project ID. Imported sample blobs should be scoped to the owning project, for example with a composite key such as `${projectId}:${sampleId}` or an equivalent indexed record shape. Switching projects should stop live playback and preview before replacing app state. Autosave must write to the intended project ID and must not accidentally overwrite another project after a switch.
+
 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/data-model.md

@@ -25,6 +25,8 @@ The initial transport UI range is 60 to 180 BPM. Implementations should validate
 ## Core Entities
 
 - `Project`: top-level serializable project document.
+- `ProjectSummary`: lightweight local project list item.
+- `ProjectCollectionState`: browser-local project collection metadata such as the active project ID.
 - `Track`: a lane that can contain clip instances.
 - `Clip`: reusable musical content. It may be a hybrid MIDI/drum clip or, later, an imported audio clip.
 - `ClipInstance`: placement of a clip on a track in arrangement time.
@@ -36,6 +38,34 @@ The initial transport UI range is 60 to 180 BPM. Implementations should validate
 - `TrackMixerState`: serializable track mixer settings when real mixer routing exists.
 - `MasterMixerState`: serializable master output settings when real mixer routing exists.
 
+## Project Collection
+
+The app should support multiple browser-local projects after the multi-project management feature.
+
+`Project` remains the serializable document for one song or sketch. Each project should have a stable ID and contain the musical data already documented in this file: clips, arrangement tracks, clip instances, arrangement length, loop range, sample metadata, tempo, mixer settings, and related project fields.
+
+Project collection metadata should be stored separately from individual project documents:
+
+```ts
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ProjectCollectionState {
+  activeProjectId: string;
+  projects: ProjectSummary[];
+}
+```
+
+The current implementation may still have one active project in memory at a time. The multi-project feature should make the active project ID serializable browser-local state so a refresh restores the last selected project.
+
+Imported sample blobs are not project JSON. In a multi-project store, imported blob records must be scoped to the owning project so two projects can safely have the same local `sampleId`. A composite key such as `${projectId}:${sampleId}` is acceptable, or the persistence layer may add a `projectId` field and an IndexedDB index if that keeps deletion and migration clearer.
+
+Switching projects should not mutate the outgoing project document except for an intentional save or autosave flush. Runtime UI selection, decoded sample caches, active source nodes, transport state, and audio preview state should be reset or rebuilt for the newly active project.
+
 ## Hybrid Clips
 
 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.

docs/features/22-multi-project-management.md

@@ -0,0 +1,130 @@
+# Feature: 22 Multi-project Management
+
+## Status
+Planned
+
+## Goal
+
+Allow users to manage more than one browser-local project instead of being limited to a single hard-coded active project.
+
+## Context
+
+The current app persists one active project in IndexedDB using a fixed `ACTIVE_PROJECT_ID`. The transport bar displays `Project 1`, and there is no project-level UI for creating, switching, renaming, or deleting separate songs.
+
+Multiple local projects should stay browser-first and lightweight. This feature is not a cloud account system or a file browser. It should extend the existing IndexedDB persistence model so users can keep separate sketches in the same browser profile.
+
+## Scope
+
+Included:
+
+- Store multiple serializable project documents in IndexedDB.
+- Store the active project ID separately from project documents.
+- Restore the last active project on app startup.
+- Add a transport bar project menu that shows the active project name.
+- Support creating a new blank project.
+- Support switching between existing projects.
+- Support renaming the active project.
+- Support deleting a project with confirmation.
+- Stop playback and audio preview before switching projects.
+- Keep imported sample blobs scoped to the owning project so projects cannot collide on sample IDs.
+- Migrate the existing single active project into the multi-project shape where practical.
+
+Excluded:
+
+- Cloud sync or user accounts.
+- Cross-device collaboration.
+- File-system project export/import.
+- Project templates beyond the current default blank project.
+- Project duplication unless it is trivial after the base workflow exists.
+- A full project dashboard page.
+- Sharing projects between browsers or devices.
+
+## Constraints
+
+- Project data must remain serializable.
+- Runtime objects such as `AudioContext`, `AudioBuffer`, `File`, object URLs, active source nodes, and mixer nodes must not be stored in project JSON.
+- Switching projects must not let pending autosave write the old project into the new project ID.
+- Persistence code should stay separate from React rendering and audio scheduling.
+- The audio engine must not depend on IndexedDB or project menu UI.
+- Use CSS Modules and semantic design tokens for project menu UI.
+- Do not introduce a runtime dependency for IndexedDB or menu behavior unless the implementation clearly justifies it.
+
+## Proposed Model
+
+Use a stable project ID per project instead of one fixed `ACTIVE_PROJECT_ID`.
+
+Illustrative shape:
+
+```ts
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ProjectCollectionState {
+  activeProjectId: string;
+  projects: ProjectSummary[];
+}
+```
+
+`PersistedProjectDocument.id` should become the actual project ID. Existing project document fields such as clips, arrangement tracks, clip instances, sample metadata, tempo, mixer state, arrangement length, and loop range remain serializable project data.
+
+Imported sample blob storage should include project ownership. Acceptable first-pass strategies:
+
+- Use a composite blob key such as `${projectId}:${sampleId}`.
+- Or add `projectId` to each imported sample blob record and query/delete by project ID if IndexedDB indexes are added.
+
+The implementation should choose the smaller safe migration path and document it in the PR.
+
+## UI Direction
+
+The project menu belongs in the transport bar near the current project name/save status area.
+
+The first project menu should include:
+
+- Current project name.
+- List of local projects.
+- `New Project`.
+- `Rename Project`.
+- `Delete Project`.
+
+Switching projects should close the menu, stop playback/preview, save or flush the current project state if practical, load the selected project, and reset selection to valid clip/instrument defaults.
+
+## Done when
+
+- Users can create, select, rename, and delete browser-local projects from the transport bar.
+- Refreshing the browser restores the last active project.
+- Each project restores its own clips, arrangement, mixer state, sample metadata, and imported sample blobs.
+- Deleting a project requires confirmation and does not delete another project's sample blobs.
+- Existing single-project IndexedDB data is preserved as an initial project after migration where practical.
+- Autosave writes to the intended project after creating or switching projects.
+- The transport bar displays the active project name from project state, not a hard-coded value.
+- The PR documents any migration limitations.
+
+## Verification
+
+Run:
+
+- `npm run typecheck --if-present`
+- `npm run lint --if-present`
+- `npm run test --if-present`
+- `npm run build --if-present`
+
+Manual check:
+
+- Start from an existing single-project browser profile if possible.
+- Confirm the old project appears as a local project after migration.
+- Create a second project and verify it starts blank.
+- Rename a project and refresh the browser.
+- Switch between projects and confirm clips, arrangement placements, mixer state, and tempo remain separate.
+- Import a WAV file in one project, refresh, and verify the imported audio belongs only to that project.
+- Delete a project and confirm another project still loads correctly.
+
+## PR notes
+
+- Summarize IndexedDB store/key changes.
+- Explain active project ID persistence.
+- Explain imported sample blob scoping and deletion behavior.
+- Mention any unsupported project operations, such as duplication or file export/import.

docs/product.md

@@ -13,12 +13,13 @@ Build a browser-first mini DAW for creating electronic music with short clips. T
 ## Core Workflow
 
 1. Open the browser app.
-2. Create or select a 1-bar clip.
-3. Build a clip with drum events and pitched notes, or import a local WAV file as an audio clip.
-4. Start loop playback and edit while listening.
-5. Place clips on the `SONG` arrangement timeline.
-6. Play the arranged timeline to build a larger song.
-7. Balance arrangement tracks with basic mixer controls.
+2. Create or select a browser-local project.
+3. Create or select a 1-bar clip.
+4. Build a clip with drum events and pitched notes, or import a local WAV file as an audio clip.
+5. Start loop playback and edit while listening.
+6. Place clips on the `SONG` arrangement timeline.
+7. Play the arranged timeline to build a larger song.
+8. Balance arrangement tracks with basic mixer controls.
 
 ## MVP Definition
 
@@ -48,6 +49,7 @@ The MVP is a browser-first 1-bar hybrid clip editor with:
 - Playback timing is stable enough for simple electronic music loops.
 - Users can place clips on an arrangement timeline and hear the placed clips in song order.
 - Users can adjust track and master levels and mute or solo tracks during arrangement playback.
+- Users can keep separate songs or sketches as multiple local browser projects.
 - Project data can be represented as JSON without runtime audio objects.
 - The codebase separates UI rendering, project state, persistence, and audio scheduling.
 - Future contributors can pick up feature specs and implement small, reviewable tasks.

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.
+- Multi-project store operations: unit or integration tests for create, list, rename, delete, active project selection, and migration from the single active project shape.
 - Project autosave/manual restore checks should verify that imported audio metadata and blobs remain separated.
 - Variable hybrid clip length should cover 1, 2, and 4 bar tick lengths, editor grid derivation, shortening behavior, and arrangement default instance length.
 - WAV encoder header, duration, and sample conversion helpers: unit tests.
@@ -83,6 +84,9 @@ tests/unit/utils/tick-time.test.ts
 - Imported audio clip metadata and runtime-cache separation.
 - Imported file persistence limitations across refresh.
 - IndexedDB restore behavior for imported sample metadata and blobs.
+- Multi-project active project migration and restore behavior.
+- Autosave writing to the wrong project after a project switch.
+- Imported sample blob collisions between projects.
 - Project export/import.
 - WAV export duration and missing-source failure behavior.
 - Scheduler timing.
@@ -115,6 +119,7 @@ Manual audio checks should verify:
 - WAV import checks should verify valid WAV import, invalid file rejection, imported clip selection, displayed duration metadata, and clear behavior after refresh when imported file persistence is not implemented.
 - Arrangement placement checks should verify dragging clips into tracks, moving placed clips, deleting placed clips, and playback from `SONG` mode.
 - Imported audio clip arrangement checks should verify clear missing-source behavior after refresh until imported file persistence exists.
+- Multi-project checks should verify creating, renaming, switching, deleting, refreshing, and imported audio isolation across projects.
 
 Use headphones or speakers at a safe volume. Record browser, OS, and device details when reporting audio timing issues.
 

docs/ui-design.md

@@ -156,6 +156,23 @@ Arrangement export should be presented as an explicit command, likely near the e
 - Download a WAV file when export completes.
 - Do not imply MP3 or cloud export support until those features exist.
 
+## Project Menu
+
+Multi-project management should live in the transport bar, near the active project name and save status.
+
+The first project menu should:
+
+- Display the active project name from project state, not a hard-coded label.
+- Open a compact menu or popover from the project-name area.
+- List browser-local projects.
+- Provide `New Project`, `Rename Project`, and `Delete Project` actions.
+- Make project switching explicit and stop playback or preview before replacing app state.
+- Show clear confirmation before deleting a project.
+
+Do not introduce a full dashboard page for the first multi-project feature. Keep the menu compact enough to fit the editor-focused workflow.
+
+Use CSS Modules and semantic design tokens. Inline styles are not expected for this menu because geometry is not tick-derived editor layout.
+
 ## Arrangement Mixer Panel
 
 The mixer should start as a bottom dock inside `SONG` mode, below the arrangement timeline.