# 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/`.