Extend the Web player

Work with components, state, services, and deployment boundaries.

Archived Web reference

Work with components, state, services, and deployment boundaries.

Archived Web development reference. It covers the Vue web player, not WinUI native development. Confirm APIs against the current checkout before applying an older example. Start with Web architecture and Native architecture for the correct project boundary.

Get started

Use the Node.js and npm versions required by the repository lockfile, then install and run the project:

npm ci
npm run dev

The main extension points are src/app/ofplayerApp.js (orchestration), src/components/ (views), src/composables/ (reusable UI logic), src/models/ (entities), src/services/ (behavior), src/stores/ (reactive state), and src/styles/ (theme tokens).

Add a feature

  1. Define the model and persistence shape. Decide how older browser databases will migrate.
  2. Put domain operations in a service. Keep browser file access and remote requests behind clear boundaries.
  3. Add reactive state in a store only if multiple views need it.
  4. Expose the operation through ofplayerApp and hydrate persisted state in the proper order.
  5. Add the view component with props and events; do not make it another source of truth.
  6. Test persistence, error handling, keyboard behavior, and the relevant narrow layout.

For a smart view, derive membership from existing tracks rather than copying the files. For a new data source, keep credentials, network errors, and media URLs separate from local file import. For playback behavior, preserve one current queue and release object URLs, media listeners, and timers when no longer needed.

Themes and accessibility

Add appearance values in the --of-* token system. Use semantic tokens for danger, playing, favorites, Pro, and the player accent. Support both color schemes, focus states, reduced motion, and icon labels. See Web theming.

Reliability and tests

Handle pending operations explicitly, especially writes that may have succeeded before a timeout. Avoid duplicate imports and repeated destructive actions. Clean up media resources and observers. Add unit tests for new domain rules, integration tests for persistence or services, and a component check for any nontrivial interaction. Run the repository build and lint commands before shipping.

Production deployment also needs a versioned artifact, correct route fallback and static assets, live smoke checks, and a rollback path. A successful local build is only one part of release acceptance.