Initial Commit

openspec/archive/2026-05-15-enterprise-audio-timeline/tasks.md

@@ -0,0 +1,112 @@
+# Tasks: enterprise-audio-timeline
+
+**Change ID**: enterprise-audio-timeline
+**Package**: `@suaveplan/audio-timeline`
+**Target path**: `packages/audio/audio-timeline`
+**Prerequisite packages on Verdaccio**: `@suaveplan/audio-core`, `@suaveplan/undo`, `@suaveplan/fsm`, `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/types`
+
+---
+
+## 1. Scaffold
+
+- [x] Create directory `packages/audio/audio-timeline/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
+- [x] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/audio-core workspace:^`, `@suaveplan/undo workspace:^`, `@suaveplan/fsm workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `zod catalog:forms`.
+- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
+- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
+- [x] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
+
+---
+
+## 2. Types + errors
+
+- [x] Write `src/engine/engine.types.ts` — `TimelineEngineOptions`, `TimelineState`, `FadeCurve`, `TimelineEventMap`.
+- [x] Write `src/track/track.types.ts` — `Track`.
+- [x] Write `src/clip/clip.types.ts` — `Clip`.
+- [x] Write `src/adapter/adapter.types.ts` — `TimelineAdapter`.
+- [x] Write co-located `.md` files for each types module (≥200 words).
+- [x] Write `src/error-codes.ts` — `TimelineErrorCode`, `AUDIO_TIMELINE_ERROR_METADATA`, `registerTimelineErrorCodes()`.
+- [x] Write Zod schemas: `TrackSchema`, `ClipSchema`, `TimelineStateSchema`, `TimelineEngineOptionsSchema`.
+
+---
+
+## 3. Track module
+
+- [x] Implement `src/track/track.ts` — track CRUD helpers: `createTrack`, `updateTrack`, `removeTrack`, `validateTrack`.
+- [x] Write `track.test.ts` and `track.md`.
+
+---
+
+## 4. Clip module
+
+- [x] Implement `src/clip/clip.ts` — clip helpers: `createClip`, `validateClip`, `canSplitAt`, `constrainBoundaryTrim`.
+- [x] Write `clip.test.ts` and `clip.md`.
+
+---
+
+## 5. Operations
+
+- [x] Implement `src/operations/clip-operations.ts` — `moveClip`, `splitClip`, `trimClip`, `constrainClipDrag`, `constrainBoundaryTrim` with overlap and `minDuration` guards.
+- [x] Implement `src/operations/timeline-operations.ts` — `setSelection`, `setLoopRegion`, `setZoomLevel`, `zoomIn`, `zoomOut`.
+- [x] Write `clip-operations.test.ts`, `timeline-operations.test.ts`, and both `.md` files.
+
+---
+
+## 6. Adapter interface
+
+- [x] Implement `src/adapter/adapter.ts` — `NullTimelineAdapter` for tests (no-op implementation of `TimelineAdapter`).
+- [x] Write `adapter.test.ts` and `adapter.md`.
+
+---
+
+## 7. Mixer
+
+- [x] Implement `src/mixer/mixer.ts` — `MixerState`, `setMasterVolume`, `setTrackVolume`, `setTrackMute`, `setTrackSolo`, `setTrackPan`, solo-group logic (non-soloed tracks gain = 0 when any track is soloed).
+- [x] Write `mixer.test.ts` and `mixer.md`.
+
+---
+
+## 8. Zoom
+
+- [x] Implement `src/zoom/zoom.ts` — zoom level table, `zoomIn`, `zoomOut`, `setZoomLevel`, `canZoomIn`, `canZoomOut`.
+- [x] Write `zoom.test.ts` and `zoom.md`.
+
+---
+
+## 9. TimelineEngine
+
+- [x] Implement `TimelineEngine` in `src/engine/engine.ts`:
+  - Constructor with `TimelineEngineOptions`, optional adapter.
+  - `getState()` returns immutable `TimelineState` snapshot.
+  - Track methods delegate to track module and push undo commands via `@suaveplan/undo` `CommandStack`.
+  - Clip methods delegate to clip-operations; no-op drags do not push undo.
+  - Playback methods delegate to adapter; FSM guards state transitions via `@suaveplan/fsm`.
+  - Undo/redo: `undo()`, `redo()`, `beginTransaction()`, `commitTransaction()`, `abortTransaction()`.
+  - Incremental adapter updates: on undo/redo, if track count is unchanged call `adapter.updateTrack()` per changed track instead of `adapter.setTracks()`.
+  - Events: typed `on`/`off` via `@suaveplan/events` for `play`, `pause`, `stop`, `seek`, `trackChange`, `clipChange`, `tempoChange`, `loopChange`, `selectionChange`, `zoomChange`.
+  - `dispose()` closes adapter and clears history.
+- [x] Write `engine.test.ts` (≤500 lines): init, play/pause/stop, add/remove track, add/move/split/trim clip, undo/redo round-trip, transaction abort.
+- [x] Write `engine.md`.
+
+---
+
+## 10. Benchmarks
+
+- [x] Write `src/__benchmarks__/timeline.bench.ts` — create 50 tracks, add 200 clips, perform 100 undo/redo cycles.
+
+---
+
+## 11. Integration tests
+
+- [x] Write `tests/integration.test.ts` — full timeline lifecycle: create tracks, add clips, playback state transitions, undo/redo round-trip, adapter incremental update verification.
+
+---
+
+## 12. Docs + verify + publish
+
+- [x] All co-located `.md` files (≥200 words each).
+- [x] Write `README.md` at package root.
+- [x] `bunx turbo lint typecheck test --filter=@suaveplan/audio-timeline` — green.
+- [x] `bunx turbo test:coverage --filter=@suaveplan/audio-timeline` — 100%.
+- [x] `bun scripts/publish.ts --package @suaveplan/audio-timeline`.
+- [x] Fold `specs/audio-timeline/spec.md` into `openspec/specs/audio-timeline/spec.md`.
+- [x] Archive to `openspec/archive/2026-05-14-enterprise-audio-timeline/`.