@swiftbrowser/native 0.17.6 → 0.17.8

package/src/bridge.ts

@@ -3,7 +3,9 @@
  * (Native/Sources/SwiftBrowserNative/Host/HostBridge.swift). Every call is
  * synchronous; the ones that answer later do so by calling a global this
  * package defines (`__sbTimerFired`, `__sbFetchResult`, `__sbImageProbed`,
- * `__sbWorkerMessage`, `__sbOpenURL`).
+ * `__sbWorkerMessage`, `__sbOpenURL`, `__sbMediaSessionCommand`,
+ * `__sbNotificationPermission`, `__sbPushRegistered`, `__sbNotification`,
+ * `__sbWebSocketEvent`, `__sbHostResponse`).
  */
 export interface NativeBridge {
   /** Applies a render pass's ops (a JSON array). Returns an error message, or nothing. */
@@ -35,6 +37,60 @@ export interface NativeBridge {
   locale(): string;
   /** The process's launch arguments (`-screen list` from an Xcode scheme or `simctl launch`). */
   launchArguments?(): string[];
+  /**
+   * `navigator.mediaSession` (mediaSession.ts): the whole session as JSON
+   * (`metadata`, `playbackState`, `position`, `commands`, as the web
+   * renderer's `mediaSession` request carries them), for the lock screen
+   * and the media keys; a command the viewer gives arrives at
+   * `__sbMediaSessionCommand(json)`. Hosts before 0.19 lack it.
+   */
+  mediaSession?(update: string): void;
+
+  // Notifications (notifications.ts), on UserNotifications. Hosts before 0.20 lack them.
+  /** The app listens: what came before it did (a tap that launched it) arrives at `__sbNotification(json)`. */
+  notificationsReady?(): void;
+  /** Answers `__sbNotificationPermission(id, 'default' | 'granted' | 'denied')`, after asking the viewer when `request` is set. */
+  notificationPermission?(id: number, request: boolean): void;
+  /** Shows `{ id, title, subtitle?, body?, data?, badge?, silent? }` now; returns what was wrong with it, or nothing. */
+  notificationShow?(json: string): string | null | undefined;
+  /** Closes the notifications with these identifiers (a JSON array). */
+  notificationClose?(json: string): void;
+  /** The app badge (0 clears it). */
+  setBadge?(count: number): void;
+  /**
+   * Registers for remote notifications; the device token (hex) or the
+   * failure answers `__sbPushRegistered(id, { token } | { error })`.
+   * `applicationServerKey` is for the page (the round trip's Web Push).
+   */
+  pushRegister?(id: number, applicationServerKey?: string): void;
+
+  // WebSockets (webSocket.ts) on `URLSessionWebSocketTask`; events come to `__sbWebSocketEvent(id, json)`. Hosts before 0.20 lack them.
+  wsOpen?(id: number, url: string, protocols: string[]): void;
+  /** `{ text }` or `{ binary }` (base64), as JSON. */
+  wsSend?(id: number, json: string): void;
+  wsClose?(id: number, code: number, reason: string): void;
+
+  // `crypto.subtle` (subtle.ts) on CryptoKit, synchronously. Hosts before 0.20 lack them.
+  /** The base64 digest of base64 `data` under `algorithm` (`SHA-256`, …), or nothing when the host cannot. */
+  digest?(algorithm: string, data: string): string | null | undefined;
+  /** The base64 HMAC of base64 `data` with base64 `key` under the hash `algorithm`, or nothing. */
+  hmac?(algorithm: string, key: string, data: string): string | null | undefined;
+
+  /** `navigator.vibrate`: a haptic (`impact`, `selection`, `success`, `warning`, `error`). Hosts before 0.20 lack it. */
+  haptic?(kind: string): void;
+
+  /**
+   * A host request of the web renderer's kinds (hostRequests.ts): `share`,
+   * `pickFiles`, `clipboard`, `pickColor` and `webAuth`, with the request's
+   * params as JSON; the answer arrives at `__sbHostResponse(id, { value } | { error })`.
+   * Hosts before 0.20 lack it.
+   */
+  hostRequest?(id: number, kind: string, json: string): void;
+
+  // The Keychain (secureStorage.ts). Hosts before 0.20 lack them.
+  secureGet?(key: string): string | null;
+  secureSet?(key: string, value: string): void;
+  secureRemove?(key: string): void;
 
   // Workers (worker.ts): a second context on its own thread, from a bundle
   // `swiftbrowser-native build --worker <name>=<entry>` wrote next to app.js

package/src/fetch.ts

@@ -1,11 +1,13 @@
 /**
  * `fetch`, `Headers`, `Request`, `Response` and `AbortController` over the
  * bridge's `fetch` primitive (`URLSession` on the Swift side). Bodies cross
- * as base64; a `Response` reads them back as text, JSON or bytes. Streams
- * and `Blob` are not here: a body is whole.
+ * as base64; a `Response` reads them back as text, JSON, bytes or a `Blob`.
+ * A `Blob` or `FormData` body (blob.ts) is sent whole, the form as
+ * multipart; there are no streams.
  */
 
 import type { NativeBridge, NativeFetchResult } from './bridge';
+import { encodeMultipart, SimpleBlob, SimpleFormData } from './blob';
 import { base64Decode, base64Encode, utf8Decode, utf8Encode } from './encoding';
 
 type HeadersInitLike = SimpleHeaders | Record<string, string> | [string, string][];
@@ -114,16 +116,25 @@ function timeoutError(): Error {
   return error;
 }
 
-type BodyInitLike = string | ArrayBuffer | ArrayBufferView | SimpleURLSearchParamsLike | null | undefined;
+type BodyInitLike = string | ArrayBuffer | ArrayBufferView | SimpleURLSearchParamsLike | SimpleBlob | SimpleFormData | null | undefined;
 interface SimpleURLSearchParamsLike {
   toString(): string;
   [Symbol.iterator](): IterableIterator<[string, string]>;
 }
 
+/** The multipart boundary's randomness: the bridge's bytes once the runtime is installed, a counter before. */
+let randomBytes: (count: number) => Uint8Array = (count) => Uint8Array.from({ length: count }, (_, i) => (i * 37 + 11) & 255);
+
+export function setBodyRandomness(random: (count: number) => Uint8Array): void {
+  randomBytes = random;
+}
+
 /** Bytes of a body, and the content type it implies when the caller set none. */
 function encodeBody(body: BodyInitLike): { bytes: Uint8Array | null; contentType: string | null } {
   if (body === null || body === undefined) return { bytes: null, contentType: null };
   if (typeof body === 'string') return { bytes: utf8Encode(body), contentType: 'text/plain;charset=UTF-8' };
+  if (body instanceof SimpleBlob) return { bytes: body.bytes(), contentType: body.type || null };
+  if (body instanceof SimpleFormData) return encodeMultipart(body, randomBytes);
   if (body instanceof ArrayBuffer) return { bytes: new Uint8Array(body), contentType: null };
   if (ArrayBuffer.isView(body)) return { bytes: new Uint8Array(body.buffer, body.byteOffset, body.byteLength), contentType: null };
   if (typeof body === 'object' && Symbol.iterator in body && typeof body.toString === 'function') {
@@ -160,6 +171,13 @@ class Body {
   async json(): Promise<unknown> {
     return JSON.parse(utf8Decode(this.take()));
   }
+  async blob(): Promise<SimpleBlob> {
+    return new SimpleBlob([this.take()], { type: this.contentType() });
+  }
+  /** The body's content type, for `blob()`; a Request or Response reads its headers. */
+  protected contentType(): string {
+    return '';
+  }
 }
 
 export interface RequestInitLike {
@@ -190,6 +208,10 @@ export class SimpleRequest extends Body {
   rawBytes(): Uint8Array | null {
     return this.bytes;
   }
+  protected override contentType(): string {
+    return this.headers.get('content-type') ?? '';
+  }
+
   clone(): SimpleRequest {
     return new SimpleRequest(this, { body: this.bytes });
   }
@@ -222,6 +244,10 @@ export class SimpleResponse extends Body {
   get ok(): boolean {
     return this.status >= 200 && this.status < 300;
   }
+  protected override contentType(): string {
+    return this.headers.get('content-type') ?? '';
+  }
+
   clone(): SimpleResponse {
     return new SimpleResponse(this.bytes, { status: this.status, statusText: this.statusText, headers: this.headers, url: this.url });
   }

package/src/hostRequests.ts

@@ -0,0 +1,148 @@
+/**
+ * The host requests `@swiftbrowser/react` sends to the browser environment
+ * (`ShareLink`, `fileImporter`, the clipboard, a color chooser: the web
+ * renderer's `performHostRequest` with its `browserEnvironment`), answered by
+ * the native app instead: the bridge's `hostRequest(id, kind, json)` performs
+ * one with UIKit (a share sheet, the photo or document picker, the
+ * pasteboard, the color picker, `ASWebAuthenticationSession`), answering
+ * `__sbHostResponse(id, { value } | { error })`. `installHostEnvironment`
+ * fills the environment's gaps with these, leaving what the page has (the
+ * round trip runs in a browser with a share sheet of its own).
+ *
+ * `webAuthenticate` is the sign-in window apps open for OAuth: the system's
+ * sheet, resolving with the callback URL.
+ */
+
+import { objectURL, SimpleBlob, SimpleFile } from './blob';
+import type { NativeBridge } from './bridge';
+import { base64Decode, base64Encode } from './encoding';
+
+export type HostRequestBridge = Required<Pick<NativeBridge, 'hostRequest'>>;
+
+/** A file as it crosses the bridge: its name, MIME type and bytes (base64). */
+export interface BridgedFile {
+  name: string;
+  type: string;
+  data: string;
+}
+
+export interface WebAuthenticateOptions {
+  /** The scheme of the callback URL the sign-in ends with (`myapp` for `myapp://auth`); universal links need none. */
+  callbackScheme?: string;
+  /** Whether the session shares no cookies with the system browser. */
+  ephemeral?: boolean;
+}
+
+let bridge: HostRequestBridge | null = null;
+let nextId = 1;
+const pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+
+/** Points the requests at the bridge (the runtime, once per install). */
+export function installHostRequests(native: HostRequestBridge): void {
+  bridge = native;
+}
+
+/** The bridge's `__sbHostResponse(id, result)`. */
+export function receiveHostResponse(id: number, result: string | { value?: unknown; error?: string }): void {
+  const waiting = pending.get(id);
+  if (!waiting) return;
+  pending.delete(id);
+  let parsed: { value?: unknown; error?: string };
+  try {
+    parsed = typeof result === 'string' ? (JSON.parse(result) as { value?: unknown; error?: string }) : result;
+  } catch {
+    waiting.reject(new Error('host: malformed response'));
+    return;
+  }
+  if (typeof parsed.error === 'string') {
+    const error = new Error(parsed.error);
+    if (parsed.error.startsWith('cancelled')) error.name = 'AbortError';
+    waiting.reject(error);
+  } else {
+    waiting.resolve(parsed.value);
+  }
+}
+
+/** Performs one request of `kind` with `params`; resolves with the host's value. */
+export function hostRequest<T = unknown>(kind: string, params: Record<string, unknown>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    if (!bridge) {
+      reject(new Error(`unsupported: no native host for ${kind}`));
+      return;
+    }
+    const id = nextId++;
+    pending.set(id, { resolve: resolve as (value: unknown) => void, reject });
+    bridge.hostRequest(id, kind, JSON.stringify(params));
+  });
+}
+
+/** Forgets the bridge and the waiting requests, for tests. */
+export function resetHostRequests(): void {
+  bridge = null;
+  pending.clear();
+  nextId = 1;
+}
+
+async function bridgedFile(file: SimpleBlob & { name?: string }): Promise<BridgedFile> {
+  return { name: file.name ?? 'file', type: file.type, data: base64Encode(file.bytes()) };
+}
+
+function filesOf(value: unknown): SimpleFile[] {
+  const files = (value as { files?: BridgedFile[] } | undefined)?.files ?? [];
+  return files.map((file) => new SimpleFile([base64Decode(file.data)], file.name, { type: file.type }));
+}
+
+/**
+ * Opens the system's sign-in sheet at `url` and resolves with the callback
+ * URL it ends with; rejects with an `AbortError` when the viewer closes it.
+ */
+export async function webAuthenticate(url: string, options: WebAuthenticateOptions = {}): Promise<string> {
+  const params: Record<string, unknown> = { action: 'start', url };
+  if (options.callbackScheme) params['callbackScheme'] = options.callbackScheme;
+  if (options.ephemeral !== undefined) params['ephemeral'] = options.ephemeral;
+  const result = await hostRequest<{ url?: string }>('webAuth', params);
+  if (typeof result?.url !== 'string') throw new Error('webAuth: the sign-in ended without a URL');
+  return result.url;
+}
+
+/** The environment fields the host answers, shaped as the web renderer's `HostRequestEnvironment`. */
+export function nativeHostEnvironment(): Record<string, unknown> {
+  return {
+    share: async (data: { title?: string; text?: string; url?: string; files?: SimpleFile[] }): Promise<void> => {
+      const params: Record<string, unknown> = {};
+      if (data.title) params['title'] = data.title;
+      if (data.text) params['text'] = data.text;
+      if (data.url) params['url'] = data.url;
+      if (data.files?.length) params['files'] = await Promise.all(data.files.map(bridgedFile));
+      const result = await hostRequest<{ outcome?: string }>('share', params);
+      if (result?.outcome === 'cancelled') {
+        const error = new Error('cancelled: the viewer closed the share sheet');
+        error.name = 'AbortError';
+        throw error;
+      }
+    },
+    canShare: () => true,
+    download: (blob: SimpleBlob, filename: string): void => {
+      void hostRequest('share', { files: [{ name: filename, type: blob.type, data: base64Encode(blob.bytes()) }] }).catch(() => undefined);
+    },
+    pickFiles: async (options: { accept: string; multiple: boolean }): Promise<SimpleFile[]> => filesOf(await hostRequest('pickFiles', { accept: options.accept, multiple: options.multiple })),
+    objectURL: (file: SimpleBlob): string => objectURL(file),
+    clipboard: {
+      writeText: (text: string): Promise<void> => hostRequest('clipboard', { action: 'write', text }).then(() => undefined),
+      writeImage: async (png: Promise<SimpleBlob>): Promise<void> => {
+        const file = await png;
+        await hostRequest('clipboard', { action: 'write', files: [{ name: 'image.png', type: file.type || 'image/png', data: base64Encode(file.bytes()) }] });
+      },
+      readText: async (): Promise<string> => (await hostRequest<{ text?: string }>('clipboard', { action: 'readText' }))?.text ?? '',
+    },
+    pickColor: async (color: string): Promise<string | null> => (await hostRequest<{ color?: string }>('pickColor', { color }))?.color ?? null,
+  };
+}
+
+/** Fills what `environment` lacks with the host's answers; what the page has stays. */
+export function installHostEnvironment(environment: Record<string, unknown>): void {
+  if (!bridge) return;
+  for (const [key, value] of Object.entries(nativeHostEnvironment())) {
+    if (environment[key] === undefined) environment[key] = value;
+  }
+}

package/src/index.ts

@@ -17,6 +17,14 @@ export { installRuntime, type InstallOptions } from './runtime';
 export { nativeBridge, launchArguments, type NativeBridge, type NativeFetchRequest, type NativeFetchResult, type WorkerEngine } from './bridge';
 export { SimpleHeaders, SimpleRequest, SimpleResponse, SimpleAbortController, SimpleAbortSignal, createFetch } from './fetch';
 export { SimpleURL, SimpleURLSearchParams } from './url';
+export { SimpleBlob, SimpleFile, SimpleFormData, encodeMultipart, objectURL } from './blob';
+export { NativeWebSocket, type NativeWebSocketEvent } from './webSocket';
+export { createSubtleCrypto } from './subtle';
+export { matchMedia, updateMediaEnvironment, type MediaEnvironment } from './matchMedia';
+export { hostRequest, webAuthenticate, nativeHostEnvironment, installHostEnvironment, type WebAuthenticateOptions, type BridgedFile } from './hostRequests';
+export { secureStorage, createSecureStorage, type SecureStorage } from './secureStorage';
 export { SimpleTextEncoder, SimpleTextDecoder, base64Encode, base64Decode, utf8Encode, utf8Decode } from './encoding';
 export { createWorker, NativeWorker, encodeMessage, decodeMessage, workerName, type NativeWorkerOptions, type WorkerLike, type WorkerMessageEvent, type WorkerErrorEvent } from './worker';
 export { onOpenURL } from './openURL';
+export { onNotification, registerForPush, type NotificationEvent, type NativeNotificationOptions, type RegisterForPushOptions } from './notifications';
+export { createMediaSession, NativeMediaMetadata, type NativeMediaSession, type MediaMetadataInit, type MediaActionDetails, type MediaActionHandler, type MediaPositionState } from './mediaSession';

package/src/matchMedia.ts

@@ -0,0 +1,79 @@
+/**
+ * `matchMedia` for the native app: `(prefers-color-scheme: dark)` and
+ * `light` follow the color scheme the host sends with the environment
+ * (run.ts hands it over), `(prefers-reduced-motion: reduce)` the host's
+ * accessibility setting when it sends one; every other query matches
+ * nothing. Listeners hear a change when the environment does.
+ */
+
+export interface MediaQueryListLike {
+  readonly media: string;
+  readonly matches: boolean;
+  onchange: ((event: { matches: boolean; media: string }) => void) | null;
+  addEventListener(type: 'change', listener: (event: { matches: boolean; media: string }) => void): void;
+  removeEventListener(type: 'change', listener: (event: { matches: boolean; media: string }) => void): void;
+  /** The older names. */
+  addListener(listener: (event: { matches: boolean; media: string }) => void): void;
+  removeListener(listener: (event: { matches: boolean; media: string }) => void): void;
+}
+
+export interface MediaEnvironment {
+  colorScheme?: 'light' | 'dark';
+  reducedMotion?: boolean;
+}
+
+type Listener = (event: { matches: boolean; media: string }) => void;
+
+let environment: MediaEnvironment = {};
+const lists = new Set<{ media: string; matches: boolean; listeners: Set<Listener>; onchange: Listener | null }>();
+
+function evaluate(query: string): boolean {
+  const normalized = query.trim().toLowerCase().replace(/\s+/g, '');
+  if (normalized === '(prefers-color-scheme:dark)') return environment.colorScheme === 'dark';
+  if (normalized === '(prefers-color-scheme:light)') return environment.colorScheme !== 'dark';
+  if (normalized === '(prefers-reduced-motion:reduce)') return environment.reducedMotion === true;
+  if (normalized === '(prefers-reduced-motion:no-preference)') return environment.reducedMotion !== true;
+  return false;
+}
+
+/** The runtime's `matchMedia(query)`. */
+export function matchMedia(query: string): MediaQueryListLike {
+  const media = String(query);
+  const state = { media, matches: evaluate(media), listeners: new Set<Listener>(), onchange: null as Listener | null };
+  lists.add(state);
+  return {
+    media,
+    get matches() {
+      return state.matches;
+    },
+    get onchange() {
+      return state.onchange;
+    },
+    set onchange(listener) {
+      state.onchange = listener;
+    },
+    addEventListener: (_type, listener) => void state.listeners.add(listener),
+    removeEventListener: (_type, listener) => void state.listeners.delete(listener),
+    addListener: (listener) => void state.listeners.add(listener),
+    removeListener: (listener) => void state.listeners.delete(listener),
+  };
+}
+
+/** What the host sent with the environment; lists whose answer changed tell their listeners. */
+export function updateMediaEnvironment(next: MediaEnvironment): void {
+  environment = { ...environment, ...next };
+  for (const state of lists) {
+    const matches = evaluate(state.media);
+    if (matches === state.matches) continue;
+    state.matches = matches;
+    const event = { matches, media: state.media };
+    state.onchange?.(event);
+    for (const listener of state.listeners) listener(event);
+  }
+}
+
+/** Forgets the environment and the lists, for tests. */
+export function resetMediaEnvironment(): void {
+  environment = {};
+  lists.clear();
+}

package/src/mediaSession.ts

@@ -0,0 +1,163 @@
+/**
+ * `navigator.mediaSession` and `MediaMetadata` for the native app: what an
+ * audio app tells the browser about what plays (the lock screen, the media
+ * keys) reaches the host's `mediaSession(update)` instead, which sets
+ * `MPNowPlayingInfoCenter` and `MPRemoteCommandCenter` (HostBridge.swift,
+ * NowPlayingBridge.swift); the commands the viewer gives come back to
+ * `__sbMediaSessionCommand(json)` and run the handlers `setActionHandler`
+ * registered, with the details the browser would give (`seekTime`,
+ * `seekOffset`). The update is the one the web renderer's `mediaSession`
+ * request carries (docs/ops-protocol.md, "Now playing"), so an app writes
+ * the same code for the page and the native app. In the page (the round
+ * trip) the page's own `navigator.mediaSession` is there already and
+ * nothing is installed over it.
+ */
+
+import type { NativeBridge } from './bridge';
+
+type Action = 'play' | 'pause' | 'stop' | 'nexttrack' | 'previoustrack' | 'seekto' | 'seekforward' | 'seekbackward' | 'skipad' | 'togglemicrophone' | 'togglecamera' | 'hangup';
+
+/** The protocol's command each Media Session action is; the rest get no button. */
+const COMMANDS: Partial<Record<Action, string>> = {
+  play: 'play',
+  pause: 'pause',
+  stop: 'stop',
+  nexttrack: 'nextTrack',
+  previoustrack: 'previousTrack',
+  seekto: 'seekTo',
+  seekforward: 'skipForward',
+  seekbackward: 'skipBackward',
+};
+
+export interface MediaImage {
+  src: string;
+  sizes?: string;
+  type?: string;
+}
+
+export interface MediaMetadataInit {
+  title?: string;
+  artist?: string;
+  album?: string;
+  artwork?: MediaImage[];
+}
+
+/** The browser's `MediaMetadata`. */
+export class NativeMediaMetadata {
+  title: string;
+  artist: string;
+  album: string;
+  artwork: MediaImage[];
+
+  constructor(init: MediaMetadataInit = {}) {
+    this.title = init.title ?? '';
+    this.artist = init.artist ?? '';
+    this.album = init.album ?? '';
+    this.artwork = (init.artwork ?? []).map((image) => ({ ...image }));
+  }
+}
+
+export interface MediaPositionState {
+  duration?: number;
+  playbackRate?: number;
+  position?: number;
+}
+
+export interface MediaActionDetails {
+  action: Action;
+  seekTime?: number;
+  seekOffset?: number;
+}
+
+export type MediaActionHandler = (details: MediaActionDetails) => void;
+
+/** The browser's `navigator.mediaSession`, as far as audio apps use it. */
+export interface NativeMediaSession {
+  metadata: NativeMediaMetadata | null;
+  playbackState: 'none' | 'playing' | 'paused';
+  setPositionState(state?: MediaPositionState): void;
+  setActionHandler(action: Action, handler: MediaActionHandler | null): void;
+}
+
+/** A command the host received: the protocol's name, with the position of a seek or the interval of a skip. */
+interface ReceivedCommand {
+  command: string;
+  position?: number;
+  interval?: number;
+}
+
+export function createMediaSession(native: Pick<NativeBridge, 'mediaSession'>): { session: NativeMediaSession; receive: (json: string) => void } {
+  let metadata: NativeMediaMetadata | null = null;
+  let playbackState: NativeMediaSession['playbackState'] = 'none';
+  let position: MediaPositionState | null = null;
+  const handlers = new Map<Action, MediaActionHandler>();
+
+  // The whole state each time: the host keeps what it has and changes what differs.
+  const sync = (): void => {
+    const commands = [...handlers.keys()].map((action) => COMMANDS[action]).filter((command): command is string => command !== undefined);
+    native.mediaSession?.(
+      JSON.stringify({
+        metadata: metadata === null ? null : { title: metadata.title, artist: metadata.artist, album: metadata.album, artwork: metadata.artwork[0]?.src },
+        playbackState,
+        position:
+          position === null
+            ? null
+            : { duration: Number.isFinite(position.duration) ? position.duration : 0, position: position.position ?? 0, rate: position.playbackRate ?? 1 },
+        commands,
+      }),
+    );
+  };
+
+  const session: NativeMediaSession = {
+    get metadata() {
+      return metadata;
+    },
+    set metadata(value) {
+      metadata = value === null || value === undefined ? null : value instanceof NativeMediaMetadata ? value : new NativeMediaMetadata(value as MediaMetadataInit);
+      sync();
+    },
+    get playbackState() {
+      return playbackState;
+    },
+    set playbackState(value) {
+      if (value !== 'none' && value !== 'playing' && value !== 'paused') throw new TypeError(`${String(value)} is not a valid MediaSessionPlaybackState`);
+      playbackState = value;
+      sync();
+    },
+    setPositionState(state) {
+      if (state === undefined || state.duration === undefined) {
+        position = null;
+      } else {
+        if (!(state.duration >= 0)) throw new TypeError('the duration must be a non-negative number');
+        if (state.position !== undefined && (state.position < 0 || state.position > state.duration)) throw new TypeError('the position must be within the duration');
+        position = { ...state };
+      }
+      sync();
+    },
+    setActionHandler(action, handler) {
+      if (!(action in COMMANDS) && !['skipad', 'togglemicrophone', 'togglecamera', 'hangup'].includes(action)) throw new TypeError(`${String(action)} is not a valid MediaSessionAction`);
+      if (handler) handlers.set(action, handler);
+      else handlers.delete(action);
+      sync();
+    },
+  };
+
+  const receive = (json: string): void => {
+    let received: ReceivedCommand;
+    try {
+      received = JSON.parse(json) as ReceivedCommand;
+    } catch {
+      return;
+    }
+    const action = (Object.keys(COMMANDS) as Action[]).find((name) => COMMANDS[name] === received.command);
+    if (!action) return;
+    const handler = handlers.get(action);
+    if (!handler) return;
+    const details: MediaActionDetails = { action };
+    if (action === 'seekto' && typeof received.position === 'number') details.seekTime = received.position;
+    if ((action === 'seekforward' || action === 'seekbackward') && typeof received.interval === 'number') details.seekOffset = received.interval;
+    handler(details);
+  };
+
+  return { session, receive };
+}