@swiftbrowser/native 0.18.1 → 0.18.3

package/src/hostRequests.ts

@@ -1,6 +1,6 @@
 /**
  * The host requests `@swiftbrowser/react` sends to the browser environment
- * (`ShareLink`, `fileImporter`, the clipboard, a color chooser: the web
+ * (`ShareLink`, `fileImporter`, `fileExporter`, 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
@@ -47,6 +47,7 @@ const pending = new Map<number, { resolve: (value: unknown) => void; reject: (er
 /** Points the requests at the bridge (the runtime, once per install). */
 export function installHostRequests(native: HostRequestBridge): void {
   bridge = native;
+  fileWatchers.clear();
 }
 
 /** The bridge's `__sbHostResponse(id, result)`. */
@@ -135,25 +136,54 @@ function appDirectories(): FileDirectories | null {
   return null;
 }
 
-/** The app's files (`files` requests): `fileManager`'s host over the sandbox. */
+/** Who hears about the files iCloud Drive changed (`watch`). */
+const fileWatchers = new Set<(urls: string[]) => void>();
+
+/** The bridge's `__sbFilesChanged(json)`: the URLs another device changed in iCloud Drive (ICloudBridge.swift). */
+export function receiveFilesChanged(json: string | string[]): void {
+  let urls: string[];
+  try {
+    const parsed: unknown = typeof json === 'string' ? JSON.parse(json) : json;
+    urls = Array.isArray(parsed) ? parsed.filter((url): url is string => typeof url === 'string') : [];
+  } catch {
+    return;
+  }
+  if (urls.length === 0) return;
+  for (const listener of [...fileWatchers]) listener(urls);
+}
+
+/** The app's files (`files` requests): `fileManager`'s host over the sandbox, and iCloud Drive's container once asked for. */
 function nativeFiles(directories: FileDirectories): Record<string, unknown> {
   const files = <T>(params: Record<string, unknown>): Promise<T> => hostRequest<T>('files', params);
+  let iCloud: Promise<string | null> | null = null;
   return {
     directories,
+    // The container's Documents (ICloudBridge.swift), resolved once; null without the entitlement or iCloud Drive.
+    iCloud: (): Promise<string | null> => (iCloud ??= files<{ url?: string } | null>({ action: 'iCloud' }).then((found) => (typeof found?.url === 'string' ? found.url : null))),
+    watch: (listener: (urls: string[]) => void): (() => void) => {
+      fileWatchers.add(listener);
+      return () => void fileWatchers.delete(listener);
+    },
     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 });
+    attributes: async (url: string): Promise<{ size: number; modified: number | null; created: number | null; directory: boolean; type: string } | null> => {
+      const found = await files<{ size?: number; modified?: number | null; created?: number | null; directory?: boolean; type?: string } | 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 };
+      return {
+        size: found.size,
+        modified: typeof found.modified === 'number' ? found.modified : null,
+        created: typeof found.created === 'number' ? found.created : null,
+        directory: found.directory === true,
+        type: typeof found.type === 'string' ? found.type : '',
+      };
     },
     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,
+    // AVPlayer and UIImage read the file themselves, once it is on the device (a file another device put in iCloud Drive is downloaded first).
+    loadURL: async (url: string): Promise<string> => (await files<{ url?: string } | null>({ action: 'download', url }))?.url ?? url,
   };
 }
 
@@ -180,6 +210,11 @@ export function nativeHostEnvironment(): Record<string, unknown> {
       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 })),
+    // `fileExporter`: the document picker, saving the files where the viewer chooses.
+    exportFiles: async (files: SimpleFile[]): Promise<{ outcome: string; urls?: string[] }> => {
+      const result = await hostRequest<{ outcome?: string; urls?: string[] } | null>('exportFiles', { files: await Promise.all(files.map(bridgedFile)) });
+      return { outcome: result?.outcome ?? 'cancelled', ...(result?.urls ? { urls: result.urls } : {}) };
+    },
     objectURL: (file: SimpleBlob): string => objectURL(file),
     clipboard: {
       writeText: (text: string): Promise<void> => hostRequest('clipboard', { action: 'write', text }).then(() => undefined),
@@ -190,6 +225,11 @@ export function nativeHostEnvironment(): Record<string, unknown> {
       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,
+    // Sign in with Apple (AppleSignInBridge.swift): the system sheet, and the credential's state.
+    appleSignIn: {
+      signIn: (options: { scopes: string[]; nonce?: string; state?: string }): Promise<unknown> => hostRequest('appleSignIn', { action: 'signIn', ...options }),
+      credentialState: async (user: string): Promise<string> => (await hostRequest<{ state?: string } | null>('appleSignIn', { action: 'credentialState', user }))?.state ?? 'unknown',
+    },
     // `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),

package/src/index.ts

@@ -13,6 +13,7 @@
 
 export { run, type RunOptions, type Running } from './run';
 export { Native, type NativeProps } from './native';
+export { callNative, callNativeSync, nativeFunctions, hasNativeFunction, onNativeEvent } from './nativeFunctions';
 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';

package/src/nativeFunctions.ts

@@ -0,0 +1,94 @@
+/**
+ * Swift the app calls: the function half of the escape hatch (docs/native.md;
+ * `<Native>` in native.ts is the view half). The Swift app registers
+ * functions with `NativeFunctions.register(name) { call in ... }`
+ * (Native/Sources/SwiftBrowserNative/Runtime/NativeFunctions.swift);
+ * `callNative(name, params)` runs one and resolves with what it returned,
+ * through the host request `app:<name>` (hostRequests.ts), `callNativeSync`
+ * runs a sync one inline over the bridge's `callNativeSync(name, json)`, and
+ * `nativeFunctions()` lists them over `nativeFunctions()`. What Swift sends
+ * with `NativeFunctions.send(name, value)` arrives at `__sbNativeEvent(name,
+ * json)` and reaches `onNativeEvent(name)`'s listeners.
+ *
+ * On a page, or in a host without the functions, `callNative` rejects and
+ * `callNativeSync` throws `unsupported:`, and `nativeFunctions()` is empty:
+ * an app checks `hasNativeFunction(name)` and falls back to the web's way.
+ * A function that throws `NativeFunctionCancelled` rejects with an
+ * `AbortError`, as the system pickers' cancellations do.
+ */
+
+import type { NativeBridge } from './bridge';
+import { hostRequest } from './hostRequests';
+
+export type NativeFunctionsBridge = Pick<NativeBridge, 'nativeFunctions' | 'callNativeSync'>;
+
+let bridge: NativeFunctionsBridge | null = null;
+const listeners = new Map<string, Set<(value: unknown) => void>>();
+
+/** Points the functions at the bridge (the runtime, once per install); null forgets it. */
+export function installNativeFunctions(native: NativeFunctionsBridge | null): void {
+  bridge = native;
+  listeners.clear();
+}
+
+/** The names the Swift app registered; empty on a page. */
+export function nativeFunctions(): string[] {
+  return bridge?.nativeFunctions?.() ?? [];
+}
+
+/** Whether the Swift app registered `name`. */
+export function hasNativeFunction(name: string): boolean {
+  return nativeFunctions().includes(name);
+}
+
+/** Runs the function registered under `name` with `params`; resolves with what it returned. */
+export function callNative<T = unknown>(name: string, params: Record<string, unknown> = {}): Promise<T> {
+  return hostRequest<T>(`app:${name}`, params);
+}
+
+/** Runs the sync function registered under `name` inline; returns what it returned. */
+export function callNativeSync<T = unknown>(name: string, params: Record<string, unknown> = {}): T {
+  if (!bridge?.callNativeSync) throw new Error(`unsupported: no native host for ${name}`);
+  let result: { value?: unknown; error?: string };
+  try {
+    result = JSON.parse(bridge.callNativeSync(name, JSON.stringify(params))) as { value?: unknown; error?: string };
+  } catch {
+    throw new Error(`${name}: malformed response`);
+  }
+  if (typeof result.error === 'string') {
+    const error = new Error(result.error);
+    if (result.error.startsWith('cancelled')) error.name = 'AbortError';
+    throw error;
+  }
+  return result.value as T;
+}
+
+/** Listens for what Swift sends under `name` (`NativeFunctions.send`); returns the function that stops listening. */
+export function onNativeEvent<T = unknown>(name: string, listener: (value: T) => void): () => void {
+  let set = listeners.get(name);
+  if (!set) {
+    set = new Set();
+    listeners.set(name, set);
+  }
+  const entry = listener as (value: unknown) => void;
+  set.add(entry);
+  return () => {
+    set.delete(entry);
+    if (set.size === 0) listeners.delete(name);
+  };
+}
+
+/** The bridge's `__sbNativeEvent(name, json)`. */
+export function receiveNativeEvent(name: string, value: unknown): void {
+  const set = listeners.get(name);
+  if (!set) return;
+  let parsed = value;
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return;
+    }
+  }
+  for (const listener of [...set]) listener(parsed);
+}

package/src/reachability.ts

@@ -0,0 +1,49 @@
+/**
+ * `navigator.onLine` and the `online` and `offline` events over the host's
+ * path monitor (`online()` on the bridge, `__sbOnline(bool)` back). The
+ * value is what the host last said (`NWPathMonitor`'s path status, true
+ * where the host has no monitor); the events reach listeners on the global
+ * (`addEventListener('online', …)`, which the runtime defines in the app's
+ * context, where a page's `window` would take them) and the global's
+ * `ononline` and `onoffline` handlers.
+ */
+
+import type { NativeBridge } from './bridge';
+
+type Listener = (event: { type: 'online' | 'offline' }) => void;
+
+export interface Reachability {
+  /** `navigator.onLine`. */
+  readonly onLine: boolean;
+  addEventListener(type: string, listener: Listener): void;
+  removeEventListener(type: string, listener: Listener): void;
+  /** `__sbOnline(online)`: the host's path changed. */
+  receive(online: boolean): void;
+}
+
+export function createReachability(native: NativeBridge, target: Record<string, unknown>): Reachability {
+  let online = native.online?.() ?? true;
+  const listeners = { online: new Set<Listener>(), offline: new Set<Listener>() };
+  const isKind = (type: string): type is 'online' | 'offline' => type === 'online' || type === 'offline';
+  return {
+    get onLine() {
+      return online;
+    },
+    addEventListener(type, listener) {
+      if (isKind(type) && typeof listener === 'function') listeners[type].add(listener);
+    },
+    removeEventListener(type, listener) {
+      if (isKind(type)) listeners[type].delete(listener);
+    },
+    receive(next) {
+      const value = Boolean(next);
+      if (value === online) return;
+      online = value;
+      const type = value ? 'online' : 'offline';
+      const event = { type } as const;
+      const handler = target[value ? 'ononline' : 'onoffline'];
+      if (typeof handler === 'function') (handler as Listener)(event);
+      for (const listener of [...listeners[type]]) listener(event);
+    },
+  };
+}

package/src/run.ts

@@ -8,7 +8,7 @@
  * ran and its pass was applied (docs/native.md, "Synchronous calls").
  */
 
-import { createSwiftUIRoot, installTextMeasurer, type SwiftUIRoot, type TextMeasurerFunction } from '@swiftbrowser/react';
+import { createSwiftUIRoot, installTextMeasurer, type Environment, type SwiftUIRoot, type TextMeasurerFunction } from '@swiftbrowser/react';
 import type { Op, RendererEvent } from '@swiftbrowser/web/src/protocol';
 import type { ReactNode } from 'react';
 import { browserEnvironment } from '@swiftbrowser/web/src/hostRequests';
@@ -35,6 +35,7 @@ interface EnvironmentFields {
   colorScheme?: 'light' | 'dark';
   dynamicTypeSize?: string;
   horizontalSizeClass?: 'compact' | 'regular';
+  scenePhase?: 'active' | 'inactive' | 'background';
 }
 
 /** The running app, when `run` was called (the dev loop calls it again on every save). */
@@ -82,13 +83,14 @@ export function run(element: ReactNode, options: RunOptions = {}): Running {
     try {
       if (parsed.type === 'environment') {
         const fields = parsed as EnvironmentFields;
-        const next: Partial<{ colorScheme: 'light' | 'dark'; dynamicTypeSize: never; horizontalSizeClass: 'compact' | 'regular' }> = {};
+        const next: Partial<Environment> = {};
         if (fields.colorScheme) {
           next.colorScheme = fields.colorScheme;
           updateMediaEnvironment({ colorScheme: fields.colorScheme });
         }
-        if (fields.dynamicTypeSize) (next as Record<string, unknown>)['dynamicTypeSize'] = fields.dynamicTypeSize;
+        if (fields.dynamicTypeSize) next.dynamicTypeSize = fields.dynamicTypeSize as Environment['dynamicTypeSize'];
         if (fields.horizontalSizeClass) next.horizontalSizeClass = fields.horizontalSizeClass;
+        if (fields.scenePhase) next.scenePhase = fields.scenePhase;
         if (Object.keys(next).length > 0) root.setEnvironment(next);
         return;
       }

package/src/runtime.ts

@@ -11,12 +11,19 @@
  * `atob`, `btoa`, `fetch` with `Headers`, `Request`, `Response`,
  * `AbortController` and `AbortSignal`, `URL`, `URLSearchParams`, `crypto`
  * (`getRandomValues`, `randomUUID`), `localStorage`, `structuredClone`,
- * `navigator` (with `mediaSession` and `MediaMetadata` on a bridge with
+ * `navigator` (with `onLine` from the host's path monitor, reachability.ts,
+ * whose `online` and `offline` events `addEventListener` on the global takes
+ * with the bridge's `__sbOnline`; with `wakeLock` and `WakeLockSentinel` on
+ * a bridge with `wakeLock`, wakeLock.ts; with `geolocation` and
+ * `GeolocationPositionError` on a bridge with `geolocation`, geolocation.ts,
+ * with the bridge's `__sbGeolocation`; with `mediaSession` and `MediaMetadata` on a bridge with
  * `mediaSession`, mediaSession.ts), `Image` (image.ts, on a bridge with `probeImage`) with the
  * bridge's `__sbImageProbed`, `Worker` (worker.ts) with the bridge's
  * `__sbWorkerMessage` and `__sbWorkerError`, `__sbOpenURL` (openURL.ts),
  * `__sbNotificationPermission`, `__sbPushRegistered` and `__sbNotification` (notifications.ts),
- * `__sbUndoCommand` (undo.ts, on a bridge with `undoState`),
+ * `__sbUndoCommand` (undo.ts, on a bridge with `undoState`), `speechSynthesis`,
+ * `SpeechSynthesisUtterance` and `__sbSpeechEvent` on a bridge with `speak`,
+ * `SpeechRecognition` and `__sbRecognition` on one with `recognize` (speech.ts),
  * and the bridge's callbacks `__sbTimerFired` and `__sbFetchResult`. In a
  * worker's own context (its bridge has
  * `workerPostMessage`), `self`, `postMessage`, `addEventListener` and
@@ -40,7 +47,12 @@ import { NativeWebSocket } from './webSocket';
 import { createSubtleCrypto } from './subtle';
 import { matchMedia } from './matchMedia';
 import { createUndoHost, installUndoHost } from './undo';
-import { installHostRequests, receiveHostResponse } from './hostRequests';
+import { installHostRequests, receiveFilesChanged, receiveHostResponse } from './hostRequests';
+import { installNativeFunctions, receiveNativeEvent } from './nativeFunctions';
+import { createReachability } from './reachability';
+import { createWakeLock, WakeLockSentinel } from './wakeLock';
+import { createGeolocation, GeolocationPositionError } from './geolocation';
+import { createSpeechSynthesis, SpeechRecognition, SpeechSynthesisUtterance } from './speech';
 
 type AnyGlobal = Record<string, unknown>;
 
@@ -209,6 +221,15 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
   if (native.hostRequest && !native.workerPostMessage) {
     installHostRequests({ hostRequest: native.hostRequest.bind(native), ...(native.appDirectories ? { appDirectories: native.appDirectories.bind(native) } : {}) });
     define('__sbHostResponse', receiveHostResponse);
+    define('__sbFilesChanged', receiveFilesChanged);
+    // The escape hatch's functions (nativeFunctions.ts): `callNative` rides `hostRequest`.
+    installNativeFunctions({
+      ...(native.nativeFunctions ? { nativeFunctions: native.nativeFunctions.bind(native) } : {}),
+      ...(native.callNativeSync ? { callNativeSync: native.callNativeSync.bind(native) } : {}),
+    });
+    define('__sbNativeEvent', receiveNativeEvent);
+  } else {
+    installNativeFunctions(null);
   }
 
   // The window's undo manager (undo.ts), mirroring the app's: the system's undo comes to `__sbUndoCommand`.
@@ -259,11 +280,15 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
 
   define('structuredClone', <T>(value: T): T => (value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T)));
 
+  // Reachability (reachability.ts): `navigator.onLine` from the host's path monitor.
+  const reachability = createReachability(native, target);
   const navigator: Record<string, unknown> = {
     userAgent: 'SwiftBrowserNative',
     language: native.locale().replace('_', '-'),
     languages: [native.locale().replace('_', '-')],
-    onLine: true,
+    get onLine() {
+      return reachability.onLine;
+    },
     platform: 'iOS',
     hardwareConcurrency: 1,
     // A haptic for a vibration; the pattern's length does not matter.
@@ -275,6 +300,12 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
       return true;
     },
   };
+  // The screen wake lock (wakeLock.ts) over the host's idle timer; not in a worker.
+  const wakeLock = native.wakeLock && !native.workerPostMessage ? createWakeLock(native) : null;
+  if (wakeLock) navigator['wakeLock'] = wakeLock;
+  // The viewer's position (geolocation.ts) over the host's location manager; not in a worker.
+  const geolocation = native.geolocation && !native.workerPostMessage ? createGeolocation(native, target) : null;
+  if (geolocation) navigator['geolocation'] = geolocation.geolocation;
   // What plays, for the lock screen and the media keys (mediaSession.ts); not in a worker.
   const mediaSession = native.mediaSession && !native.workerPostMessage ? createMediaSession(native) : null;
   if (mediaSession) navigator['mediaSession'] = mediaSession.session;
@@ -286,6 +317,24 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
     navigator['clearAppBadge'] = notifications.clearAppBadge;
   }
   define('navigator', navigator);
+  if (wakeLock) define('WakeLockSentinel', WakeLockSentinel);
+  if (geolocation) {
+    define('GeolocationPositionError', GeolocationPositionError);
+    define('__sbGeolocation', geolocation.receive);
+  }
+  // Speech (speech.ts): synthesis on AVSpeechSynthesizer, recognition on SFSpeechRecognizer; not in a worker.
+  if (native.speak && native.speechControl && !native.workerPostMessage) {
+    const synthesis = createSpeechSynthesis(native);
+    define('speechSynthesis', synthesis.speechSynthesis);
+    define('SpeechSynthesisUtterance', SpeechSynthesisUtterance);
+    define('__sbSpeechEvent', synthesis.receive);
+  }
+  if (native.recognize && !native.workerPostMessage) {
+    SpeechRecognition.install({ recognize: native.recognize.bind(native) });
+    define('SpeechRecognition', SpeechRecognition);
+    define('webkitSpeechRecognition', SpeechRecognition);
+    define('__sbRecognition', SpeechRecognition.receive);
+  }
   if (mediaSession) {
     define('MediaMetadata', NativeMediaMetadata);
     define('__sbMediaSessionCommand', mediaSession.receive);
@@ -300,8 +349,12 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
   if (native.workerPostMessage) {
     installed.push(...installWorkerScope(native, target));
   } else {
-    // The app's context: the URLs it is opened with (openURL.ts), and workers.
+    // The app's context: the URLs it is opened with (openURL.ts), the
+    // `online` and `offline` events (a page's `window` takes them), and workers.
     define('__sbOpenURL', receiveOpenURL);
+    define('addEventListener', reachability.addEventListener);
+    define('removeEventListener', reachability.removeEventListener);
+    define('__sbOnline', reachability.receive);
     if (native.workerStart) {
       define('Worker', NativeWorker);
       define('__sbWorkerMessage', NativeWorker.receive);