Migration and Versioning

Use this guide when you are upgrading dependencies and need to reduce production risk.

Choose your consumer profile first

Contract-only consumer

You depend on @ddgutierrezc/legato-contract types, events, error codes, and capabilities, but you do not consume the Capacitor runtime package directly.

Primary risk surface:

Semantic assumptions in your adapters and state machines
Event payload handling and type narrowing
Branches keyed by capability/error literals

Capacitor runtime consumer

You depend on @ddgutierrezc/legato-capacitor (and transitively align with contract semantics).

Primary risk surface:

Runtime behavior under real device conditions
Setup/order lifecycle integration
Capability-gated controls and remote event handling

Upgrade flow

Read the target release entry in Releases and the root changelog.
Confirm version alignment expectations from Compatibility.
Update dependencies in a branch.
Run consumer-specific validation (contract-only or runtime).
Roll forward only after passing your app-level checks.

Contract-only upgrade checklist

Verify LEGATO_ERROR_CODES handling still branches on error.code, never on message text.
Verify capability checks still use literal names from the contract (play, pause, stop, seek, skip-next, skip-previous).
Verify event-name assumptions match documented public names.
Re-run TypeScript checks in your integration package(s).

Capacitor runtime upgrade checklist

Verify initialization order is explicit and awaited (audioPlayer.setup(), mediaSession.setup() where used).
Verify queue lifecycle: add(...), startIndex, play(), skipTo...(), reset().
Verify capability-gated UI logic (getCapabilities() before showing seek/skip affordances).
Verify event listeners are attached/removed correctly across component lifecycles.
Verify error handling uses error.code and logs details for diagnostics.

Additional checklist for 1.1.0 shared playback headers

Apply this checklist when adopting HeaderGroup / headerGroupId in the 1.1.0 line:

Align both packages to 1.1.0 (@ddgutierrezc/legato-contract and @ddgutierrezc/legato-capacitor).
Confirm setup registration path exists and is awaited before queue admission:
- audioPlayer.setup({ headerGroups }) or
- Legato.setup({ headerGroups })
Keep existing Track.headers entries where one-off overrides are still required.
Add an explicit validation case for unknown headerGroupId (must fail fast at add()).
Add an explicit validation case for precedence (track.headers overrides shared-group keys).
Add one mixed-token queue scenario (some tracks use headerGroupId, others use per-track headers).
Verify your diagnostics/logging pipeline does not rely on internal merged effective header state.

Breaking-change review checklist

For each release, answer these questions before production rollout:

Were any public literals (event names, error codes, capability names) added/removed/renamed?
Did setup, queue, or snapshot semantics change in a way your UI assumes implicitly?
Did release notes mention native/runtime parity or behavior fixes that could alter edge-case flows?
Do you rely on behavior not guaranteed by the documented public surface?
Is your rollback path defined (previous package versions + deployment procedure)?

If any answer is uncertain, run additional device-level validation before promoting.

Minimal rollout strategy

Update dependencies on a feature branch.
Run smoke tests on representative Android and iOS targets.
Validate one real queue/playback scenario and one error-path scenario.
Roll out gradually and monitor playback error-code distribution.

This guide does not assume automated migration tooling. Treat each upgrade as an explicit engineering change with observable checks.