@swiftbrowser/web 0.18.1 → 0.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/appFiles.ts

@@ -132,6 +132,8 @@ export interface EntryRow {
   directory?: boolean;
   /** Milliseconds since the epoch; rows the module wrote (and older rows) have none. */
   modified?: number;
+  /** When it was made, in milliseconds since the epoch, where the writer said. */
+  created?: number;
 }
 
 export const ENTRIES = 'entries';

package/src/appleSignIn.ts

@@ -0,0 +1,140 @@
+/**
+ * Sign in with Apple on a page (docs/ops-protocol.md, "Sign in with Apple"):
+ * Apple's JS (`appleid.auth.js`) in a popup, for an app that configured its
+ * Services ID and return URL with `configureSignInWithApple` (both registered
+ * with Apple for the page's domain). `signIn` loads the script once, asks,
+ * and shapes the answer as `ASAuthorizationAppleIDCredential` does: the
+ * `user` is the identity token's subject, the name and email come only the
+ * first time the viewer agrees. A page cannot ask Apple what a credential is
+ * now, so `credentialState` is `unknown`. Natively the host answers instead
+ * (Host/AppleSignInBridge.swift).
+ */
+
+import { base64Decode } from './base64';
+import type { AppleCredentialState, AppleIDCredential, AppleSignInHost } from './hostRequests';
+
+export interface AppleSignInConfiguration {
+  /** The Services ID registered with Apple for the page's domain (`com.example.app.web`). */
+  clientId: string;
+  /** The return URL registered with it, on this domain (`https://example.com/app/`). */
+  redirectURI: string;
+  /** Apple's script, where a page serves its own copy. */
+  scriptURL?: string;
+}
+
+/** What Apple's script puts on the page. */
+interface AppleIDAuth {
+  init(options: { clientId: string; scope: string; redirectURI: string; state?: string; nonce?: string; usePopup: boolean }): void;
+  signIn(): Promise<AppleSignInResponse>;
+}
+
+interface AppleSignInResponse {
+  authorization: { code: string; id_token: string; state?: string };
+  user?: { email?: string; name?: { firstName?: string; lastName?: string } };
+}
+
+const SCRIPT_URL = 'https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js';
+
+let configuration: AppleSignInConfiguration | null = null;
+
+/** Names the page's Services ID and return URL; before it, a sign-in fails `unsupported: …`. */
+export function configureSignInWithApple(config: AppleSignInConfiguration | null): void {
+  configuration = config;
+}
+
+export function signInWithAppleConfiguration(): AppleSignInConfiguration | null {
+  return configuration;
+}
+
+/** The payload of a JWT, or null when it is not one. */
+export function jwtPayload(token: string): Record<string, unknown> | null {
+  const parts = token.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const base64 = parts[1]!.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(base64Decode(padded)));
+    return parsed !== null && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Apple's answer as the credential the app reads. */
+export function credentialOf(response: AppleSignInResponse): AppleIDCredential {
+  const token = response.authorization?.id_token ?? null;
+  const claims = token ? jwtPayload(token) : null;
+  const user = typeof claims?.['sub'] === 'string' ? (claims['sub'] as string) : '';
+  const email = response.user?.email ?? (typeof claims?.['email'] === 'string' ? (claims['email'] as string) : null);
+  const name = response.user?.name;
+  return {
+    user,
+    email,
+    fullName: name
+      ? { givenName: name.firstName ?? null, familyName: name.lastName ?? null, middleName: null, namePrefix: null, nameSuffix: null, nickname: null }
+      : null,
+    identityToken: token,
+    authorizationCode: response.authorization?.code ?? null,
+    realUserStatus: 'unsupported',
+    state: response.authorization?.state ?? null,
+  };
+}
+
+let loading: Promise<AppleIDAuth> | null = null;
+
+/** Apple's script, loaded once. */
+function appleIDAuth(scriptURL: string): Promise<AppleIDAuth> {
+  const existing = (globalThis as { AppleID?: { auth: AppleIDAuth } }).AppleID?.auth;
+  if (existing) return Promise.resolve(existing);
+  return (loading ??= new Promise<AppleIDAuth>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = scriptURL;
+    script.async = true;
+    script.onload = () => {
+      const auth = (globalThis as { AppleID?: { auth: AppleIDAuth } }).AppleID?.auth;
+      if (auth) resolve(auth);
+      else reject(new Error('appleSignIn: the script loaded without AppleID.auth'));
+    };
+    script.onerror = () => {
+      loading = null;
+      reject(new Error('network: could not load Sign in with Apple'));
+    };
+    document.head.append(script);
+  }));
+}
+
+/** Whether Apple's script reported the viewer closing the popup or declining. */
+function isCancellation(error: unknown): boolean {
+  const code = (error as { error?: string } | null)?.error;
+  return code === 'popup_closed_by_user' || code === 'user_cancelled_authorize' || code === 'popup_blocked_by_browser';
+}
+
+export function browserAppleSignIn(): AppleSignInHost {
+  return {
+    async signIn(options) {
+      const config = configuration;
+      if (!config) throw new Error('unsupported: Sign in with Apple is not configured here (configureSignInWithApple on a page)');
+      const auth = await appleIDAuth(config.scriptURL ?? SCRIPT_URL);
+      const scope = options.scopes.map((item) => (item === 'fullName' ? 'name' : 'email')).join(' ');
+      auth.init({
+        clientId: config.clientId,
+        scope,
+        redirectURI: config.redirectURI,
+        ...(options.state ? { state: options.state } : {}),
+        ...(options.nonce ? { nonce: options.nonce } : {}),
+        usePopup: true,
+      });
+      let response: AppleSignInResponse;
+      try {
+        response = await auth.signIn();
+      } catch (error) {
+        if (isCancellation(error)) throw new Error('cancelled: the viewer closed Sign in with Apple');
+        throw new Error(`appleSignIn: ${(error as { error?: string } | null)?.error ?? String(error)}`);
+      }
+      return credentialOf(response);
+    },
+    async credentialState(): Promise<AppleCredentialState> {
+      return 'unknown';
+    },
+  };
+}

package/src/files.ts

@@ -21,7 +21,11 @@ export interface FileAttributes {
   size: number;
   /** When it was last written, in milliseconds since the epoch, where the host knows. */
   modified: number | null;
+  /** When it was made, in milliseconds since the epoch, where the host knows. */
+  created: number | null;
   directory: boolean;
+  /** The MIME type its extension names (`text/plain`); empty for a directory or an unknown extension. */
+  type: string;
 }
 
 /** The app's standard directories, as `file:` URLs. */
@@ -58,8 +62,19 @@ export interface FilesHost {
   move(from: string, to: string): Promise<void>;
   /** Copies a file or directory to a URL nothing is at, in a directory that exists. */
   copy(from: string, to: string): Promise<void>;
-  /** A URL the page can load the file at: an object URL of its bytes on a page, the URL itself natively. */
+  /** A URL the page can load the file at: an object URL of its bytes on a page, the URL itself natively (downloaded from iCloud Drive first). */
   loadURL(url: string): Promise<string>;
+  /**
+   * The app's iCloud Drive `Documents`, where the app has the entitlement and
+   * the viewer iCloud Drive (natively); null elsewhere, and on a page.
+   */
+  iCloud?(): Promise<string | null>;
+  /**
+   * Calls `listener` with the URLs that changed: what this page wrote (so
+   * two readers of a file agree), and natively what another device wrote to
+   * iCloud Drive. Returns a function that stops listening.
+   */
+  watch?(listener: (urls: string[]) => void): () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -121,10 +136,11 @@ function parentOf(path: string): string {
 // Rows: a home's files by path, in IndexedDB or memory
 // ---------------------------------------------------------------------------
 
-/** A file's bytes, or null for a directory, and when it was written. */
+/** A file's bytes, or null for a directory, and when it was written and made. */
 export interface FileRow {
   data: Uint8Array | null;
   modified: number | null;
+  created: number | null;
 }
 
 /** The rows of one home, by path relative to it (`Documents/notes.txt`). */
@@ -141,7 +157,7 @@ export function memoryRows(): FileRows {
   const rows = new Map<string, FileRow>();
   return {
     get: async (path) => rows.get(path),
-    put: async (path, row) => void rows.set(path, { data: row.data === null ? null : row.data.slice(), modified: row.modified }),
+    put: async (path, row) => void rows.set(path, { data: row.data === null ? null : row.data.slice(), modified: row.modified, created: row.created }),
     remove: async (paths) => paths.forEach((path) => rows.delete(path)),
     keys: async () => [...rows.keys()],
   };
@@ -156,12 +172,17 @@ export function indexedDBRows(app: string, factory: IDBFactory = indexedDB): Fil
     async get(path) {
       const row = (await request((await store('readonly')).get(path))) as EntryRow | undefined;
       if (!row) return undefined;
-      return { data: row.directory ? null : new Uint8Array(row.data ?? new Uint8Array()), modified: typeof row.modified === 'number' ? row.modified : null };
+      return {
+        data: row.directory ? null : new Uint8Array(row.data ?? new Uint8Array()),
+        modified: typeof row.modified === 'number' ? row.modified : null,
+        created: typeof row.created === 'number' ? row.created : null,
+      };
     },
     async put(path, row) {
       const entries = await store('readwrite');
       const stored: EntryRow = row.data === null ? { path, directory: true } : { path, data: row.data.slice() };
       if (row.modified !== null) stored.modified = row.modified;
+      if (row.created !== null) stored.created = row.created;
       entries.put(stored);
       await done(entries.transaction);
     },
@@ -232,6 +253,8 @@ export class BrowserFiles implements FilesHost {
   private readonly now: () => number;
   /** Object URLs handed out, by mount URL and path, revoked when the file changes. */
   private readonly loaded = new Map<string, string>();
+  /** Who hears about changes (`watch`). */
+  private readonly watchers = new Set<(urls: string[]) => void>();
 
   /** Whether the home's rows are the database named by `app` (not rows an option gave). */
   private readonly defaultRows: boolean;
@@ -271,6 +294,21 @@ export class BrowserFiles implements FilesHost {
     { url: TMP_URL, prefix: TMP.split('/').filter(Boolean), rows: () => this.temporaryRows, standard: [] },
   ];
 
+  /** No iCloud Drive on a page. */
+  async iCloud(): Promise<string | null> {
+    return null;
+  }
+
+  watch(listener: (urls: string[]) => void): () => void {
+    this.watchers.add(listener);
+    return () => void this.watchers.delete(listener);
+  }
+
+  /** Tells the watchers, after the change landed. */
+  private changed(...urls: string[]): void {
+    for (const listener of [...this.watchers]) listener(urls);
+  }
+
   /** The mount a URL falls in and its path there, or a failure for a URL outside the app's files. */
   private locate(url: string): { mount: Mount; path: string } {
     const segments = fileSegments(url);
@@ -295,7 +333,7 @@ export class BrowserFiles implements FilesHost {
   private async rowAt(mount: Mount, path: string): Promise<FileRow | undefined> {
     const row = await mount.rows().get(path);
     if (row) return row;
-    return (await this.impliedDirectory(mount, path)) ? { data: null, modified: null } : undefined;
+    return (await this.impliedDirectory(mount, path)) ? { data: null, modified: null, created: null } : undefined;
   }
 
   private async requireDirectory(mount: Mount, path: string, url: string): Promise<void> {
@@ -326,8 +364,10 @@ export class BrowserFiles implements FilesHost {
     await this.requireDirectory(mount, parentOf(path), url);
     const existing = await this.rowAt(mount, path);
     if (existing && existing.data === null) throw new FilesFailure('isDirectory', `${url} is a directory`);
-    await mount.rows().put(path, { data, modified: this.now() });
+    const now = this.now();
+    await mount.rows().put(path, { data, modified: now, created: existing?.created ?? now });
     this.forget(mount, path);
+    this.changed(url);
   }
 
   async remove(url: string): Promise<void> {
@@ -339,6 +379,7 @@ export class BrowserFiles implements FilesHost {
     const below = (await mount.rows().keys()).filter((key) => key === path || key.startsWith(prefix));
     await mount.rows().remove(below);
     for (const key of below) this.forget(mount, key);
+    this.changed(url);
   }
 
   async createDirectory(url: string): Promise<void> {
@@ -348,8 +389,9 @@ export class BrowserFiles implements FilesHost {
       const at = parts.slice(0, depth).join('/');
       const row = await mount.rows().get(at);
       if (row?.data) throw new FilesFailure('exists', `${fileURL(mount.url, at)} is a file`);
-      if (!row && !mount.standard.includes(at)) await mount.rows().put(at, { data: null, modified: this.now() });
+      if (!row && !mount.standard.includes(at)) await mount.rows().put(at, { data: null, modified: this.now(), created: this.now() });
     }
+    this.changed(url);
   }
 
   async list(url: string): Promise<string[]> {
@@ -370,7 +412,8 @@ export class BrowserFiles implements FilesHost {
     const { mount, path } = this.locate(url);
     const row = await this.rowAt(mount, path);
     if (!row) return null;
-    return { size: row.data?.byteLength ?? 0, modified: row.modified, directory: row.data === null };
+    const directory = row.data === null;
+    return { size: row.data?.byteLength ?? 0, modified: row.modified, created: row.created, directory, type: directory ? '' : mediaType(path) };
   }
 
   /** Every row at or below `path`, by path. */
@@ -399,12 +442,13 @@ export class BrowserFiles implements FilesHost {
     const now = this.now();
     for (const [path, row] of rows) {
       const moved = target.path + path.slice(source.path.length);
-      await target.mount.rows().put(moved, { data: row.data, modified: removeSource ? row.modified : now });
+      await target.mount.rows().put(moved, { data: row.data, modified: removeSource ? row.modified : now, created: removeSource ? row.created : now });
     }
     if (removeSource) {
       await source.mount.rows().remove([...rows.keys()].filter((key) => key !== source.path || !source.mount.standard.includes(key)));
       for (const key of rows.keys()) this.forget(source.mount, key);
     }
+    this.changed(from, to);
   }
 
   move(from: string, to: string): Promise<void> {

package/src/hostRequests.ts

@@ -2,7 +2,8 @@
  * Phase 13: what the Wasm app asks the page to do on its behalf. The app has
  * no network of its own; `URLSession` sends a `request` op of kind `fetch`
  * and `AsyncImage` one of kind `image` (see docs/ops-protocol.md, "Phase
- * 13"); `ShareLink` sends `share` and `PhotosPicker` `pickFiles`. The
+ * 13"); `ShareLink` sends `share`, `PhotosPicker` `pickFiles` and `fileExporter`
+ * `exportFiles`. The
  * loader (wasm.ts) hands each op to `performHostRequest` and delivers the
  * result as a `response` event with the same id.
  *
@@ -17,6 +18,7 @@
  * `UIPasteboard` `clipboard` (clipboard.ts).
  */
 
+import { browserAppleSignIn } from './appleSignIn';
 import { base64Decode, base64Encode } from './base64';
 import { browserNotificationHost, browserPushHost, performNotification, type NotificationHost, type NotificationResult } from './notifications';
 import type {
@@ -25,6 +27,8 @@ import type {
   ImageRequestParams,
   NotificationRequestParams,
   PickFilesRequestParams,
+  ExportFilesRequestParams,
+  AppleSignInRequestParams,
   RequestOp,
   ScannerRequestParams,
   ShareRequestParams,
@@ -76,6 +80,45 @@ export interface ShareResult {
   outcome: 'shared' | 'downloaded' | 'cancelled';
 }
 
+/** What Sign in with Apple answered (`ASAuthorizationAppleIDCredential`): the stable `user` identifier and, the first time, the name and email the viewer shared. */
+export interface AppleIDCredential {
+  user: string;
+  email: string | null;
+  fullName: AppleIDName | null;
+  /** The identity token, a JWT (`sub` is `user`), for the app's server. */
+  identityToken: string | null;
+  /** The authorization code, short-lived, for the app's server. */
+  authorizationCode: string | null;
+  realUserStatus: 'likelyReal' | 'unknown' | 'unsupported';
+  state: string | null;
+}
+
+export interface AppleIDName {
+  givenName: string | null;
+  familyName: string | null;
+  middleName: string | null;
+  namePrefix: string | null;
+  nameSuffix: string | null;
+  nickname: string | null;
+}
+
+export type AppleCredentialState = 'authorized' | 'revoked' | 'notFound' | 'transferred' | 'unknown';
+
+/** Sign in with Apple, as the host has it: Apple's JS on a page the app configured, `ASAuthorizationController` natively. */
+export interface AppleSignInHost {
+  /** Asks the viewer; rejects `cancelled: …` when they dismiss it. It must open before it returns, as a chooser. */
+  signIn(options: { scopes: ('fullName' | 'email')[]; nonce?: string; state?: string }): Promise<AppleIDCredential>;
+  /** What the credential for `user` is now; `unknown` where the host cannot ask (a page). */
+  credentialState(user: string): Promise<AppleCredentialState>;
+}
+
+/** How an `exportFiles` request ended: saved where the viewer chose, saved as downloads, or dismissed by the viewer. */
+export interface ExportFilesResult {
+  outcome: 'saved' | 'downloaded' | 'cancelled';
+  /** Where the files went, where the host knows (the document picker's `file:` URLs natively). */
+  urls?: string[];
+}
+
 /** One file the viewer picked (`pickFiles`), with its bytes. */
 export interface PickedFile {
   name: string;
@@ -121,6 +164,12 @@ export interface HostRequestEnvironment {
    * only show one during the tap that asked (user activation).
    */
   pickFiles?: (options: { accept: string; multiple: boolean }) => Promise<File[]>;
+  /**
+   * Lets the viewer choose where files go (a save dialog, the Files app) and
+   * resolves with where they went, or `cancelled`. Absent, `exportFiles`
+   * downloads them instead. It must open before it returns, as `pickFiles`.
+   */
+  exportFiles?: (files: File[]) => Promise<ExportFilesResult>;
   /** A URL the page can show a picked file at (`URL.createObjectURL`). */
   objectURL?: (file: File) => string;
   /** A `UIImage` bitmap drawn into a PNG file (src/bitmapStore.ts), to share it as a file. */
@@ -135,6 +184,8 @@ export interface HostRequestEnvironment {
   openURL?: (url: string) => void;
   /** Sign-in windows (`webAuth`, webAuth.ts). */
   webAuth?: WebAuthSessions;
+  /** Sign in with Apple (`appleSignIn`, appleSignIn.ts on a page once configured; `ASAuthorizationController` natively). */
+  appleSignIn?: AppleSignInHost;
   /** AVFoundation's media files and probes, QuickLook's previews (`media`, media.ts). */
   media?: MediaHost;
   /** MediaPlayer's now-playing info and remote commands (src/mediaSession.ts); absent without the Media Session API. */
@@ -195,6 +246,38 @@ function downloadBlob(blob: Blob, filename: string): void {
   setTimeout(() => URL.revokeObjectURL(url), 60_000);
 }
 
+/** The File System Access API's save dialog, where the browser has it (Chromium). */
+interface SaveFilePickerWindow {
+  showSaveFilePicker(options: { suggestedName?: string; types?: { description?: string; accept: Record<string, string[]> }[] }): Promise<{
+    createWritable(): Promise<{ write(data: Blob): Promise<void>; close(): Promise<void> }>;
+  }>;
+}
+
+/** Saves each file where the viewer chooses; a dismissed dialog ends the export as `cancelled`. */
+async function saveFiles(files: File[]): Promise<ExportFilesResult> {
+  const picker = window as unknown as SaveFilePickerWindow;
+  const urls: string[] = [];
+  for (const file of files) {
+    const dot = file.name.lastIndexOf('.');
+    const extension = dot > 0 ? file.name.slice(dot) : '';
+    let handle: Awaited<ReturnType<SaveFilePickerWindow['showSaveFilePicker']>>;
+    try {
+      handle = await picker.showSaveFilePicker({
+        suggestedName: file.name,
+        ...(extension && file.type && !file.type.includes(';') ? { types: [{ accept: { [file.type]: [extension] } }] } : {}),
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') return { outcome: 'cancelled' };
+      throw error;
+    }
+    const writable = await handle.createWritable();
+    await writable.write(file);
+    await writable.close();
+    urls.push(`file:///${encodeURIComponent(file.name)}`);
+  }
+  return { outcome: 'saved', urls };
+}
+
 const notificationHost = browserNotificationHost();
 
 /**
@@ -235,6 +318,8 @@ export const browserEnvironment: HostRequestEnvironment = {
     ? { canShare: (data: ShareData) => navigator.canShare(data) }
     : {}),
   ...(typeof document !== 'undefined' ? { download: downloadBlob, pickFiles: chooseFiles } : {}),
+  ...(typeof window !== 'undefined' && 'showSaveFilePicker' in window ? { exportFiles: saveFiles } : {}),
+  ...(typeof document !== 'undefined' ? { appleSignIn: browserAppleSignIn() } : {}),
   ...(typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function'
     ? { objectURL: (file: File) => URL.createObjectURL(file) }
     : {}),
@@ -278,7 +363,7 @@ export function loadableURL(url: string): string | Promise<string> {
 export async function performHostRequest(
   op: RequestOp,
   env: HostRequestEnvironment = browserEnvironment,
-): Promise<FetchResult | ImageResult | ShareResult | PickFilesResult | NotificationResult | ScannerResult | WebAuthResult | Record<string, unknown>> {
+): Promise<FetchResult | ImageResult | ShareResult | PickFilesResult | ExportFilesResult | NotificationResult | ScannerResult | WebAuthResult | AppleIDCredential | Record<string, unknown>> {
   switch (op.kind) {
     case 'fetch':
       return performFetch(op.params as FetchRequestParams, env);
@@ -290,6 +375,8 @@ export async function performHostRequest(
       // Not awaited before the chooser opens: `performPickFiles` calls
       // `env.pickFiles` synchronously, inside the tap that sent the request.
       return performPickFiles(op.params as PickFilesRequestParams, env);
+    case 'exportFiles':
+      return performExportFiles(op.params as ExportFilesRequestParams, env);
     case 'notification':
       return performNotification(op.params as NotificationRequestParams, env.notifications);
     case 'scanner':
@@ -309,6 +396,9 @@ export async function performHostRequest(
       // synchronously, while the tap's activation may still count.
       if (!env.webAuth) throw new Error('unsupported: this page cannot open a sign-in window');
       return env.webAuth.perform(op.params as WebAuthRequestParams);
+    case 'appleSignIn':
+      // Not awaited before the sheet opens: Apple's JS opens its popup within the tap.
+      return performAppleSignIn(op.params as AppleSignInRequestParams, env.appleSignIn);
     case 'media':
       // `open` is called before any await, while the tap's activation may still count.
       return performMedia(op.params as MediaRequestParams, env.media);
@@ -434,6 +524,40 @@ async function collectFiles(
   return files;
 }
 
+/**
+ * Sign in with Apple: `signIn` answers the credential, `credentialState`
+ * `{ state }`. Without a host (a page the app did not configure) the request
+ * fails `unsupported: …`, which the app shows as the button doing nothing it
+ * can do here.
+ */
+function performAppleSignIn(params: AppleSignInRequestParams, host: AppleSignInHost | undefined): Promise<AppleIDCredential | { state: AppleCredentialState }> {
+  if (!host) return Promise.reject(new Error('unsupported: Sign in with Apple is not configured here (configureSignInWithApple on a page)'));
+  if (params.action === 'credentialState') {
+    if (typeof params.user !== 'string') return Promise.reject(new Error('appleSignIn: credentialState needs a user'));
+    return host.credentialState(params.user).then((state) => ({ state }));
+  }
+  const scopes = (params.scopes ?? []).filter((scope): scope is 'fullName' | 'email' => scope === 'fullName' || scope === 'email');
+  return host.signIn({ scopes, ...(params.nonce ? { nonce: params.nonce } : {}), ...(params.state ? { state: params.state } : {}) });
+}
+
+/**
+ * `exportFiles`: the files go where the viewer chooses (`env.exportFiles`:
+ * a save dialog, the Files app) or, where the page has no dialog, to the
+ * downloads, as a download link saves them. `fileExporter` in
+ * @swiftbrowser/react calls it with the document's file.
+ */
+export async function exportFiles(files: File[], env: HostRequestEnvironment = browserEnvironment): Promise<ExportFilesResult> {
+  if (!files.length) throw new Error('unsupported: nothing to export');
+  if (env.exportFiles) return env.exportFiles(files);
+  if (!env.download) throw new Error('unsupported: this page can neither save nor download files');
+  for (const file of files) env.download(file, file.name);
+  return { outcome: 'downloaded' };
+}
+
+async function performExportFiles(params: ExportFilesRequestParams, env: HostRequestEnvironment): Promise<ExportFilesResult> {
+  return exportFiles(await collectFiles(params, env, 'Document'), env);
+}
+
 /**
  * Saving to the photo library (Photos, UIKit): every file the request
  * carries is downloaded, as the browser saves any download.

package/src/main.ts

@@ -20,6 +20,7 @@ import { withBlockedHosts } from './blockedHosts';
 import { withCORSProxy } from './corsProxy';
 import { browserEnvironment, installPushService } from './hostRequests';
 import { locateBundleFiles } from './media';
+import { currentScenePhase } from './scenePhase';
 import { relayUndo } from './undo';
 import { callbackPageURL } from './webAuth';
 import { bitmapStore } from './bitmaps';
@@ -265,14 +266,6 @@ if (deviceMode) {
 // Phase 8: scene phase
 // ---------------------------------------------------------------------------
 
-/**
- * `ScenePhase` from the document: `background` while hidden, else `active`
- * when the window has focus and `inactive` when it does not.
- */
-function currentScenePhase(): ScenePhase {
-  if (document.visibilityState === 'hidden') return 'background';
-  return document.hasFocus() ? 'active' : 'inactive';
-}
 /** The scene phase last sent in an `environment` event (null before the first). */
 let sentScenePhase: ScenePhase | null = null;
 

package/src/protocol.ts

@@ -1107,17 +1107,19 @@ export interface DefaultsOp {
 export interface RequestOp {
   op: 'request';
   id: number;
-  kind: 'fetch' | 'image' | 'share' | 'pickFiles' | 'notification' | 'scanner' | 'websocket' | 'openURL' | 'webAuth' | 'media' | 'download' | 'clipboard' | 'translate' | 'pickColor' | 'mediaSession' | 'undo';
+  kind: 'fetch' | 'image' | 'share' | 'pickFiles' | 'exportFiles' | 'notification' | 'scanner' | 'websocket' | 'openURL' | 'webAuth' | 'appleSignIn' | 'media' | 'download' | 'clipboard' | 'translate' | 'pickColor' | 'mediaSession' | 'undo';
   params:
     | FetchRequestParams
     | ImageRequestParams
     | ShareRequestParams
     | PickFilesRequestParams
+    | ExportFilesRequestParams
     | NotificationRequestParams
     | ScannerRequestParams
     | WebSocketRequestParams
     | OpenURLRequestParams
     | WebAuthRequestParams
+    | AppleSignInRequestParams
     | MediaRequestParams
     | DownloadRequestParams
     | ClipboardRequestParams
@@ -1178,6 +1180,23 @@ export interface WebAuthRequestParams {
   callbackPage?: string;
   ephemeral?: boolean;
 }
+/**
+ * Sign in with Apple (docs/ops-protocol.md, "Sign in with Apple"): `signIn`
+ * asks for the viewer's Apple ID with `scopes` (`fullName`, `email`), a
+ * `nonce` for the identity token and a `state` echoed back; the response
+ * value is an `AppleIDCredential`, or the request fails `cancelled: …`.
+ * `credentialState` asks what a `user` identifier's credential is now; the
+ * response value is `{ state }` (`authorized`, `revoked`, `notFound`,
+ * `transferred`, or `unknown` where the host cannot tell).
+ */
+export interface AppleSignInRequestParams {
+  action: 'signIn' | 'credentialState';
+  scopes?: ('fullName' | 'email')[];
+  nonce?: string;
+  state?: string;
+  user?: string;
+}
+
 export interface OpenURLRequestParams {
   url: string;
 }
@@ -1266,6 +1285,16 @@ export interface PickFilesRequestParams {
   multiple: boolean;
 }
 
+/**
+ * `fileExporter`, saving to Files: let the viewer choose where the app's
+ * files go. The page shows a save dialog where the browser has one (the
+ * File System Access API) and downloads the files elsewhere; the native app
+ * shows the document picker. The response value is an `ExportFilesResult`.
+ */
+export interface ExportFilesRequestParams {
+  files: SharedFile[];
+}
+
 /**
  * UserNotifications (docs/ops-protocol.md, "Notifications"): `status` reads
  * `Notification.permission`, `request` asks for it, `show` presents a
@@ -1940,8 +1969,18 @@ export interface DropDestinationProps {
   accepts?: string[];
 }
 
+/**
+ * `.onTouches` (a SwiftBrowser addition: SwiftUI has no multi-touch gesture):
+ * exactly one child, the child's size. The element owns every pointer that
+ * goes down on it and receives `touches` events with all of them, so an app
+ * can hear chords and glissandi (a piano, a drum pad, a multi-finger
+ * drawing). No props.
+ */
+export type TouchesProps = Record<string, never>;
+
 export interface ElementPropsByKind {
   gesture: GestureProps;
+  touches: TouchesProps;
   swipeactions: SwipeActionsProps;
   contextmenu: ContextMenuProps;
   listrow: ListRowProps;
@@ -1949,7 +1988,7 @@ export interface ElementPropsByKind {
   dropdestination: DropDestinationProps;
 }
 
-export const INTERACTION_KINDS: readonly ElementKind[] = ['gesture', 'swipeactions', 'contextmenu', 'listrow', 'draggable', 'dropdestination'];
+export const INTERACTION_KINDS: readonly ElementKind[] = ['gesture', 'touches', 'swipeactions', 'contextmenu', 'listrow', 'draggable', 'dropdestination'];
 
 export interface ListProps {
   /** `EditButton` / `editMode`: a selectable or deletable `listrow` gains a 44 pt leading control and its content shifts right 40; a movable one a trailing grip. */
@@ -2117,6 +2156,25 @@ export interface LongPressEvent {
   type: 'longpress';
   id: ElementId;
 }
+/** One pointer on a `touches` element: a stable `id` while it is down, and its point in the element's coordinates. */
+export interface TouchPoint {
+  id: number;
+  x: number;
+  y: number;
+}
+/**
+ * A `touches` element's pointers changed: `began` when one came down,
+ * `changed` when they moved (coalesced to one per animation frame), `ended`
+ * when one lifted, `cancelled` when the renderer lost them all. `touches` is
+ * every pointer still down after the change, so an app reads the state from
+ * each event (the keys under the touches) instead of tracking ups and downs.
+ */
+export interface TouchesEvent {
+  type: 'touches';
+  id: ElementId;
+  phase: DragPhase;
+  touches: TouchPoint[];
+}
 /** A `listrow` was swiped to delete or its edit-mode Delete button tapped. */
 export interface DeleteEvent {
   type: 'delete';
@@ -2191,7 +2249,7 @@ export interface DropEvent {
 }
 
 /** The Phase 8 events (merged into `RendererEvent` above). */
-export type InteractionEvent = DragEvent | PinchEvent | LongPressEvent | DeleteEvent | RefreshEvent | ScrollPositionEvent | ScrollVisibilityEvent | MoveEvent | DragStartEvent | DragEndEvent | DropEvent;
+export type InteractionEvent = DragEvent | PinchEvent | LongPressEvent | TouchesEvent | DeleteEvent | RefreshEvent | ScrollPositionEvent | ScrollVisibilityEvent | MoveEvent | DragStartEvent | DragEndEvent | DropEvent;
 // Phase 8: alerts, controls, effects
 // (docs/ops-protocol.md, "Phase 8: interaction"; gestures, swipe actions,
 // context menus, list rows and refresh live in their own block)

package/src/renderer.ts

@@ -162,6 +162,7 @@ import { applyPathShape, hasPathFrames, playPathFrames } from './pathShape';
 import { VideoEvents, applyVideo, stopVideos } from './video';
 import { loadableURL } from './hostRequests';
 import { PinchController } from './pinch';
+import { TouchesController } from './touches';
 import { applyCanvas, createCanvasElement } from './canvasDrawing';
 import { scrollToTarget } from './scrollTo';
 import { POSITION_SETTLE_MS, POSITION_SNAP_WAITS, anchorPoint, positionTarget, restsOnSnapPoint, type PositionCandidate } from './scrollPosition';
@@ -433,6 +434,7 @@ export class Renderer {
   /** Text, links and files dragged in from outside the page (src/dragDrop.ts). */
   private readonly externalDrops: ExternalDrops;
   private readonly pinches: PinchController;
+  private readonly touches: TouchesController;
   private readonly touchPaging: TouchPaging;
   /** `video` elements' media events, as `video` events (src/video.ts). */
   private readonly videoEvents: VideoEvents;
@@ -1012,6 +1014,8 @@ export class Renderer {
     this.externalDrops = new ExternalDrops(host);
     // Two-finger gestures: MagnifyGesture and RotateGesture (src/pinch.ts).
     this.pinches = new PinchController(host);
+    // Multi-touch: every pointer on a `touches` element (src/touches.ts).
+    this.touches = new TouchesController(host);
     // A finger on a paging scroll view pages it as iOS does (src/touchPaging.ts);
     // the view it drives reports its position once the drive rests it on a page.
     this.touchPaging = new TouchPaging(root, (el) => {
@@ -1956,6 +1960,7 @@ export class Renderer {
     this.pressEffects.dispose();
     this.externalDrops.dispose();
     this.pinches.dispose();
+    this.touches.dispose();
     this.touchPaging.dispose();
     this.videoEvents.dispose();
     this.resizeObserver?.disconnect();
@@ -3131,6 +3136,7 @@ function createShell(kind: ElementKind): HTMLElement {
       return document.createElement('div');
     // Phase 8: gestures, rows, navigation; drag and drop
     case 'gesture':
+    case 'touches':
     case 'contextmenu':
     case 'draggable':
     case 'dropdestination':
@@ -3960,6 +3966,7 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
       el.dataset['sbLeading'] = String(Math.max(0, Math.floor(Number(swipe.leading) || 0)));
       break;
     }
+    case 'touches':
     case 'contextmenu':
       break;
     case 'draggable':

package/src/scenePhase.ts

@@ -0,0 +1,53 @@
+/**
+ * `ScenePhase` from the document, as a page reads it for the Swift
+ * environment (main.ts) and `mount` reads it for a React root's
+ * `useScenePhase`: `background` while the document is hidden, else `active`
+ * when the window has focus and `inactive` when it does not. The browser
+ * signals every change through `visibilitychange`, `focus` and `blur`.
+ */
+
+import type { ScenePhase } from './protocol';
+
+/** What `currentScenePhase` reads: a `Document`, or a stand-in in tests. */
+export interface ScenePhaseDocument {
+  visibilityState: string;
+  hasFocus(): boolean;
+  addEventListener(type: 'visibilitychange', listener: () => void): void;
+  removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+
+/** Where the focus events arrive: a `Window`, or a stand-in in tests. */
+export interface ScenePhaseWindow {
+  addEventListener(type: 'focus' | 'blur', listener: () => void): void;
+  removeEventListener(type: 'focus' | 'blur', listener: () => void): void;
+}
+
+export function currentScenePhase(doc: ScenePhaseDocument = document): ScenePhase {
+  if (doc.visibilityState === 'hidden') return 'background';
+  return doc.hasFocus() ? 'active' : 'inactive';
+}
+
+/**
+ * Calls `onChange` with the new phase each time it changes (not with the
+ * current one). Returns a function that stops watching.
+ */
+export function watchScenePhase(
+  onChange: (phase: ScenePhase) => void,
+  { doc = document, win = window }: { doc?: ScenePhaseDocument; win?: ScenePhaseWindow } = {},
+): () => void {
+  let last = currentScenePhase(doc);
+  const check = (): void => {
+    const next = currentScenePhase(doc);
+    if (next === last) return;
+    last = next;
+    onChange(next);
+  };
+  doc.addEventListener('visibilitychange', check);
+  win.addEventListener('focus', check);
+  win.addEventListener('blur', check);
+  return () => {
+    doc.removeEventListener('visibilitychange', check);
+    win.removeEventListener('focus', check);
+    win.removeEventListener('blur', check);
+  };
+}

package/src/styles.css

@@ -152,7 +152,8 @@
   --sb-alert-scrim: rgba(0, 0, 0, 0.46);
   --sb-alert-card: rgba(22, 22, 23, 0.9);
   --sb-color-field-border: #3a3a3c;
-  --sb-color-field-background: #1c1c1e;
+  /* A rounded-border field is black in the dark, in a sheet too (UIKit's rounded-rect text field is not elevated). */
+  --sb-color-field-background: #000000;
   --sb-color-placeholder: rgba(235, 235, 245, 0.3);
   --sb-glass-background: rgba(30, 30, 30, 0.84);
   --sb-glass-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
@@ -1665,14 +1666,16 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
   box-shadow: 0 10px 50px rgba(0, 0, 0, 0.25);
 }
 
-/* In dark mode what a form sheet holds takes iOS's elevated colors, as the
-   card does: the base ones are black and would paint it black. */
-.device[data-theme="dark"] .sb-sheet[data-sb-form] > .sb-sheet-card {
+/* In dark mode what a sheet holds takes iOS's elevated colors, as the card
+   does (UIKit raises the interface level of anything presented as a sheet,
+   on a phone as on an iPad's form sheet): the base ones are black and would
+   paint it black. A full-screen cover is not a sheet to UIKit and keeps the
+   base colors. */
+.device[data-theme="dark"] .sb-sheet:not([data-sb-detent="full"]) > .sb-sheet-card {
   --sb-color-system-background: #1c1c1e;
   --sb-color-secondary-system-background: #2c2c2e;
   --sb-color-grouped-background: #1c1c1e;
   --sb-color-grouped-cell: #2c2c2e;
-  --sb-color-field-background: #2c2c2e;
 }
 
 .sb-sheet-grabber {
@@ -3091,10 +3094,18 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
 }
 
 .sb-gesture[data-sb-drag],
-.sb-gesture[data-sb-pinch] {
+.sb-gesture[data-sb-pinch],
+.sb-touches {
   touch-action: none;
 }
 
+/* `touches`: the element owns its pointers (src/touches.ts), so no selection, callout or scroll from them. */
+.sb-touches {
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-touch-callout: none;
+}
+
 /* `contextmenu` / `swipeactions`: only the content (the first child) shows
    inline; the items are listed in the popover / drawn as action buttons
    (they are in `hidden` without frames). */

package/src/symbols.ts

@@ -505,6 +505,17 @@ const BOOKS_VERTICAL_FILL: IconNode = [
   ['rect', { x: '17.8', y: '4.5', width: '4', height: '16', rx: '1.2', stroke: 'none', transform: 'rotate(-14 19.8 12.5)' }],
 ];
 
+/** `apple.logo`: the Apple logo (the simple-icons path, CC0), as one solid shape, for a Sign in with Apple button. */
+const APPLE_LOGO: IconNode = [
+  [
+    'path',
+    {
+      d: 'M12.152 6.896c-.948 0-2.415-1.078-3.96-1.04-2.04.027-3.91 1.183-4.961 3.014-2.117 3.675-.546 9.103 1.519 12.09 1.013 1.454 2.208 3.09 3.792 3.039 1.52-.065 2.09-.987 3.935-.987 1.831 0 2.35.987 3.96.948 1.637-.026 2.676-1.48 3.676-2.948 1.156-1.688 1.636-3.325 1.662-3.415-.039-.013-3.182-1.221-3.22-4.857-.026-3.04 2.48-4.494 2.597-4.559-1.429-2.09-3.623-2.324-4.39-2.376-2-.156-3.675 1.09-4.61 1.09zM15.53 3.83c.843-1.012 1.4-2.427 1.245-3.83-1.207.052-2.662.805-3.532 1.818-.78.896-1.454 2.338-1.273 3.714 1.338.104 2.715-.688 3.559-1.701',
+      stroke: 'none',
+    },
+  ],
+];
+
 /** Marks a `knockout` glyph's inner shape that is filled, not only stroked (`enclosed`). */
 const SOLID_MARK = 'data-sb-knockout-solid';
 
@@ -1226,6 +1237,8 @@ export const SF_SYMBOLS: Readonly<Record<string, SymbolGlyph>> = {
   bird: outline(Bird),
   // The Swift logo: a bird in flight.
   swift: outline(Bird),
+  'apple.logo': solid(APPLE_LOGO),
+  applelogo: solid(APPLE_LOGO),
   cat: outline(Cat),
   dog: outline(Dog),
   carrot: outline(Carrot),

package/src/touches.ts

@@ -0,0 +1,199 @@
+/**
+ * Multi-touch: the `touches` element (`.onTouches` in the shim, `onTouches`
+ * in @swiftbrowser/react; docs/ops-protocol.md, "Multi-touch"). The
+ * single-pointer gestures of src/interaction.ts own one pointer at a time,
+ * which a piano or a drum pad cannot live with; this controller owns every
+ * pointer that goes down inside a `touches` element and sends the element
+ * `touches` events with all of them: `began` as one comes down, `changed` as
+ * they move (one event per animation frame), `ended` as one lifts and
+ * `cancelled` when the browser takes them away. Each event carries every
+ * pointer still down, in the element's coordinates, so the app reads the
+ * state from the event (the keys under the fingers) rather than pairing ups
+ * with downs.
+ *
+ * A pointer down inside a `touches` element stops there: the interaction
+ * controller never sees it, so no scroll view, swipe row or `gesture` above
+ * the element competes for the finger, and the stylesheet's `touch-action:
+ * none` keeps the browser from scrolling or zooming with it. Clicks still
+ * reach the controls inside (a click is not a pointer event).
+ *
+ * `TouchSet` is the pure part: which pointers are down and what each change
+ * reports, testable without a DOM.
+ */
+
+import type { DragPhase, ElementId, TouchPoint, TouchesEvent } from './protocol';
+
+export interface TouchesHost {
+  readonly root: HTMLElement;
+  send(event: TouchesEvent): void;
+}
+
+const round = (n: number): number => Math.round(n * 100) / 100;
+
+/** The pointers down on one `touches` element, by pointer id, in order of arrival. */
+export class TouchSet {
+  private readonly points = new Map<number, { x: number; y: number }>();
+
+  get size(): number {
+    return this.points.size;
+  }
+
+  has(id: number): boolean {
+    return this.points.has(id);
+  }
+
+  /** A pointer came down: the set with it, as the event lists it. */
+  down(id: number, x: number, y: number): TouchPoint[] {
+    this.points.set(id, { x, y });
+    return this.list();
+  }
+
+  /** A pointer moved; false when it is not one of ours or did not move. */
+  move(id: number, x: number, y: number): boolean {
+    const point = this.points.get(id);
+    if (!point || (point.x === x && point.y === y)) return false;
+    point.x = x;
+    point.y = y;
+    return true;
+  }
+
+  /** A pointer lifted: the set without it, or null when it was not one of ours. */
+  up(id: number): TouchPoint[] | null {
+    if (!this.points.delete(id)) return null;
+    return this.list();
+  }
+
+  clear(): void {
+    this.points.clear();
+  }
+
+  /** Every pointer down, rounded to hundredths of a point. */
+  list(): TouchPoint[] {
+    return [...this.points.entries()].map(([id, point]) => ({ id, x: round(point.x), y: round(point.y) }));
+  }
+}
+
+/** One `touches` element with pointers down on it. */
+interface Session {
+  el: HTMLElement;
+  id: ElementId;
+  set: TouchSet;
+  /** The element's box in the viewport, measured as each pointer comes down. */
+  rect: DOMRect;
+  /** A `changed` waiting for the next frame. */
+  raf: number | null;
+}
+
+export class TouchesController {
+  /** The elements with pointers down, and which element each pointer is on. */
+  private readonly sessions = new Map<HTMLElement, Session>();
+  private readonly owners = new Map<number, Session>();
+  private listening = false;
+
+  constructor(private readonly host: TouchesHost) {
+    host.root.addEventListener('pointerdown', this.onPointerDown, true);
+  }
+
+  dispose(): void {
+    this.host.root.removeEventListener('pointerdown', this.onPointerDown, true);
+    this.detachWindow();
+    for (const session of this.sessions.values()) {
+      if (session.raf !== null) cancelAnimationFrame(session.raf);
+    }
+    this.sessions.clear();
+    this.owners.clear();
+  }
+
+  /** The innermost `touches` element at or above `target`, or null. */
+  private elementAt(target: EventTarget | null): { el: HTMLElement; id: ElementId } | null {
+    const start = target instanceof Element ? target : null;
+    const el = start?.closest<HTMLElement>('.sb-touches') ?? null;
+    if (!el || !this.host.root.contains(el)) return null;
+    // Pointer downs in a text field select text (as src/interaction.ts leaves them).
+    if (start?.closest('input, textarea, [contenteditable]')) return null;
+    const id = Number(el.dataset['sbId']);
+    return Number.isInteger(id) ? { el, id } : null;
+  }
+
+  private readonly onPointerDown = (event: PointerEvent): void => {
+    if (event.pointerType === 'mouse' && event.button !== 0) return;
+    const found = this.elementAt(event.target);
+    if (!found) return;
+    // Ours alone: no gesture, scroll or swipe above competes for the pointer.
+    event.stopPropagation();
+    let session = this.sessions.get(found.el);
+    if (!session) {
+      session = { el: found.el, id: found.id, set: new TouchSet(), rect: found.el.getBoundingClientRect(), raf: null };
+      this.sessions.set(found.el, session);
+    } else {
+      session.rect = found.el.getBoundingClientRect();
+    }
+    this.owners.set(event.pointerId, session);
+    try {
+      found.el.setPointerCapture(event.pointerId);
+    } catch {
+      // Not every environment allows capture; the window listeners still hear the pointer.
+    }
+    this.attachWindow();
+    const touches = session.set.down(event.pointerId, event.clientX - session.rect.left, event.clientY - session.rect.top);
+    this.flush(session);
+    this.host.send({ type: 'touches', id: session.id, phase: 'began', touches });
+  };
+
+  private readonly onPointerMove = (event: PointerEvent): void => {
+    const session = this.owners.get(event.pointerId);
+    if (!session) return;
+    if (!session.set.move(event.pointerId, event.clientX - session.rect.left, event.clientY - session.rect.top)) return;
+    if (session.raf !== null) return;
+    session.raf = requestAnimationFrame(() => {
+      session.raf = null;
+      if (!this.sessions.has(session.el)) return;
+      this.host.send({ type: 'touches', id: session.id, phase: 'changed', touches: session.set.list() });
+    });
+  };
+
+  private readonly onPointerUp = (event: PointerEvent): void => {
+    this.lift(event.pointerId, 'ended');
+  };
+
+  private readonly onPointerCancel = (event: PointerEvent): void => {
+    this.lift(event.pointerId, 'cancelled');
+  };
+
+  /** A pointer is gone: the element hears the set without it; the last one ends the session. */
+  private lift(pointerId: number, phase: DragPhase): void {
+    const session = this.owners.get(pointerId);
+    if (!session) return;
+    this.owners.delete(pointerId);
+    const touches = session.set.up(pointerId);
+    if (touches === null) return;
+    this.flush(session);
+    if (touches.length === 0) this.sessions.delete(session.el);
+    if (this.owners.size === 0) this.detachWindow();
+    this.host.send({ type: 'touches', id: session.id, phase, touches });
+  }
+
+  /** A `changed` waiting for the next frame goes out now, before a down or an up, so the order holds. */
+  private flush(session: Session): void {
+    if (session.raf === null) return;
+    cancelAnimationFrame(session.raf);
+    session.raf = null;
+    this.host.send({ type: 'touches', id: session.id, phase: 'changed', touches: session.set.list() });
+  }
+
+  private attachWindow(): void {
+    if (this.listening) return;
+    this.listening = true;
+    window.addEventListener('pointermove', this.onPointerMove);
+    window.addEventListener('pointerup', this.onPointerUp);
+    window.addEventListener('pointercancel', this.onPointerCancel);
+  }
+
+  private detachWindow(): void {
+    if (!this.listening) return;
+    this.listening = false;
+    window.removeEventListener('pointermove', this.onPointerMove);
+    window.removeEventListener('pointerup', this.onPointerUp);
+    window.removeEventListener('pointercancel', this.onPointerCancel);
+  }
+}