feat: scaffold API, commands and tests

[velocitysystems]

Summary

Scaffolds the API contract for headless native audio playback: Tauri commands, TypeScript bindings, state machine, event system, and mock Rust implementation.

API design inspired by Vidstack's audio provider model, adapted for native platform integration with OS transport controls (lock screen, notification shade, headphone buttons)

Architecture

State machine with 7 statuses (Idle, Loading, Ready, Playing, Paused, Ended, Error) gates transport actions (load, play, pause, stop, seek) at both the Rust and TypeScript layers. The TypeScript type system enforces this via discriminated unions — only valid actions are available on the Player object for a given status.

Two event channels separate high-frequency time progression from infrequent state transitions:

• state-changed — status transitions, settings, errors (full PlayerState)
• time-update — currentTime/duration progression (lightweight TimeUpdate, ~250ms during playback)

Always-available controls (setVolume, setMuted, setPlaybackRate, setLoop, listen, onTimeUpdate) are not gated by status — they work regardless of playback state.

Design decisions

• Single player — OS transport controls map to one active session; consuming apps build queue management on top
• Transport actions vs controls separation — Transport actions return AudioActionResponse with expected-status metadata; settings return the updated PlayerWithAnyStatus directly

Test plan

• npm run standards passes (eslint, tsc, markdownlint, clippy, rustfmt, commitlint, check-node-version)
• npm test passes (23 TypeScript + 24 Rust tests)
• All state transitions tested (happy path and error cases)
• NaN/Infinity rejection tested for volume, playback rate, seek
• Clamping boundary values tested
• Action gating verified for all 7 statuses
• Player controls verified as always-available (Idle and Error)

[pmorris-dev]

I won't block on these suggestions. Leaving it up to you, @velocitysystems.