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

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

• Create directory packages/audio/audio-timeline/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• 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.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/engine/engine.types.ts — TimelineEngineOptions, TimelineState, FadeCurve, TimelineEventMap.
• Write src/track/track.types.ts — Track.
• Write src/clip/clip.types.ts — Clip.
• Write src/adapter/adapter.types.ts — TimelineAdapter.
• Write co-located .md files for each types module (≥200 words).
• Write src/error-codes.ts — TimelineErrorCode, AUDIO_TIMELINE_ERROR_METADATA, registerTimelineErrorCodes().
• Write Zod schemas: TrackSchema, ClipSchema, TimelineStateSchema, TimelineEngineOptionsSchema.

---

3. Track module

• Implement src/track/track.ts — track CRUD helpers: createTrack, updateTrack, removeTrack, validateTrack.
• Write track.test.ts and track.md.

---

4. Clip module

• Implement src/clip/clip.ts — clip helpers: createClip, validateClip, canSplitAt, constrainBoundaryTrim.
• Write clip.test.ts and clip.md.

---

5. Operations

• Implement src/operations/clip-operations.ts — moveClip, splitClip, trimClip, constrainClipDrag, constrainBoundaryTrim with overlap and minDuration guards.
• Implement src/operations/timeline-operations.ts — setSelection, setLoopRegion, setZoomLevel, zoomIn, zoomOut.
• Write clip-operations.test.ts, timeline-operations.test.ts, and both .md files.

---

6. Adapter interface

• Implement src/adapter/adapter.ts — NullTimelineAdapter for tests (no-op implementation of TimelineAdapter).
• Write adapter.test.ts and adapter.md.

---

7. Mixer

• Implement src/mixer/mixer.ts — MixerState, setMasterVolume, setTrackVolume, setTrackMute, setTrackSolo, setTrackPan, solo-group logic (non-soloed tracks gain = 0 when any track is soloed).
• Write mixer.test.ts and mixer.md.

---

8. Zoom

• Implement src/zoom/zoom.ts — zoom level table, zoomIn, zoomOut, setZoomLevel, canZoomIn, canZoomOut.
• Write zoom.test.ts and zoom.md.

---

9. TimelineEngine

• 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.
• Write engine.test.ts (≤500 lines): init, play/pause/stop, add/remove track, add/move/split/trim clip, undo/redo round-trip, transaction abort.
• Write engine.md.

---

10. Benchmarks

• Write src/__benchmarks__/timeline.bench.ts — create 50 tracks, add 200 clips, perform 100 undo/redo cycles.

---

11. Integration tests

• 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

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/audio-timeline — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-timeline — 100%.
• bun scripts/publish.ts --package @suaveplan/audio-timeline.
• Fold specs/audio-timeline/spec.md into openspec/specs/audio-timeline/spec.md.
• Archive to openspec/archive/2026-05-14-enterprise-audio-timeline/.