release: promote develop to main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,15 @@
+## Bug
+
+## Steps to reproduce
+
+## Expected behavior
+
+## Actual behavior
+
+## Relevant files or docs
+
+## Done when
+
+## Verification
+
+## Notes

.github/ISSUE_TEMPLATE/feature_task.md

@@ -0,0 +1,22 @@
+## Feature Spec
+Related feature document:
+
+## Goal
+
+## Context
+
+## Scope
+
+Included:
+-
+
+Excluded:
+-
+
+## Constraints
+
+## Done when
+
+## Verification
+
+## Notes

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+## Changes
+
+## Testing
+- [ ] `npm run typecheck`
+- [ ] `npm run lint`
+- [ ] `npm run test`
+- [ ] `npm run build`
+
+## Screenshots
+If UI changed, add screenshots or a short recording.
+
+## Notes / Limitations
+
+## Follow-up

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            echo "No package.json yet; skipping install."
+          fi
+
+      - name: Type check
+        run: |
+          if [ -f package.json ]; then
+            npm run typecheck --if-present
+          else
+            echo "No package.json yet; skipping typecheck."
+          fi
+
+      - name: Lint
+        run: |
+          if [ -f package.json ]; then
+            npm run lint --if-present
+          else
+            echo "No package.json yet; skipping lint."
+          fi
+
+      - name: Test
+        run: |
+          if [ -f package.json ]; then
+            npm run test --if-present
+          else
+            echo "No package.json yet; skipping test."
+          fi
+
+      - name: Build
+        run: |
+          if [ -f package.json ]; then
+            npm run build --if-present
+          else
+            echo "No package.json yet; skipping build."
+          fi

.gitignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+dist-ssr
+coverage
+.vite
+.env
+.env.*
+!.env.example
+.DS_Store
+*.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*

AGENTS.md

@@ -0,0 +1,154 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository is for a browser-based mini DAW built with Vite, React, TypeScript, CSS Modules, and the Web Audio API.
+
+The product is a clip-based electronic music creation tool. The first major milestone is a 1-bar hybrid clip editor with drum step sequencing, basic piano roll editing, and loop playback. Future work may add arrangement editing and desktop packaging with Electron or Tauri, but the initial target is a browser app.
+
+## Repository Layout
+
+Expected source layout after the scaffold task:
+
+- `src/app/`: app shell, providers, root composition.
+- `src/components/`: shared reusable React components.
+- `src/features/`: feature-specific UI and orchestration.
+- `src/audio/`: Web Audio engine, transport, scheduling, sample playback.
+- `src/model/`: serializable project types and model transformations.
+- `src/persistence/`: import, export, storage, and migration helpers.
+- `src/utils/`: pure utilities such as tick/time conversion.
+- `src/styles/`: global CSS, tokens, and shared style primitives.
+- `tests/unit/`: unit tests for utilities, model transformations, scheduler calculations, and other isolated logic.
+- `tests/integration/`: integration tests for multi-module flows when needed.
+- `docs/`: product, architecture, data model, audio, UI, testing, and feature specs.
+
+Preserve the existing structure unless a refactor is clearly required by the task.
+
+## Commands
+
+Use npm unless the repository already clearly uses another package manager.
+
+Intended project commands:
+
+```text
+Install: npm install
+Dev: npm run dev
+Type check: npm run typecheck
+Lint: npm run lint
+Test: npm run test
+Build: npm run build
+```
+
+If these scripts do not exist yet, future scaffold work must add them. CI uses `--if-present` until the Vite scaffold exists.
+
+## Engineering Conventions
+
+- Prefer small, focused, reviewable changes.
+- Keep React UI separate from audio scheduling logic.
+- Do not mix persistence, UI rendering, and audio scheduling in the same module.
+- Keep project data serializable.
+- Store musical time in ticks, not seconds.
+- Use TypeScript types for project data, audio engine APIs, and feature boundaries.
+- Follow `docs/code-conventions.md` for naming, file organization, TypeScript, React, CSS Modules, design tokens, domain naming, tests, and comments.
+- Prefer pure utilities for tick math, model transformations, and scheduler calculations.
+- Do not introduce new production dependencies without a clear reason.
+- Do not rewrite large files unless required.
+- Do not implement unrelated features while working on a feature spec.
+- Do not change the project data model without updating `docs/data-model.md`.
+
+## Audio Rules
+
+- React UI must not own exact audio timing.
+- Schedule audio against `AudioContext.currentTime`.
+- Use a lookahead scheduler for sequenced playback.
+- UI cursors and playheads may use `requestAnimationFrame`, but not for exact audio scheduling.
+- Store musical time in ticks. The documented default PPQ is 480.
+- Do not store `AudioBuffer` objects directly in project JSON.
+- Runtime audio objects such as `AudioContext`, `AudioBuffer`, nodes, and decoded samples belong in audio runtime caches, not serializable project state.
+- Create a new `AudioBufferSourceNode` for each repeated one-shot sample playback.
+- The audio engine should expose a small typed API to the UI.
+
+## CSS Modules Rules
+
+- Use CSS Modules for component styles.
+- Keep global CSS limited to resets, base document styles, and design tokens.
+- Use CSS custom properties for shared colors, spacing, typography, and timing values.
+- Define primitive design tokens first, then define semantic tokens from those primitives.
+- Component CSS Modules should use semantic tokens. Do not reference primitive color, spacing, typography, or radius tokens directly in component styles unless there is a documented exception.
+- Dynamic editor geometry such as note positions, note widths, and grid coordinates may use inline styles when values are computed at runtime.
+- Do not add a visual design system dependency at this stage unless a task explicitly justifies it.
+
+## UI Reference Policy
+
+- If a design prototype uses Tailwind, inline styles, or CDN assets, treat it as visual reference only.
+- Convert visual patterns into CSS Modules and shared CSS variables.
+- Do not add Tailwind or CDN-based styling unless explicitly requested in a feature spec.
+- Inline styles are acceptable for dynamic editor geometry such as note positions, widths, grid coordinates, and velocity heights.
+
+## Testing Rules
+
+- Keep production code under `src/`; place unit tests under `tests/unit/`.
+- Add integration tests under `tests/integration/` only when a task needs multi-module workflow coverage.
+- Do not add an end-to-end test framework or `tests/e2e/` until a feature spec calls for browser flow testing.
+- Keep `tsconfig.test.json` in sync with test locations so `npm run typecheck` checks test files.
+- Do not remove tests or checks to make a task pass.
+
+## Issue Workflow
+
+- Use GitHub Issues as the task queue for feature work, bugs, and larger refactors.
+- Follow `PLANS.md` `Active Issue Order` when choosing the next issue unless the user gives a different priority.
+- Prefer one issue per feature spec or focused bug.
+- Link issues to feature documents under `docs/features/` when applicable.
+- Use branch names that include the issue number when possible:
+  - `feat/<issue-number>-<short-name>`
+  - `fix/<issue-number>-<short-name>`
+  - `docs/<issue-number>-<short-name>`
+- PRs should reference the issue they address.
+- Use `Closes #<issue-number>` only when the PR fully completes the issue.
+- Do not close issues unless the acceptance criteria are met.
+- Do not create duplicate issues. Search existing open issues first when possible.
+- Do not create issues for tiny typo fixes or trivial cleanup unless requested.
+
+## Git and PR Expectations
+
+- Work on a focused branch when possible.
+- Open PRs against `develop` by default unless a maintainer explicitly requests another base branch.
+- Keep commits scoped to the task.
+- Use conventional commit messages when practical.
+- PR summaries should explain what changed, how it was tested, and known limitations.
+- Do not remove tests or checks to make a task pass.
+- Do not merge PRs automatically.
+
+## Constraints and Do-Not Rules
+
+- Do not implement production DAW features unless the active task asks for them.
+- Do not add sample files unless the active task asks for them.
+- Do not add `CHANGELOG.md` for now.
+- Do not store runtime-only audio objects in project JSON.
+- Do not make broad refactors during feature work.
+- Do not introduce new runtime dependencies without documenting why they are needed.
+- Do not couple React components to Web Audio scheduling internals.
+- Do not change documented model semantics without updating the relevant docs.
+
+## Definition of Done
+
+- Requested behavior implemented.
+- Relevant docs updated if needed.
+- TypeScript passes.
+- Lint passes.
+- Tests pass.
+- Production build passes.
+- PR summary includes testing and known limitations.
+
+## Verification
+
+Run applicable checks before opening a PR:
+
+```bash
+npm run typecheck --if-present
+npm run lint --if-present
+npm run test --if-present
+npm run build --if-present
+```
+
+If the project scaffold does not exist yet, record that the npm scripts are not available and that `docs/features/01-project-scaffold.md` must add them.

PLANS.md

@@ -0,0 +1,78 @@
+# Plans
+
+## North Star
+
+Create a browser-first, clip-oriented mini DAW that is useful for making electronic music. The app should favor correct timing, serializable project data, and focused workflows over broad full-DAW scope.
+
+## Current Milestone: Develop to Main Stabilization
+
+The current branch is being prepared for a `develop` to `main` PR. The goal is to make the repository easy to understand, verify, and review at its current prototype stage.
+
+Focus:
+
+- Keep README, plans, and feature docs aligned with the implemented state.
+- Keep the GitHub Issue queue and `Active Issue Order` clean.
+- Verify the standard checks pass before opening release-prep PRs.
+- Avoid adding new product scope during stabilization unless the user explicitly asks for it.
+
+## Active Issue Order
+
+No active implementation issues are queued right now.
+
+When new work is needed, create or update a feature spec under `docs/features/`, create a linked GitHub Issue, and add that issue here in priority order.
+
+## Completed Milestones
+
+1. Project scaffold.
+2. AudioContext and sample playback.
+3. Lookahead scheduler.
+4. Drum step sequencer.
+5. Basic piano roll.
+6. Transport pause/resume and editor playhead.
+7. Pitched instrument selection and Iowa Piano one-shot playback.
+8. Tempo control and live BPM updates.
+9. Arrangement view UI shell.
+10. Sampler advanced sustain.
+11. Sidebar clip and instrument management.
+12. Drum step subdivisions.
+13. Arrangement mixer panel UI shell.
+14. Hybrid clip loop playback.
+15. WAV file import as audio clip.
+16. Arrangement clip placement and playback.
+17. Mixer audio routing and track controls.
+18. IndexedDB project persistence.
+19. Variable hybrid clip length.
+20. Adjustable arrangement length.
+21. Arrangement WAV export.
+22. Multi-project management.
+
+## Planned Milestones
+
+1. Project JSON export/import.
+2. Basic effects.
+3. Custom project-management dialogs to replace browser prompt/confirm flows.
+4. Browser-driven smoke tests with Playwright or an equivalent e2e tool.
+5. Broader manual/audio QA pass before treating the prototype as a stable release.
+
+## Backlog
+
+- Keyboard shortcuts for transport and editing.
+- Basic undo and redo.
+- Velocity editing for drum and note events.
+- Clip duplication.
+- Starter project template.
+- Metronome.
+- Quantize utilities.
+- Swing or groove timing after strict timing is reliable.
+- MIDI file import or export.
+- Improved sampler sustain authoring and tuning UI.
+- More complete effect slots and effect parameter persistence.
+
+## Frozen / Not Now
+
+- Realtime audio recording.
+- VST/plugin support.
+- Cloud sync.
+- Multiplayer collaboration.
+- Advanced audio mastering.
+- Full DAW replacement scope.