Merge pull request #15 from boostcampwm-snu-2026-1/feat/3-drum-step-sequencer

feat: connect drum sequencer to clip model

Author: britle20

PLANS.md

@@ -29,9 +29,8 @@ 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. #5 Lookahead Scheduler -> `docs/features/03-lookahead-scheduler.md` (PR #14 in review)
-2. #3 Drum Step Sequencer -> `docs/features/04-drum-step-sequencer.md`
-3. #2 Basic Piano Roll -> `docs/features/05-basic-piano-roll.md`
+1. #3 Drum Step Sequencer -> `docs/features/04-drum-step-sequencer.md` (PR #15 in review)
+2. #2 Basic Piano Roll -> `docs/features/05-basic-piano-roll.md`
 
 ## Planned Milestones
 

docs/audio-engine.md

@@ -90,6 +90,8 @@ Events at the loop start should play when the loop begins. Events at the loop en
 
 Loop stop clears the scheduler timer and prevents future windows from being scheduled. Events already submitted to Web Audio inside the current schedule-ahead window may still play briefly; keep `scheduleAheadTime` short enough that this limitation remains acceptable for interactive editing.
 
+When the user edits a drum pattern during playback, the UI may update the scheduler's event list without restarting transport. Newly scheduled windows should use the latest serializable drum events. Events already submitted to Web Audio inside the current schedule-ahead window may still reflect the previous pattern because Web Audio scheduled source nodes cannot be unscheduled after `start(when)`.
+
 ## UI Playhead Separation
 
 UI cursor and playhead animation may use `requestAnimationFrame` and read transport position from the audio engine. Visual playhead timing can be approximate. Exact sound timing must come from scheduled Web Audio events.

docs/data-model.md

@@ -28,6 +28,44 @@ Early clips may contain both drum events and note events. This keeps the M1 edit
 
 Later, the model can evolve toward separate drum, MIDI, and audio clip types if arrangement and editing workflows need stronger separation.
 
+## Bundled Drum Sample Naming and Display
+
+Bundled drum sample files live under `public/samples/drums/`.
+
+Use descriptive `.wav` file names with words separated by underscores, for example:
+
+```text
+Fred_Kick_1.wav
+Fred_Closed_Hi-Hat.wav
+```
+
+The app derives sample metadata from the file name:
+
+- Sample IDs are the file stem lowercased with underscores replaced by hyphens.
+- Display names remove `.wav`, replace underscores with spaces, and uppercase the result.
+
+Examples:
+
+- `Fred_Kick_1.wav` -> sample ID `fred-kick-1`, display name `FRED KICK 1`.
+- `Fred_Closed_Hi-Hat.wav` -> sample ID `fred-closed-hi-hat`, display name `FRED CLOSED HI-HAT`.
+
+## Initial Drum Clip Implementation
+
+The initial drum step sequencer stores lane settings and drum hits in the selected hybrid clip. A 16-step grid maps step indices to ticks with `stepIndex * 120`.
+
+The clip stores `drumLanes` as an ordered array. That array controls both visual lane order and the current sample assigned to each lane. Reordering lanes or changing a lane's sample must update serializable clip state, not runtime-only audio state.
+
+Initial drum lanes map to bundled sample IDs:
+
+- `kick` -> `fred-kick-1`
+- `snare` -> `fred-snare-1`
+- `closedHat` -> `fred-closed-hi-hat`
+- `openHat` -> `fred-open-hi-hat`
+
+Drum event IDs are deterministic within a clip using the clip ID, lane ID, and start tick. Runtime playback converts these serializable events into audio engine sample loop events; the project model itself does not store `AudioBuffer` or other Web Audio objects.
+
+When a lane sample changes, existing `DrumEvent` objects for that lane should be updated to the new `sampleId` so playback and project export reflect the visible lane setting.
+
 ## Illustrative Types
 
 These snippets show model intent. Implementation may refine names and fields, but changes to model semantics must update this document.
@@ -61,10 +99,17 @@ export interface Clip {
   id: string;
   name: string;
   lengthTicks: Tick;
+  drumLanes: DrumLaneDefinition[];
   drumEvents: DrumEvent[];
   noteEvents: NoteEvent[];
 }
 
+export interface DrumLaneDefinition {
+  id: "kick" | "snare" | "closedHat" | "openHat";
+  label: string;
+  sampleId: string;
+}
+
 export interface ClipInstance {
   id: string;
   clipId: string;

docs/features/04-drum-step-sequencer.md

@@ -1,7 +1,7 @@
 # Feature: 04 Drum Step Sequencer
 
 ## Status
-Planned
+In Review
 
 ## Goal
 
@@ -18,6 +18,9 @@ Included:
 - Add initial lanes for kick, snare, closed hi-hat, and open hi-hat.
 - Toggle steps on and off.
 - Store events in the clip model using tick positions.
+- Store lane sample assignment and lane order in the clip model.
+- Allow lane sample selection from bundled drum samples.
+- Allow vertical lane reordering.
 - Use CSS Modules for styling.
 - Use semantic buttons for step toggles.
 - Integrate with the existing audio playback/scheduler if already present.
@@ -38,6 +41,7 @@ Excluded:
 ## Done when
 - Users can toggle drum steps for the four initial lanes.
 - Drum events are added to and removed from the selected clip model.
+- Lane sample selection and lane order update the selected clip model.
 - Step buttons have accessible names and visible focus states.
 - Playback integration works if the scheduler exists.
 

docs/ui-design.md

@@ -114,6 +114,22 @@ Inline styles are acceptable for computed editor geometry, including:
 
 Keep static appearance in CSS Modules. Keep dynamic numeric layout derived from ticks, pitch, and grid dimensions.
 
+## Sample Display Names
+
+When displaying bundled drum sample names in the UI, derive the label from the `.wav` file name:
+
+- Remove the `.wav` extension.
+- Replace underscores (`_`) with spaces.
+- Convert the result to uppercase.
+
+Example: `Fred_Kick_1.wav` displays as `FRED KICK 1`.
+
+## Drum Lane Editing
+
+Drum lane names can act as sample selectors. Clicking a lane name may open a compact scrollable list of bundled drum samples. Render this menu as a popover above clipping editor containers when needed so it is not cut off by panel or workspace overflow. Selecting a sample should update the lane's visible label, the lane's `sampleId`, and existing drum events for that lane in serializable clip state.
+
+Drum lanes may be reordered vertically with drag and drop. The visual order should come from the selected clip's ordered `drumLanes` array rather than a hard-coded component order.
+
 ## UI Reference Policy
 
 If a design prototype uses Tailwind, inline styles, or CDN assets, treat it as visual reference only. Convert the design into semantic React components, CSS Modules, and shared CSS variables.