one 2.11.5 → 2.12.0

package/src/cli/buildPage.test.ts

@@ -0,0 +1,152 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, it } from 'vitest'
+import {
+  LOADER_JS_POSTFIX,
+  NATIVE_LOADER_JS_POSTFIX_UNCACHED,
+} from '../constants'
+import { buildPage } from './buildPage'
+
+let root: string | undefined
+
+afterEach(async () => {
+  if (root) await rm(root, { recursive: true, force: true })
+})
+
+async function fixture() {
+  root = await mkdtemp(join(tmpdir(), 'one-build-page-'))
+  const serverEntry = join(root, 'entry.mjs')
+  const { writeFile, mkdir } = await import('node:fs/promises')
+  await writeFile(
+    serverEntry,
+    `export default {
+      options: { routes: {
+        '/app/probe.tsx': async () => ({
+          loader: ({ params }) => ({ slug: params.slug }),
+        }),
+        '/app/gated.tsx': async () => ({
+          loader: () => { throw Response.redirect('http://example.com/login', 302) },
+        }),
+      } },
+      render: async ({ loaderData }) => '<html><head></head><body>' + JSON.stringify(loaderData) + '</body></html>'
+    }`
+  )
+  return serverEntry
+}
+
+async function buildRoute(
+  serverEntry: string,
+  out: string,
+  route: { path: string; file: string; params: any },
+  skipNativeLoaders?: boolean
+) {
+  const clientDir = join(out, 'client')
+  const staticDir = join(out, 'static')
+  const { mkdir } = await import('node:fs/promises')
+  await mkdir(join(clientDir, 'assets'), { recursive: true })
+  await mkdir(staticDir, { recursive: true })
+  const built = await buildPage(
+    serverEntry,
+    'app',
+    route.path,
+    '/probe.tsx',
+    route.params,
+    { type: 'ssg', file: route.file, layouts: [], middlewares: [] } as any,
+    { file: 'assets/probe.js' },
+    staticDir,
+    clientDir,
+    {},
+    'server/probe.js',
+    [],
+    [],
+    [],
+    [],
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    skipNativeLoaders
+  )
+  return { built, clientDir, staticDir }
+}
+
+function nativeTwins(clientDir: string, loaderPath: string) {
+  const cached = join(clientDir, loaderPath.replace(/\.js$/, '.native.js'))
+  const uncached = join(
+    clientDir,
+    loaderPath.replace(LOADER_JS_POSTFIX, NATIVE_LOADER_JS_POSTFIX_UNCACHED)
+  )
+  return { cached, uncached }
+}
+
+async function exists(path: string) {
+  try {
+    await readFile(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+it('omits native loader twins when skipped, keeping web output identical', async () => {
+  const serverEntry = await fixture()
+  for (const route of [
+    { path: '/probe', file: './probe.tsx', params: { slug: 'probe' } },
+    { path: '/gated', file: './gated.tsx', params: {} },
+  ]) {
+    const enabled = await buildRoute(serverEntry, join(root!, 'enabled', route.path), route)
+    const skipped = await buildRoute(
+      serverEntry,
+      join(root!, 'skipped', route.path),
+      route,
+      true
+    )
+
+    // web loader and html are byte-identical either way
+    const [enabledLoader, skippedLoader] = await Promise.all([
+      readFile(join(enabled.clientDir, enabled.built.loaderPath), 'utf8'),
+      readFile(join(skipped.clientDir, skipped.built.loaderPath), 'utf8'),
+    ])
+    expect(skippedLoader, route.path).toBe(enabledLoader)
+    const [enabledHtml, skippedHtml] = await Promise.all([
+      readFile(join(enabled.staticDir, `${route.path.slice(1)}.html`), 'utf8'),
+      readFile(join(skipped.staticDir, `${route.path.slice(1)}.html`), 'utf8'),
+    ])
+    expect(skippedHtml, route.path).toBe(enabledHtml)
+
+    // native twins exist by default, absent when skipped
+    const enabledTwins = nativeTwins(enabled.clientDir, enabled.built.loaderPath)
+    expect(await exists(enabledTwins.cached), `${route.path} cached`).toBe(true)
+    expect(await exists(enabledTwins.uncached), `${route.path} uncached`).toBe(true)
+    const skippedTwins = nativeTwins(skipped.clientDir, skipped.built.loaderPath)
+    expect(await exists(skippedTwins.cached), `${route.path} cached`).toBe(false)
+    expect(await exists(skippedTwins.uncached), `${route.path} uncached`).toBe(false)
+  }
+
+  // the redirect loader still carries its signal on the web file
+  const skipped = await buildRoute(
+    serverEntry,
+    join(root!, 'redirect'),
+    { path: '/gated', file: './gated.tsx', params: {} },
+    true
+  )
+  const webLoader = await readFile(
+    join(skipped.clientDir, skipped.built.loaderPath),
+    'utf8'
+  )
+  expect(webLoader).toContain('__oneRedirect')
+})
+
+it('writes native loader twins by default', async () => {
+  const serverEntry = await fixture()
+  const { built, clientDir } = await buildRoute(
+    serverEntry,
+    join(root!, 'default'),
+    { path: '/probe', file: './probe.tsx', params: { slug: 'probe' } }
+  )
+  const twins = nativeTwins(clientDir, built.loaderPath)
+  expect(await exists(twins.cached)).toBe(true)
+  expect(await exists(twins.uncached)).toBe(true)
+})

package/src/cli/buildPage.ts

@@ -63,7 +63,8 @@ export async function buildPage(
   criticalPreloads?: string[],
   deferredPreloads?: string[],
   useAfterLCP?: boolean,
-  useAfterLCPAggressive?: boolean
+  useAfterLCPAggressive?: boolean,
+  skipNativeLoaders?: boolean
 ): Promise<One.RouteBuildInfo> {
   let t0 = performance.now()
 
@@ -275,10 +276,12 @@ prefetchCSS()
             loaderPartialPath,
             `export function loader(){return ${redirectData}}`
           )
-          // native-friendly CJS version
-          const nativeCjs = `exports.loader = function(){return ${redirectData}}`
-          await outputFile(loaderPartialPath.replace(/\.js$/, '.native.js'), nativeCjs)
-          await outputFile(uncachedNativePath, nativeCjs)
+          if (!skipNativeLoaders) {
+            // native-friendly CJS version
+            const nativeCjs = `exports.loader = function(){return ${redirectData}}`
+            await outputFile(loaderPartialPath.replace(/\.js$/, '.native.js'), nativeCjs)
+            await outputFile(uncachedNativePath, nativeCjs)
+          }
           loaderPath = getLoaderPath(path)
           loaderData = {}
         } else {
@@ -289,10 +292,12 @@ prefetchCSS()
           // stub of its own to replace)
           const data = JSON.stringify(loaderData)
           await outputFile(loaderPartialPath, `export function loader(){return ${data}}`)
-          // native-friendly CJS version
-          const nativeCjs = `exports.loader = function(){return ${data}}`
-          await outputFile(loaderPartialPath.replace(/\.js$/, '.native.js'), nativeCjs)
-          await outputFile(uncachedNativePath, nativeCjs)
+          if (!skipNativeLoaders) {
+            // native-friendly CJS version
+            const nativeCjs = `exports.loader = function(){return ${data}}`
+            await outputFile(loaderPartialPath.replace(/\.js$/, '.native.js'), nativeCjs)
+            await outputFile(uncachedNativePath, nativeCjs)
+          }
           loaderPath = getLoaderPath(path)
         }
       }

package/src/cli/buildPageWorker.ts

@@ -86,7 +86,8 @@ parentPort.on('message', async (msg: any) => {
           msg.args.criticalPreloads,
           msg.args.deferredPreloads,
           msg.args.useAfterLCP,
-          msg.args.useAfterLCPAggressive
+          msg.args.useAfterLCPAggressive,
+          msg.args.skipNativeLoaders
         )
       })
       // loader data is already in the artifacts and is discarded by the parent.

package/src/cli/workerPool.ts

@@ -127,6 +127,7 @@ export class BuildWorkerPool {
     deferredPreloads?: string[]
     useAfterLCP?: boolean
     useAfterLCPAggressive?: boolean
+    skipNativeLoaders?: boolean
   }): Promise<any> {
     if (this._terminated) {
       throw new Error('Worker pool has been terminated')

package/src/headless-server.ts

@@ -27,13 +27,13 @@
  *   })
  *
  *   const response = await server.fetch(request)
+ *   // pass a request-scoped static HTML reader as the fourth argument for SPA or SSG
  *   server.updateRoutes(newManifest, newRoutes)
  */
 
 export { createWorkerHandler, type LazyRoutes } from './server/workerHandler'
 export { compileManifest } from './createHandleRequest'
 export type { RequestHandlers } from './createHandleRequest'
-export { getFetchStaticHtml, setFetchStaticHtml } from './server/staticHtmlFetcher'
 export type { One } from './vite/types'
 
 import { setServerGlobals } from './server/setServerGlobals'
@@ -92,7 +92,7 @@ export async function createServer(options: HeadlessServerOptions) {
   })
 
   return {
-    /** handle an incoming request — returns Response or null (unmatched) */
+    /** handle a request with an optional request-scoped static HTML reader */
     fetch: handler.handleRequest,
 
     /** hot-swap the route table without recreating the server */

package/src/index.ts

@@ -37,6 +37,7 @@ export {
 export type {
   PortalProps,
   PortalHostProps,
+  AudioPlayOptions,
   AudioPlayer,
   AudioPlayerOptions,
   AudioPlayerSubscription,

package/src/platform/audio/index.native.ts

@@ -2,6 +2,7 @@ import { validateCallback } from '../validateCallback'
 import { rethrowNativeError } from '../nativeError'
 import type {
   AudioPlaybackStatus,
+  AudioPlayOptions,
   AudioRecordingPermission,
   AudioRecordingResult,
   AudioRecordingStatus,
@@ -15,6 +16,7 @@ import { AudioPlayer, createPlayer } from './player.native'
 export type {
   AudioPlaybackState,
   AudioPlaybackStatus,
+  AudioPlayOptions,
   AudioRecordingPermission,
   AudioRecordingResult,
   AudioRecordingState,
@@ -33,8 +35,8 @@ export const Audio = Object.freeze({
     native().getRecordingPermissionStatus().catch(rethrowNativeError),
   requestRecordingPermission: (): Promise<AudioRecordingPermission> =>
     native().requestRecordingPermission().catch(rethrowNativeError),
-  play: (uri: string): Promise<AudioPlaybackStatus> =>
-    native().play(uri).catch(rethrowNativeError),
+  play: (uri: string, options?: AudioPlayOptions): Promise<AudioPlaybackStatus> =>
+    native().play(uri, options ?? {}).catch(rethrowNativeError),
   getPlaybackStatus: (): Promise<AudioPlaybackStatus> =>
     native().getPlaybackStatus().catch(rethrowNativeError),
   pause: (): Promise<AudioPlaybackStatus> => native().pause().catch(rethrowNativeError),

package/src/platform/audio/index.ts

@@ -2,17 +2,24 @@ import { Audio as unavailable } from './unavailable'
 import { validateCallback } from '../validateCallback'
 import type {
   AudioPlaybackStatus,
+  AudioPlayOptions,
   AudioRecordingPermission,
   AudioRecordingResult,
   AudioRecordingStatus,
   AudioNowPlayingInfo,
   AudioRemoteCommandEvent,
 } from '../specs/OneAudio.nitro'
+import { addRemoteListener, claimNowPlaying, releaseNowPlaying } from './nowPlaying'
 import { AudioPlayer, createPlayer } from './player'
 export type { PitchCorrectionQuality } from '../specs/OneAudio.nitro'
 export type * from './types'
 export type * from './unavailable'
 let player: HTMLAudioElement | undefined
+// a play with a position or paused flag, between creation and the landed
+// seek. paused is the intent pause and resume update while it loads.
+let pendingLoad:
+  | { audio: HTMLAudioElement; paused: boolean; cancel?: () => void }
+  | undefined
 let playbackError: string | undefined
 let permission: AudioRecordingPermission = 'undetermined'
 let openingRecording = false
@@ -27,8 +34,6 @@ let recording:
       error?: Error
     }
   | undefined
-const remoteListeners = new Set<(event: AudioRemoteCommandEvent) => void>()
-let remoteInstalled = false
 
 async function getRecordingPermissionStatus(): Promise<AudioRecordingPermission> {
   if (typeof window === 'undefined' || !navigator.mediaDevices?.getUserMedia)
@@ -74,7 +79,7 @@ function playbackStatus(): AudioPlaybackStatus {
         ? 'failed'
         : player.ended
           ? 'ended'
-          : player.readyState < 2
+          : pendingLoad || player.readyState < 2
             ? 'loading'
             : player.paused
               ? 'paused'
@@ -90,7 +95,9 @@ function requirePlayer(): HTMLAudioElement {
   return player
 }
 function clearPlayer(): void {
-  clearNowPlaying()
+  releaseNowPlaying('global')
+  pendingLoad?.cancel?.()
+  pendingLoad = undefined
   if (player) {
     player.pause()
     player.removeAttribute('src')
@@ -152,69 +159,88 @@ function recorderChange(event: 'pause' | 'resume'): Promise<AudioRecordingStatus
     }
   })
 }
-function mediaSession(): MediaSession {
-  if (!navigator.mediaSession) throw new Error('Audio: Media Session is unavailable')
-  return navigator.mediaSession
-}
-function clearNowPlaying(): void {
-  if (typeof window === 'undefined' || !navigator.mediaSession) return
-  const session = navigator.mediaSession
-  if (remoteInstalled)
-    for (const action of ['play', 'pause', 'seekto'] as const)
-      session.setActionHandler(action, null)
-  remoteInstalled = false
-  session.metadata = null
-  session.playbackState = 'none'
-}
-function syncNowPlaying(): void {
-  if (!navigator.mediaSession?.metadata || !player) return
-  navigator.mediaSession.playbackState =
-    player.paused || player.ended ? 'paused' : 'playing'
-}
-async function remote(event: AudioRemoteCommandEvent): Promise<void> {
-  if (!player || !navigator.mediaSession?.metadata) return
-  const audio = player
-  try {
-    if (event.type === 'play') await Audio.resume()
-    else if (event.type === 'pause') await Audio.pause()
-    else await Audio.seek(event.positionMs!)
-  } catch {
-    // the browser callback has no error channel; failed work emits no success.
-    return
-  }
-  if (player !== audio) return
-  syncNowPlaying()
-  for (const listener of [...remoteListeners]) listener(event)
-}
-function installRemote(): void {
-  if (remoteInstalled) return
-  const session = mediaSession()
-  session.setActionHandler('play', () => remote({ type: 'play' }))
-  session.setActionHandler('pause', () => remote({ type: 'pause' }))
-  session.setActionHandler('seekto', (event) =>
-    remote({ type: 'seek', positionMs: (event.seekTime ?? 0) * 1000 })
-  )
-  remoteInstalled = true
+// resolves once the element has metadata and sits at the position, without
+// playing. replacement cancels it through the load's cancel hook.
+function prepareAt(load: NonNullable<typeof pendingLoad>, positionMs: number): Promise<void> {
+  const { audio } = load
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      audio.removeEventListener('loadedmetadata', ready)
+      audio.removeEventListener('seeked', done)
+      audio.removeEventListener('error', failed)
+      load.cancel = undefined
+    }
+    let seconds = 0
+    // a source without range support lands somewhere else, often 0; fail
+    // rather than let a later resume play the opening.
+    const done = () => {
+      cleanup()
+      if (Math.abs(audio.currentTime - seconds) > 0.25)
+        reject(new Error('Audio.play: the source cannot seek to the position'))
+      else resolve()
+    }
+    const failed = () => {
+      cleanup()
+      reject(new Error(`Audio.play: ${audio.error?.message || 'decoding failed'}`))
+    }
+    function ready() {
+      audio.removeEventListener('loadedmetadata', ready)
+      seconds = Math.min(
+        positionMs / 1000,
+        Number.isFinite(audio.duration) ? audio.duration : Infinity
+      )
+      if (audio.currentTime === seconds) return done()
+      audio.addEventListener('seeked', done, { once: true })
+      audio.currentTime = seconds
+    }
+    load.cancel = () => {
+      cleanup()
+      reject(new Error('Audio.play: playback was replaced'))
+    }
+    audio.addEventListener('error', failed, { once: true })
+    if (audio.readyState >= 1) ready()
+    else audio.addEventListener('loadedmetadata', ready, { once: true })
+  })
 }
 export const Audio = Object.freeze({
   getRecordingPermissionStatus,
   requestRecordingPermission,
-  play: async (uri: string): Promise<AudioPlaybackStatus> => {
-    if (typeof window === 'undefined') return unavailable.play(uri)
+  play: async (uri: string, options?: AudioPlayOptions): Promise<AudioPlaybackStatus> => {
+    if (typeof window === 'undefined') return unavailable.play(uri, options)
     if (openingRecording || recording)
       throw new Error('Audio.play: stop the current recording first')
     const url = new URL(uri, document.baseURI)
     if (!['https:', 'http:', 'blob:', 'data:'].includes(url.protocol))
       throw new Error('Audio.play: invalid browser audio URI')
+    const prepare = options?.positionMs !== undefined || options?.paused !== undefined
+    const positionMs = options?.positionMs ?? 0
+    if (typeof positionMs !== 'number' || !Number.isFinite(positionMs) || positionMs < 0)
+      throw new Error('Audio.play: position must be finite and nonnegative')
     clearPlayer()
     const audio = new window.Audio(url.href)
     player = audio
-    for (const event of ['play', 'pause', 'ended'])
-      audio.addEventListener(event, syncNowPlaying)
     audio.addEventListener('error', () => {
       if (player === audio)
         playbackError = audio.error?.message ?? 'Audio.play: decoding failed'
     })
+    if (prepare) {
+      const load: NonNullable<typeof pendingLoad> = { audio, paused: options?.paused ?? false }
+      pendingLoad = load
+      audio.preload = 'auto'
+      try {
+        await prepareAt(load, positionMs)
+      } catch (error) {
+        if (pendingLoad === load) {
+          pendingLoad = undefined
+          playbackError = (error as Error).message
+        }
+        throw error
+      }
+      if (player !== audio || pendingLoad !== load)
+        throw new Error('Audio.play: playback was replaced')
+      pendingLoad = undefined
+      if (load.paused) return playbackStatus()
+    }
     try {
       await audio.play()
     } catch (error) {
@@ -228,6 +254,10 @@ export const Audio = Object.freeze({
   pause: async (): Promise<AudioPlaybackStatus> => {
     if (typeof window === 'undefined') return unavailable.pause()
     const audio = requirePlayer()
+    if (pendingLoad) {
+      pendingLoad.paused = true
+      return playbackStatus()
+    }
     if (!audio.paused)
       await new Promise<void>((resolve) => {
         audio.addEventListener('pause', () => resolve(), { once: true })
@@ -238,6 +268,11 @@ export const Audio = Object.freeze({
   resume: async (): Promise<AudioPlaybackStatus> => {
     if (typeof window === 'undefined') return unavailable.resume()
     const audio = requirePlayer()
+    // a prepared load plays itself once its seek lands.
+    if (pendingLoad) {
+      pendingLoad.paused = false
+      return playbackStatus()
+    }
     if (audio.ended) audio.currentTime = 0
     await audio.play()
     if (player !== audio) throw new Error('Audio.resume: playback was replaced')
@@ -248,7 +283,8 @@ export const Audio = Object.freeze({
     if (!Number.isFinite(positionMs) || positionMs < 0)
       throw new Error('Audio.seek: position must be finite and nonnegative')
     const audio = requirePlayer()
-    if (audio.readyState < 1) throw new Error('Audio.seek: playback is not ready')
+    if (audio.readyState < 1 || pendingLoad)
+      throw new Error('Audio.seek: playback is not ready')
     const seconds = Math.min(
       positionMs / 1000,
       Number.isFinite(audio.duration) ? audio.duration : Infinity
@@ -402,27 +438,23 @@ export const Audio = Object.freeze({
   watchInterruptions: unavailable.watchInterruptions,
   setNowPlayingInfo: async (info: AudioNowPlayingInfo): Promise<void> => {
     if (typeof window === 'undefined') return unavailable.setNowPlayingInfo(info)
-    if (!info.title.trim())
-      throw new Error('Audio.setNowPlayingInfo: title must not be empty')
     const audio = requirePlayer()
-    if (info.artworkUri) {
-      const artwork = new window.Image()
-      artwork.src = info.artworkUri
-      await artwork.decode()
-      if (player !== audio) throw new Error('Audio.setNowPlayingInfo: playback was replaced')
-    }
-    mediaSession().metadata = new MediaMetadata({
-      title: info.title,
-      artist: info.artist,
-      album: info.albumTitle,
-      artwork: info.artworkUri ? [{ src: info.artworkUri }] : [],
-    })
-    installRemote()
-    syncNowPlaying()
+    await claimNowPlaying(
+      {
+        key: 'global',
+        element: audio,
+        play: Audio.resume,
+        pause: Audio.pause,
+        seek: Audio.seek,
+      },
+      info,
+      'Audio.setNowPlayingInfo',
+      () => player === audio
+    )
   },
   clearNowPlayingInfo: async (): Promise<void> => {
     if (typeof window === 'undefined') return unavailable.clearNowPlayingInfo()
-    clearNowPlaying()
+    releaseNowPlaying('global')
   },
   watchRemoteCommands: (
     onEvent: (event: AudioRemoteCommandEvent) => void
@@ -430,11 +462,7 @@ export const Audio = Object.freeze({
     validateCallback(onEvent, 'Audio.watchRemoteCommands: onEvent must be a function')
     if (typeof window === 'undefined' || !navigator.mediaSession)
       return unavailable.watchRemoteCommands(onEvent)
-    remoteListeners.add(onEvent)
-    return () => {
-      remoteListeners.delete(onEvent)
-
-    }
+    return addRemoteListener(onEvent)
   },
   AudioPlayer,
   createPlayer,

package/src/platform/audio/nowPlaying.ts

@@ -0,0 +1,122 @@
+import type { AudioNowPlayingInfo, AudioRemoteCommandEvent } from '../specs/OneAudio.nitro'
+
+// the one browser media session, owned by the singleton or by one player
+// instance. a claim moves ownership without clearing the metadata first;
+// owners release only their own claim, so an old owner's cleanup never
+// clears a newer one, and a claim that finishes after a newer claim or
+// release (slow artwork) rejects instead of taking ownership back.
+
+export type NowPlayingOwner = {
+  // 'global' for the singleton, else the player id.
+  key: string
+  element: HTMLAudioElement
+  play: () => Promise<unknown>
+  pause: () => Promise<unknown>
+  seek: (positionMs: number) => Promise<unknown>
+}
+
+const listeners = new Set<(event: AudioRemoteCommandEvent) => void>()
+const syncEvents = ['play', 'pause', 'ended'] as const
+let owner: NowPlayingOwner | undefined
+let claim = 0
+let pendingKey: string | undefined
+let installed = false
+
+function sync(): void {
+  if (!owner || !navigator.mediaSession?.metadata) return
+  navigator.mediaSession.playbackState =
+    owner.element.paused || owner.element.ended ? 'paused' : 'playing'
+}
+
+function setOwner(next: NowPlayingOwner | undefined): void {
+  if (owner?.element !== next?.element) {
+    for (const event of syncEvents) {
+      owner?.element.removeEventListener(event, sync)
+      next?.element.addEventListener(event, sync)
+    }
+  }
+  owner = next
+}
+
+async function remote(event: AudioRemoteCommandEvent): Promise<void> {
+  const current = owner
+  if (!current || !navigator.mediaSession?.metadata) return
+  try {
+    if (event.type === 'play') await current.play()
+    else if (event.type === 'pause') await current.pause()
+    else await current.seek(event.positionMs!)
+  } catch {
+    // the browser callback has no error channel; failed work emits no success.
+    return
+  }
+  if (owner !== current) return
+  sync()
+  const emitted = current.key === 'global' ? event : { ...event, playerId: current.key }
+  for (const listener of [...listeners]) listener(emitted)
+}
+
+function install(session: MediaSession): void {
+  if (installed) return
+  session.setActionHandler('play', () => remote({ type: 'play' }))
+  session.setActionHandler('pause', () => remote({ type: 'pause' }))
+  session.setActionHandler('seekto', (event) =>
+    remote({ type: 'seek', positionMs: (event.seekTime ?? 0) * 1000 })
+  )
+  installed = true
+}
+
+export async function claimNowPlaying(
+  next: NowPlayingOwner,
+  info: AudioNowPlayingInfo,
+  verb: string,
+  alive: () => boolean
+): Promise<void> {
+  if (!info.title.trim()) throw new Error(`${verb}: title must not be empty`)
+  if (!navigator.mediaSession) throw new Error('Audio: Media Session is unavailable')
+  const ticket = ++claim
+  pendingKey = next.key
+  if (info.artworkUri) {
+    const artwork = new window.Image()
+    artwork.src = info.artworkUri
+    await artwork.decode()
+    if (!alive()) throw new Error(`${verb}: playback was replaced`)
+    if (ticket !== claim) throw new Error(`${verb}: now playing was claimed or cleared again`)
+  }
+  if (pendingKey === next.key) pendingKey = undefined
+  const session = navigator.mediaSession
+  setOwner(next)
+  session.metadata = new MediaMetadata({
+    title: info.title,
+    artist: info.artist,
+    album: info.albumTitle,
+    artwork: info.artworkUri ? [{ src: info.artworkUri }] : [],
+  })
+  install(session)
+  sync()
+}
+
+export function releaseNowPlaying(key: string): void {
+  if (pendingKey === key) {
+    claim++
+    pendingKey = undefined
+  }
+  if (owner?.key !== key) return
+  setOwner(undefined)
+  if (typeof window === 'undefined' || !navigator.mediaSession) return
+  const session = navigator.mediaSession
+  if (installed)
+    for (const action of ['play', 'pause', 'seekto'] as const)
+      session.setActionHandler(action, null)
+  installed = false
+  session.metadata = null
+  session.playbackState = 'none'
+}
+
+export function addRemoteListener(
+  onEvent: (event: AudioRemoteCommandEvent) => void
+): () => void {
+  listeners.add(onEvent)
+  return () => {
+    listeners.delete(onEvent)
+  }
+}