0.6.0

One release for every Art Computer in the field.

• Both firmware generations. The pairing request is the one 0.5 sends. An
  FF1 on FF OS with display grants answers with a grant (relay v2, as in
  0.5); an FF1 on older FF OS answers with a relayer session, which 0.5
  discarded with device_unsupported and 0.6 keeps and casts with, through
  the legacy relayer's HTTPS POST /api/cast, as 0.4 did.
• EphemeralBrowserSession is a union discriminated by kind:
  "displayGrant" ({ deviceId, ctl, expiresAt?, persistent }) or
  "relayerSession" ({ sessionId, expiresAt?, persistent, relayerBaseUrl? }).
  The session's token stays in localStorage and is never returned.
• Storage precedence. A stored grant first (IndexedDB), then a stored
  session (localStorage, under ephemeralBrowserSessionStorageKey(origin),
  the 0.4 key and record), else pair. A new grant replaces a stored session.
  Sessions 0.4 stored are used, no longer removed.
• relayerBaseUrl is an option again on DisplayDp1PlaylistOptions and
  mountDisplayOnArtComputerButton (a value or a function), with no default;
  the session's own relayerBaseUrl wins. DisplayDp1PlaylistOptions takes
  fetchImpl again.
• Relayer answers. 400 {"error":{"id":1003}} (no FF1 on the session's
  channel: the FF1 updated, or it is off) is device_unrecognized: the
  session is kept and the button offers "Pair again?". 401/403 is
  session_rejected, and the session is deleted.
• unpairArtComputer() and clearStoredEphemeralBrowserSession(origin) also
  forget a stored session.
• Removed the 0.5 deprecated aliases: mountPlayOnArtComputerButton,
  PlayOnArtComputerButtonOptions, PlayOnArtComputerButtonHandle,
  PlayError, PlayErrorCode, the ff-ac-play, ff-ac-play-button and
  ff-ac-play-status class names, and the play.js release asset. Use the
  Display names and ff-ac-display* classes.
• Removed legacySessionStorageKey: use ephemeralBrowserSessionStorageKey
  (the same key).
• On a session's 1003 the button says "Could not reach your Art Computer. If
  it is on and was updated recently, pair again." and its "Pair again?" pairs
  without deleting the session first: if that pairing fails, the session
  still works once the FF1 is back. A browser whose IndexedDB is missing or
  will not open still casts with a stored session; only a new pairing needs
  IndexedDB.
• A relayer-session cast honours timeoutMs (one deadline over the request,
  its retry and the body read), like a grant cast.

feral-file/feral-file#3551, #33.

0.5.0

The package is now @feralfile/display (npm i @feralfile/display). The button reads Display on Art Computer, and pairing and casting go over relay v2 with a display grant the Art Computer issues. @feralfile/play stops at 0.4.0 and is deprecated on npm with a pointer here.

Renamed. Change the dependency and the import specifier. The Play names stay as deprecated aliases through 0.5.x and go in 0.6.0: mountPlayOnArtComputerButton → mountDisplayOnArtComputerButton, PlayOnArtComputerButtonOptions/Handle → DisplayOnArtComputerButton…, PlayError/PlayErrorCode → DisplayError/DisplayErrorCode (the same class, so instanceof PlayError still matches), and the CSS classes ff-ac-play* → ff-ac-display* (the button carries both). The default dialog title is "Display on your Art Computer". The messages that said press play now say try again, and an error's name is "DisplayError". Match on code, which is unchanged. buttonLabel and dialog.copy overrides work as before. The self-hosted bundle is display.js; this release also attaches play.js.

Breaking (relay v2, display grant): there is no relayer token, no /api/cast and no relayerBaseUrl. The grant and its keys live in IndexedDB (the database keeps the name ff-play, so stored grants survive the rename). hasStoredEphemeralBrowserSession, readStoredEphemeralBrowserSession and clearStoredEphemeralBrowserSession are async and take only the origin. DisplayDp1PlaylistOptions gains socketFactory and timeoutMs. Stored 0.4 sessions are removed on first use, so each visitor pairs once more. 0.5 needs an Art Computer on FF OS with display grants; older firmware fails with device_unsupported. Full list: "Upgrading from 0.4.x" in clients/session-recipient/js/README.md.

Adopt when FF OS 3.0.0 is broadly deployed. 0.5 needs an Art Computer on FF OS 3.0.0 (display grants); 3.0.0 is at staging and no fielded FF1 runs it yet, so integrators stay on @feralfile/play 0.4.0 until then (ffos-user#430, feral-file#3551). The deprecation on 0.4.0 is lifted.

0.4.0

Site-initiated pairing. The site now starts pairing: @feralfile/play creates the channel and shows the visitor an app link (button on a phone, QR on a desktop) and a six-digit code; the Feral File app brings their Art Computer to it. Owners can keep a site paired until they remove it in the app.

Breaking (integrators calling requestEphemeralSession directly): the pairing input ({ shortCode } / { qrPayload }) is gone, along with parsePairingQrPayload and pairingToResolved; pass onPairingMaterial({ appLink, shortCode, expiresAt }) instead. createPairingCodeDialog is now createPairingDialog. PlayErrorCode drops pairing_code_not_found and pairing_code_used. mountPlayOnArtComputerButton is unchanged apart from an optional appLinkBaseUrl. Guide: docs/integration.md.

Also in this release:

• The site's request rides the create call, so the Art Computer can ask its owner as soon as it joins (FF OS releases carrying ffos-user#375); earlier devices keep working through the encrypted request (#17, #19).
• A session the Art Computer delivered while the page was suspended is collected instead of discarded (#19).
• A cast that fails once on a network error is retried once (#19).
• No pairing link or code is shown after a cancel that lands during channel creation (#16, #18).

Requires the Mint Pairing Broker at play c31c2ea or later (live on handoff.feralfile.com). 0.3.x sites keep working.

0.3.1

A truer message for a stale pairing code.

• When a pairing code has aged out, the dialog now says the code is no longer valid, that codes expire after a few minutes, and to turn Browser Pairing on again and enter the new one. Before, the broker's answer for an expired code surfaced as "Pairing code not found on this broker", which reads like a server fault; one integrator lost half an hour to it.
• Error codes are unchanged. pairing_code_not_found still fires for that case and pairing_code_expired remains for the broker's explicit 410. Match on codes, not on message text.
• No API changes. A drop-in upgrade from 0.3.0.
• Companion fix on the device side: the Feral File mobile app showed "Could not start browser pairing" in red while the FF1 was already displaying the code, whenever the phone reached the FF1 over the same wifi. That is fixed in the app and ships with its next release.

Guide: https://docs.feralfile.com/art-computer/play/

0.3.0

Sessions that outlive the tab, and a corrected relayer host.

• Owner-kept sessions: when the device owner approves your site, they can choose to keep it paired until they remove it (mobile app → Settings → Art Computers → the FF1 → Paired sites). Such a session comes back as { persistent: true } with no expiresAt and stays usable until removed or revoked. Sessions the owner does not keep carry expiresAt and behave as before.
• The shape is capability-gated: each request declares it, and the device sends the no-expiry session only to a site that declared it. A site on 0.2.0 or older gets a timed session even when the owner chose to keep it — upgrading the library is the whole fix on the site side. The device-side support ships in its own FF OS and mobile-app releases; until those land everywhere, write your page to handle both shapes.
• New option requestedExpiresInSeconds on mountPlayOnArtComputerButton and requestEphemeralSessionWithPairingUi: the lifetime your site asks for, a whole number of seconds from 1 to 31536000. A value outside that range throws where you set it. Leave it unset to take the device default. The owner decides: if they keep your site paired, the request is ignored.
• Relayer host corrected. https://artwork-info.feral-file.workers.dev no longer resolves; the relayer Feral File operates today is https://tv-cast-coordination.autonomy-system.workers.dev. Put that host in your Content-Security-Policy connect-src — the policy has to be written before any session exists. At runtime, read session.relayerBaseUrl from the approved session rather than hard-coding a host; the relayerBaseUrl option is the fallback for a session that carries none, and without it such a session fails with relayer base URL is required.
• The Go ephemeral-token minter carries the persistent session shape and validates the requested lifetime device-side.

Guide: https://docs.feralfile.com/art-computer/play/

0.2.0

Integrator-facing hardening before the first external builds:

• Typed errors: every user-facing failure is a PlayError with a stable code (pairing_code_not_found, pairing_code_expired, pairing_code_used, mint_rejected, approval_timeout, session_rejected, pairing_canceled, display_failed, display_rejected). Match on error.code; messages are for humans.
• Self-hosted no-build install: play.js (attached below) is a self-contained minified ESM bundle. Host it next to your pages and import { mountPlayOnArtComputerButton } from "./play.js".
• The pairing dialog no longer shows roadmap copy; cliNotice remains as an optional override.
• npm homepage now points at https://docs.feralfile.com/art-computer/play/

Guide: https://docs.feralfile.com/art-computer/play/

0.1.0

First release of @feralfile/play, the browser library behind Play on Art Computer. Install with npm i @feralfile/play, or import from https://esm.sh/@feralfile/play on no-build sites. Integration guide: https://github.com/feral-file/play/blob/main/docs/third-party-integration.md