@swiftbrowser/native 0.17.7 → 0.18.0

package/src/blob.ts

@@ -0,0 +1,186 @@
+/**
+ * `Blob`, `File` and `FormData` for the native app: bytes with a type, a
+ * named one, and a form whose entries `fetch` sends as multipart. A body is
+ * still whole (no streams); `URL.createObjectURL` gives a `data:` URL, which
+ * the host's image loader and `URLSession` both read, and
+ * `revokeObjectURL` has nothing to free.
+ */
+
+import { base64Encode, utf8Decode, utf8Encode } from './encoding';
+
+export type BlobPartLike = string | ArrayBuffer | ArrayBufferView | SimpleBlob;
+
+export interface BlobOptions {
+  type?: string;
+}
+
+export interface FileOptions extends BlobOptions {
+  lastModified?: number;
+}
+
+function partBytes(part: BlobPartLike): Uint8Array {
+  if (typeof part === 'string') return utf8Encode(part);
+  if (part instanceof SimpleBlob) return part.bytes();
+  if (part instanceof ArrayBuffer) return new Uint8Array(part.slice(0));
+  if (ArrayBuffer.isView(part)) return new Uint8Array(part.buffer.slice(part.byteOffset, part.byteOffset + part.byteLength));
+  return utf8Encode(String(part));
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  return out;
+}
+
+/** The browser's `Blob`: bytes and a MIME type. */
+export class SimpleBlob {
+  private readonly data: Uint8Array;
+  readonly type: string;
+
+  constructor(parts: Iterable<BlobPartLike> = [], options: BlobOptions = {}) {
+    this.data = concat([...parts].map(partBytes));
+    // As the browser does: lowercased, and empty when it is not printable ASCII.
+    const type = options.type ?? '';
+    this.type = /^[\x20-\x7e]*$/.test(type) ? type.toLowerCase() : '';
+  }
+
+  get size(): number {
+    return this.data.byteLength;
+  }
+
+  /** The bytes (a view; callers must not write into it). */
+  bytes(): Uint8Array {
+    return this.data;
+  }
+
+  slice(start = 0, end = this.size, contentType = ''): SimpleBlob {
+    const from = start < 0 ? Math.max(this.size + start, 0) : Math.min(start, this.size);
+    const to = end < 0 ? Math.max(this.size + end, 0) : Math.min(end, this.size);
+    return new SimpleBlob([this.data.subarray(from, Math.max(from, to))], { type: contentType });
+  }
+
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    return this.data.buffer.slice(this.data.byteOffset, this.data.byteOffset + this.data.byteLength) as ArrayBuffer;
+  }
+
+  async text(): Promise<string> {
+    return utf8Decode(this.data);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'Blob';
+  }
+}
+
+/** The browser's `File`: a `Blob` with a name. */
+export class SimpleFile extends SimpleBlob {
+  readonly name: string;
+  readonly lastModified: number;
+
+  constructor(parts: Iterable<BlobPartLike>, name: string, options: FileOptions = {}) {
+    super(parts, options);
+    this.name = String(name);
+    this.lastModified = options.lastModified ?? Date.now();
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'File';
+  }
+}
+
+export type FormDataEntryValueLike = string | SimpleFile;
+
+/** The browser's `FormData`, as far as a request body needs it. */
+export class SimpleFormData {
+  private entries_: [string, FormDataEntryValueLike][] = [];
+
+  private static value(value: unknown, filename?: string): FormDataEntryValueLike {
+    if (value instanceof SimpleBlob) {
+      const name = filename ?? (value instanceof SimpleFile ? value.name : 'blob');
+      return value instanceof SimpleFile && filename === undefined ? value : new SimpleFile([value], name, { type: value.type });
+    }
+    return String(value);
+  }
+
+  append(name: string, value: unknown, filename?: string): void {
+    this.entries_.push([String(name), SimpleFormData.value(value, filename)]);
+  }
+
+  set(name: string, value: unknown, filename?: string): void {
+    const key = String(name);
+    const entry: [string, FormDataEntryValueLike] = [key, SimpleFormData.value(value, filename)];
+    const index = this.entries_.findIndex(([entryName]) => entryName === key);
+    if (index < 0) {
+      this.entries_.push(entry);
+      return;
+    }
+    this.entries_ = this.entries_.filter(([entryName], position) => position === index || entryName !== key);
+    this.entries_[index] = entry;
+  }
+
+  get(name: string): FormDataEntryValueLike | null {
+    return this.entries_.find(([entryName]) => entryName === String(name))?.[1] ?? null;
+  }
+
+  getAll(name: string): FormDataEntryValueLike[] {
+    return this.entries_.filter(([entryName]) => entryName === String(name)).map(([, value]) => value);
+  }
+
+  has(name: string): boolean {
+    return this.entries_.some(([entryName]) => entryName === String(name));
+  }
+
+  delete(name: string): void {
+    this.entries_ = this.entries_.filter(([entryName]) => entryName !== String(name));
+  }
+
+  *entries(): IterableIterator<[string, FormDataEntryValueLike]> {
+    yield* this.entries_;
+  }
+
+  *keys(): IterableIterator<string> {
+    for (const [name] of this.entries_) yield name;
+  }
+
+  *values(): IterableIterator<FormDataEntryValueLike> {
+    for (const [, value] of this.entries_) yield value;
+  }
+
+  forEach(callback: (value: FormDataEntryValueLike, name: string, form: SimpleFormData) => void): void {
+    for (const [name, value] of this.entries_) callback(value, name, this);
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, FormDataEntryValueLike]> {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'FormData';
+  }
+}
+
+/** A multipart/form-data body for the form, with the boundary `random` makes unique. */
+export function encodeMultipart(form: SimpleFormData, random: (count: number) => Uint8Array): { bytes: Uint8Array; contentType: string } {
+  const boundary = `----SwiftBrowserFormBoundary${Array.from(random(16), (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+  const escape = (text: string): string => text.replace(/\r/g, '%0D').replace(/\n/g, '%0A').replace(/"/g, '%22');
+  const parts: Uint8Array[] = [];
+  for (const [name, value] of form.entries()) {
+    const head = [`--${boundary}`, `Content-Disposition: form-data; name="${escape(name)}"` + (typeof value === 'string' ? '' : `; filename="${escape(value.name)}"`)];
+    if (typeof value !== 'string') head.push(`Content-Type: ${value.type || 'application/octet-stream'}`);
+    parts.push(utf8Encode(`${head.join('\r\n')}\r\n\r\n`));
+    parts.push(typeof value === 'string' ? utf8Encode(value) : value.bytes());
+    parts.push(utf8Encode('\r\n'));
+  }
+  parts.push(utf8Encode(`--${boundary}--\r\n`));
+  return { bytes: concat(parts), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
+/** `URL.createObjectURL`: a `data:` URL holding the blob. */
+export function objectURL(blob: SimpleBlob): string {
+  return `data:${blob.type || 'application/octet-stream'};base64,${base64Encode(blob.bytes())}`;
+}

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`, `__sbMediaSessionCommand`).
+ * `__sbWorkerMessage`, `__sbOpenURL`, `__sbMediaSessionCommand`,
+ * `__sbNotificationPermission`, `__sbPushRegistered`, `__sbNotification`,
+ * `__sbWebSocketEvent`, `__sbHostResponse`, `__sbUndoCommand`).
  */
 export interface NativeBridge {
   /** Applies a render pass's ops (a JSON array). Returns an error message, or nothing. */
@@ -44,6 +46,77 @@ export interface NativeBridge {
    */
   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 app's undo manager's state (undo.ts): `{ canUndo, canRedo,
+   * undoActionName, redoActionName }` as JSON, which the host mirrors on the
+   * window's `UndoManager` so the system's undo reaches the app; the undo or
+   * redo the system asks for arrives at `__sbUndoCommand('undo' | 'redo')`.
+   * Hosts before 0.18 lack it.
+   */
+  undoState?(json: string): void;
+
+  /**
+   * `measureText` (@swiftbrowser/react): the size `text` in `font` (a Font
+   * JSON object over the body font) takes wrapped to `width` points (one
+   * line when null), from `NSAttributedString`'s bounding rect, synchronously:
+   * `{ width, height, lines }`, or nothing when the host cannot measure.
+   * Hosts before 0.21 lack it.
+   */
+  measureText?(text: string, font: string, width: number | null): { width: number; height: number; lines: number } | null | undefined;
+
+  /**
+   * The app's standard directories as `file:` URLs, a JSON object
+   * `{ documents, applicationSupport, caches, temporary }` (hostRequests.ts
+   * `files`, Host/FilesBridge.swift). Hosts before 0.22 lack it.
+   */
+  appDirectories?(): string | null | undefined;
+
+  // 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
   // (`<name>.worker.js`). The app's context has the first three; a worker's

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,216 @@
+/**
+ * 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`, a recording
+ * from the microphone with `AVAudioRecorder`), answering
+ * `__sbHostResponse(id, { value } | { error })`. `installHostEnvironment`
+ * fills the environment's gaps with these, and with the window's undo
+ * manager (undo.ts), leaving what the page has (the round trip runs in a
+ * browser with a share sheet and a keyboard of its own).
+ *
+ * `webAuthenticate` is the sign-in window apps open for OAuth: the system's
+ * sheet, resolving with the callback URL.
+ *
+ * `files` is the app's sandbox for `fileManager` (@swiftbrowser/react): the
+ * `files` requests of Host/FilesBridge.swift, bytes crossing as base64, with
+ * the standard directories from the bridge's `appDirectories()`.
+ */
+
+import { objectURL, SimpleBlob, SimpleFile } from './blob';
+import type { NativeBridge } from './bridge';
+import { base64Decode, base64Encode } from './encoding';
+import { nativeUndoHost } from './undo';
+
+export type HostRequestBridge = Required<Pick<NativeBridge, 'hostRequest'>> & Pick<NativeBridge, 'appDirectories'>;
+
+/** 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;
+}
+
+interface FileDirectories {
+  documents: string;
+  applicationSupport: string;
+  caches: string;
+  temporary: string;
+}
+
+/** The app's directories the bridge reports, or null on a host without `appDirectories`. */
+function appDirectories(): FileDirectories | null {
+  try {
+    const json = bridge?.appDirectories?.();
+    if (!json) return null;
+    const parsed = JSON.parse(json) as Partial<FileDirectories>;
+    const { documents, applicationSupport, caches, temporary } = parsed;
+    if ([documents, applicationSupport, caches, temporary].every((url) => typeof url === 'string')) {
+      return { documents: documents!, applicationSupport: applicationSupport!, caches: caches!, temporary: temporary! };
+    }
+  } catch {
+    // Malformed: as if the host had none.
+  }
+  return null;
+}
+
+/** The app's files (`files` requests): `fileManager`'s host over the sandbox. */
+function nativeFiles(directories: FileDirectories): Record<string, unknown> {
+  const files = <T>(params: Record<string, unknown>): Promise<T> => hostRequest<T>('files', params);
+  return {
+    directories,
+    read: async (url: string): Promise<Uint8Array> => base64Decode((await files<{ data?: string }>({ action: 'read', url }))?.data ?? ''),
+    write: (url: string, data: Uint8Array): Promise<void> => files({ action: 'write', url, data: base64Encode(data) }).then(() => undefined),
+    remove: (url: string): Promise<void> => files({ action: 'remove', url }).then(() => undefined),
+    createDirectory: (url: string): Promise<void> => files({ action: 'createDirectory', url }).then(() => undefined),
+    list: async (url: string): Promise<string[]> => (await files<{ urls?: string[] }>({ action: 'list', url }))?.urls ?? [],
+    attributes: async (url: string): Promise<{ size: number; modified: number | null; directory: boolean } | null> => {
+      const found = await files<{ size?: number; modified?: number | null; directory?: boolean } | null>({ action: 'attributes', url });
+      if (!found || typeof found.size !== 'number') return null;
+      return { size: found.size, modified: typeof found.modified === 'number' ? found.modified : null, directory: found.directory === true };
+    },
+    move: (from: string, to: string): Promise<void> => files({ action: 'move', from, to }).then(() => undefined),
+    copy: (from: string, to: string): Promise<void> => files({ action: 'copy', from, to }).then(() => undefined),
+    // AVPlayer and UIImage read the file themselves.
+    loadURL: async (url: string): Promise<string> => url,
+  };
+}
+
+/** The environment fields the host answers, shaped as the web renderer's `HostRequestEnvironment`. */
+export function nativeHostEnvironment(): Record<string, unknown> {
+  const directories = appDirectories();
+  return {
+    ...(directories ? { files: nativeFiles(directories) } : {}),
+    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,
+    // `AVAudioRecorder` (AudioRecorderBridge.swift): a recording ends as a file URL in Documents; `trim` writes another.
+    audioRecorder: {
+      start: (): Promise<void> => hostRequest('audioRecord', { action: 'start' }).then(() => undefined),
+      pause: (): Promise<void> => hostRequest('audioRecord', { action: 'pause' }).then(() => undefined),
+      resume: (): Promise<void> => hostRequest('audioRecord', { action: 'resume' }).then(() => undefined),
+      stop: (): Promise<{ url: string; duration: number; type: string }> => hostRequest('audioRecord', { action: 'stop' }),
+      cancel: (): Promise<void> => hostRequest('audioRecord', { action: 'cancel' }).then(() => undefined),
+      meter: (): Promise<{ level: number; time: number }> => hostRequest('audioRecord', { action: 'meter' }),
+      discard: (url: string): Promise<void> => hostRequest('audioRecord', { action: 'discard', url }).then(() => undefined),
+      trim: (url: string, keep: readonly { start: number; end: number }[]): Promise<{ url: string; duration: number; type: string }> =>
+        hostRequest('audioRecord', { action: 'trim', url, keep: keep.map((range) => ({ start: range.start, end: range.end })) }),
+    },
+  };
+}
+
+/** 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;
+  const undo = nativeUndoHost();
+  if (undo && environment['undoManager'] === undefined) environment['undoManager'] = undo;
+  for (const [key, value] of Object.entries(nativeHostEnvironment())) {
+    if (environment[key] === undefined) environment[key] = value;
+  }
+}

package/src/index.ts

@@ -17,7 +17,15 @@ 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 { createUndoHost, nativeUndoHost } from './undo';
 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();
+}