suaveplan/packages/media/audio/audio-timeline/SPEC_CHECKLIST.md

audio-timeline Spec Checklist

Requirements

1. Universal purity
   • Scenario: Built dist references no platform globals
   • Scenario: Tests pass under both runtimes
2. TimelineEngine construction and state snapshot
   • Scenario: getState returns an immutable snapshot
   • Scenario: tracksVersion increments on track mutation
3. Track model and CRUD operations
   • Scenario: addTrack then removeTrack round-trips the track array
   • Scenario: Unknown track id throws AUDIO_TIMELINE_TRACK_NOT_FOUND
4. Clip model and clip lifecycle
   • Scenario: addClip places a clip on the named track
   • Scenario: Unknown clip id throws AUDIO_TIMELINE_CLIP_NOT_FOUND
5. Clip drag with overlap constraint
   • Scenario: Drag is clamped to avoid sibling overlap
   • Scenario: Zero constrained delta is a no-op
6. Clip trim with minimum-duration guard
   • Scenario: Right trim shortens duration within the floor
   • Scenario: Over-trim throws AUDIO_TIMELINE_INVALID_TRIM
7. Clip split at a sample boundary
   • Scenario: Split produces two contiguous clips
   • Scenario: Split outside the clip throws AUDIO_TIMELINE_INVALID_SPLIT
8. Per-track mixer state
   • Scenario: Volume is clamped and forwarded to the adapter
   • Scenario: Solo mutes non-soloed tracks
9. Zoom levels and selection
   • Scenario: zoomOut at the coarsest level is a no-op
   • Scenario: setSelection normalises a reversed range
10. Loop region and transport playback
    • Scenario: Playback follows the FSM transitions
    • Scenario: Invalid transport transition is rejected by the FSM
11. Tempo and musical time
    • Scenario: setTempo updates state and forwards to the adapter
12. TimelineAdapter interface — plugin slot 5
    • Scenario: NullTimelineAdapter satisfies the full interface
    • Scenario: Transport without an adapter throws AUDIO_TIMELINE_ADAPTER_NOT_SET
13. Undo/redo via @suaveplan/undo
    • Scenario: Mutation then undo restores prior state
    • Scenario: redo reapplies the undone command
14. Transaction batching of undo commands
    • Scenario: Committed transaction undoes as one step
    • Scenario: commitTransaction without an active transaction throws
15. Incremental adapter updates on undo/redo
    • Scenario: Same-count undo issues per-track updates
    • Scenario: Count-changing undo issues a full setTracks
16. Typed timeline event surface
    • Scenario: clipChange fires once per clip mutation
17. Session save/load via @suaveplan/serialize
    • Scenario: Session round-trips through serialize
18. Zod boundary validation
    • Scenario: Invalid clip is rejected at the boundary
19. Structured error codes
    • Scenario: Every registered code is thrown by a call site
20. OpenTelemetry instrumentation
    • Scenario: Instrumentation is inert without an exporter
21. AbortSignal propagation
    • Scenario: Pre-aborted signal short-circuits init
22. Subpath exports per feature module
    • Scenario: Each feature module is independently importable