@swiftbrowser/web 0.1.0 → 0.2.0

package/src/wasm.ts

@@ -11,7 +11,11 @@
  */
 
 import { ConsoleStdout, Directory, type Fd, File, OpenFile, PreopenDirectory, WASI, WASIProcExit, type Inode } from '@bjorn3/browser_wasi_shim';
-import { isOp, type ElementId, type Op, type RendererEvent } from './protocol';
+import { HOME, HOME_ENVIRONMENT, TMP, homeDirectory } from './appFiles';
+import { zoneInfoEntries } from './zoneinfo';
+import { base64Encode } from './base64';
+import { performHostRequest, type HostRequestEnvironment } from './hostRequests';
+import { isOp, type ElementId, type Op, type RendererEvent, type RequestOp, type SwiftDataOp } from './protocol';
 
 export type OpsSink = (ops: Op[]) => void;
 
@@ -61,6 +65,24 @@ export interface LoadAppOptions {
   bundle?: ReadonlyMap<string, Uint8Array>;
   /** Phase 11: receives the app's `UserDefaults` whenever they change (a `defaults` op); the op never reaches `onOps`. */
   onDefaults?: (values: Record<string, unknown>) => void;
+  /**
+   * Phase 18: receives each saved batch of the app's SwiftData stores (a
+   * `swiftdata` op), in order; the op never reaches `onOps`.
+   */
+  onSwiftData?: (op: SwiftDataOp) => void;
+  /**
+   * Phase 19: the app's home, mounted writable at `/data` (`HOME`, with the
+   * XDG variables pointing at its `Library`); an empty one when not given. A
+   * fresh in-memory `/tmp` is mounted too.
+   */
+  home?: Directory;
+  /** Phase 19: called after an event or executor run in which the app wrote to its files. */
+  onFilesWritten?: () => void;
+  /**
+   * Phase 13: how `request` ops (`fetch`, `image`) are performed; the
+   * browser's `fetch` and `Image` by default. Tests substitute both.
+   */
+  requests?: HostRequestEnvironment;
 }
 
 /** An in-memory WASI directory tree from `path → bytes` (paths `/`-separated, no leading slash). */
@@ -101,6 +123,11 @@ interface SwiftBrowserExports {
   sb_state_len?: () => number;
   // Phase 4 (optional).
   sb_run_jobs?: (nowMs: number) => number;
+  // Bytes beside the JSON (optional; docs/ops-protocol.md, "Bytes").
+  sb_bytes?: (ptr: number, len: number) => number;
+  sb_bytes_count?: () => number;
+  sb_bytes_ptr?: (index: number) => number;
+  sb_bytes_len?: (index: number) => number;
 }
 
 const WASI_MODULE = 'wasi_snapshot_preview1';
@@ -210,7 +237,42 @@ export async function loadApp(
     const root = bundleDirectory(options.bundle);
     fds.push(new PreopenDirectory('/bundle', root.contents));
   }
-  const wasi = new WASI(options.args ?? ['Counter'], options.env ?? [], fds, { debug: options.debug ?? false });
+  // Phase 19: the home directory and the temporary directory.
+  fds.push(new PreopenDirectory(HOME, (options.home ?? homeDirectory(new Map())).contents));
+  fds.push(new PreopenDirectory(TMP, new Map<string, Inode>()));
+  // The zone files CoreFoundation reads for the viewer's `TZ` (zoneinfo.ts).
+  fds.push(new PreopenDirectory('/usr/share/zoneinfo', zoneInfoEntries()));
+  const given = new Set((options.env ?? []).map((entry) => entry.split('=', 1)[0]));
+  const env = [...HOME_ENVIRONMENT.filter((entry) => !given.has(entry.split('=', 1)[0])), ...(options.env ?? [])];
+  const wasi = new WASI(options.args ?? ['Counter'], env, fds, { debug: options.debug ?? false });
+  // Any call that can change a file marks the files as written; the loader
+  // reports that once per drain.
+  let filesWritten = false;
+  const imports = wasi.wasiImport as Record<string, (...args: never[]) => unknown>;
+  for (const name of ['fd_pwrite', 'fd_allocate', 'fd_filestat_set_size', 'path_create_directory', 'path_remove_directory',
+    'path_unlink_file', 'path_rename', 'path_link']) {
+    const original = imports[name];
+    if (!original) continue;
+    imports[name] = (...args: never[]) => {
+      filesWritten = true;
+      return original(...args);
+    };
+  }
+  const writeImport = imports['fd_write'];
+  if (writeImport) {
+    imports['fd_write'] = (...args: never[]) => {
+      if ((args[0] as unknown as number) > 2) filesWritten = true;
+      return writeImport(...args);
+    };
+  }
+  const openImport = imports['path_open'];
+  if (openImport) {
+    imports['path_open'] = (...args: never[]) => {
+      // oflags: CREAT (1) or TRUNC (8) change the tree or a file.
+      if (((args[4] as unknown as number) & 9) !== 0) filesWritten = true;
+      return openImport(...args);
+    };
+  }
 
   const instance = await WebAssembly.instantiate(module, {
     [WASI_MODULE]: wasi.wasiImport,
@@ -248,6 +310,18 @@ export async function loadApp(
     throw new WasmLoadError(`${url} exited with code ${exitCode}`);
   }
 
+  // Phase 13: `request` ops are answered asynchronously with a `response`
+  // event through the same path as the renderer's events, which also runs
+  // the executor so the awaiting Swift task resumes.
+  const requests = options.requests;
+  let deliver: (event: RendererEvent) => boolean = () => false;
+  const perform = (op: RequestOp): void => {
+    performHostRequest(op, requests).then(
+      (value) => deliver({ type: 'response', id: op.id, value }),
+      (error: unknown) => deliver({ type: 'response', id: op.id, error: error instanceof Error ? error.message : String(error) }),
+    );
+  };
+
   const drain = (): void => {
     let ops = readPendingOps(exports);
     // Clear before applying so a renderer error never re-applies stale ops.
@@ -258,7 +332,20 @@ export async function loadApp(
       if (latest && latest.op === 'defaults') options.onDefaults?.(latest.values);
       ops = ops.filter((op) => op.op !== 'defaults');
     }
+    if (ops.some((op) => op.op === 'swiftdata')) {
+      // Every save matters (each holds only what changed), in order.
+      for (const op of ops) if (op.op === 'swiftdata') options.onSwiftData?.(op);
+      ops = ops.filter((op) => op.op !== 'swiftdata');
+    }
+    if (ops.some((op) => op.op === 'request')) {
+      for (const op of ops) if (op.op === 'request') perform(op);
+      ops = ops.filter((op) => op.op !== 'request');
+    }
     if (ops.length > 0) onOps(ops);
+    if (filesWritten) {
+      filesWritten = false;
+      options.onFilesWritten?.();
+    }
   };
 
   const supportsJsonEvents =
@@ -278,6 +365,32 @@ export async function loadApp(
     runJobs();
   };
 
+  /** `bytes` in linear memory for the next event (`sb_bytes`), as the event names them. */
+  const putBytes = (bytes: Uint8Array): { $bytes: number } | string => {
+    if (typeof exports.sb_bytes !== 'function') return base64Encode(bytes);
+    const ptr = writeBytes(exports, bytes);
+    return { $bytes: exports.sb_bytes(ptr, bytes.byteLength) };
+  };
+
+  const sendEventJson = (event: RendererEvent): boolean => {
+    if (event.type === 'tap' && event.x === undefined) {
+      // A tap with a point (`onTapGesture { point in }`) goes as JSON.
+      sendEvent(event.id);
+      return true;
+    }
+    if (!supportsJsonEvents) return false;
+    // A fetched body crosses as bytes: copied into linear memory and named
+    // `{"$bytes": n}` in the event, or as base64 for a module without `sb_bytes`.
+    const json = event.type === 'response' ? JSON.stringify(event, (_key, value: unknown) => (value instanceof Uint8Array ? putBytes(value) : value)) : JSON.stringify(event);
+    const bytes = encoder.encode(json);
+    const ptr = writeBytes(exports, bytes);
+    exports.sb_event_json!(ptr, bytes.byteLength);
+    drain();
+    runJobs();
+    return true;
+  };
+  deliver = sendEventJson;
+
   drain();
   runJobs();
 
@@ -289,28 +402,7 @@ export async function loadApp(
     supportsJobs,
     runJobs,
     sendEvent,
-    sendEventJson(event: RendererEvent): boolean {
-      if (event.type === 'tap') {
-        sendEvent(event.id);
-        return true;
-      }
-      if (!supportsJsonEvents) return false;
-      const bytes = encoder.encode(JSON.stringify(event));
-      const ptr = exports.sb_alloc!(bytes.byteLength) >>> 0;
-      // `memory.buffer` must be read after `sb_alloc`: allocating may grow
-      // linear memory and detach the previous ArrayBuffer.
-      const memory = exports.memory.buffer;
-      if (ptr + bytes.byteLength > memory.byteLength) {
-        throw new WasmLoadError(
-          `sb_alloc(${bytes.byteLength}) returned ${ptr}, outside linear memory (${memory.byteLength} bytes)`,
-        );
-      }
-      new Uint8Array(memory, ptr, bytes.byteLength).set(bytes);
-      exports.sb_event_json!(ptr, bytes.byteLength);
-      drain();
-      runJobs();
-      return true;
-    },
+    sendEventJson,
     snapshotState(): string | null {
       if (!supportsSnapshot) return null;
       // `sb_state_ptr` refreshes the buffer, so call it before `sb_state_len`.
@@ -328,18 +420,32 @@ export async function loadApp(
   };
 }
 
-async function compile(url: string): Promise<WebAssembly.Module> {
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new WasmLoadError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
-  }
+/** The module at `url`, whole or joined from the parts it was published as. */
+export async function compile(url: string, fetchImpl: typeof fetch = fetch): Promise<WebAssembly.Module> {
+  const response = await fetchImpl(url);
   const type = response.headers.get('content-type') ?? '';
-  if (typeof WebAssembly.compileStreaming === 'function' && type.includes('application/wasm')) {
-    return WebAssembly.compileStreaming(response);
+  if (response.ok && typeof WebAssembly.compileStreaming === 'function' && type.includes('application/wasm')) {
+    try {
+      return await WebAssembly.compileStreaming(response);
+    } catch (error) {
+      // A host may answer a missing file with its fallback page and still
+      // label it a Wasm module (Cloudflare Pages does, with the `/*.wasm`
+      // Content-Type rule in public/_headers): the module may be published
+      // as parts.
+      const joined = await fetchParts(url, fetchImpl);
+      if (joined) return WebAssembly.compile(joined);
+      throw error;
+    }
   }
   // Fall back for servers that mislabel the MIME type.
-  const bytes = await response.arrayBuffer();
+  const bytes = response.ok ? await response.arrayBuffer() : new ArrayBuffer(0);
   if (bytes.byteLength < 8 || new DataView(bytes).getUint32(0, true) !== 0x6d736100) {
+    // A module larger than the host allows a file to be is published as
+    // parts (plugins/swift-wasm.ts); the host answers the whole one's URL
+    // with a 404 or its fallback page.
+    const joined = await fetchParts(url, fetchImpl);
+    if (joined) return WebAssembly.compile(joined);
+    if (!response.ok) throw new WasmLoadError(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
     throw new WasmLoadError(
       `${url} is not a Wasm binary (${bytes.byteLength} bytes, content-type "${type}"). ` +
         'Has scripts/build-wasm.sh copied the module into Web/public/?',
@@ -348,6 +454,42 @@ async function compile(url: string): Promise<WebAssembly.Module> {
   return WebAssembly.compile(bytes);
 }
 
+/**
+ * The module published as parts at `<url>.parts.json` (`{ size, parts }`),
+ * fetched in parallel and joined; null when there is no such manifest.
+ */
+export async function fetchParts(url: string, fetchImpl: typeof fetch = fetch): Promise<Uint8Array<ArrayBuffer> | null> {
+  const manifestURL = `${url}.parts.json`;
+  let manifest: { size?: unknown; parts?: unknown };
+  try {
+    const response = await fetchImpl(manifestURL);
+    if (!response.ok) return null;
+    manifest = (await response.json()) as typeof manifest;
+  } catch {
+    return null;
+  }
+  const { size, parts } = manifest;
+  if (typeof size !== 'number' || !Array.isArray(parts) || !parts.every((part) => typeof part === 'string')) {
+    throw new WasmLoadError(`${manifestURL} is not a parts manifest`);
+  }
+  const base = new URL(manifestURL, typeof location === 'undefined' ? 'http://localhost/' : location.href);
+  const chunks = await Promise.all(parts.map(async (part) => {
+    const partURL = new URL(part, base).href;
+    const response = await fetchImpl(partURL);
+    if (!response.ok) throw new WasmLoadError(`Failed to fetch ${partURL}: ${response.status} ${response.statusText}`);
+    return new Uint8Array(await response.arrayBuffer());
+  }));
+  const joined = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    if (offset + chunk.byteLength > size) throw new WasmLoadError(`${manifestURL}: the parts are larger than ${size} bytes`);
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  if (offset !== size) throw new WasmLoadError(`${manifestURL}: the parts hold ${offset} of ${size} bytes`);
+  return joined;
+}
+
 function checkImports(module: WebAssembly.Module): void {
   const foreign = WebAssembly.Module.imports(module).filter((i) => i.module !== WASI_MODULE);
   if (foreign.length > 0) {
@@ -362,11 +504,61 @@ function checkImports(module: WebAssembly.Module): void {
 const decoder = new TextDecoder('utf-8', { fatal: true });
 const encoder = new TextEncoder();
 
+/** Copies `bytes` into a buffer from `sb_alloc` and answers where it starts. */
+function writeBytes(exports: SwiftBrowserExports, bytes: Uint8Array): number {
+  const ptr = exports.sb_alloc!(bytes.byteLength) >>> 0;
+  // `memory.buffer` must be read after `sb_alloc`: allocating may grow
+  // linear memory and detach the previous ArrayBuffer.
+  const memory = exports.memory.buffer;
+  if (ptr + bytes.byteLength > memory.byteLength) {
+    throw new WasmLoadError(`sb_alloc(${bytes.byteLength}) returned ${ptr}, outside linear memory (${memory.byteLength} bytes)`);
+  }
+  new Uint8Array(memory, ptr, bytes.byteLength).set(bytes);
+  return ptr;
+}
+
+/** The pending ops' `count` byte buffers (`sb_bytes_*`), each copied out of linear memory. */
+function readPendingBytes(exports: SwiftBrowserExports, count: number): Uint8Array[] {
+  if (count === 0 || typeof exports.sb_bytes_ptr !== 'function' || typeof exports.sb_bytes_len !== 'function') return [];
+  const out: Uint8Array[] = [];
+  for (let i = 0; i < count; i++) {
+    const ptr = exports.sb_bytes_ptr(i) >>> 0;
+    const len = exports.sb_bytes_len(i) >>> 0;
+    const memory = exports.memory.buffer;
+    if (ptr + len > memory.byteLength) {
+      throw new WasmLoadError(`sb_bytes_ptr/len(${i}) (${ptr}, ${len}) point outside linear memory (${memory.byteLength} bytes)`);
+    }
+    out.push(new Uint8Array(memory, ptr, len).slice());
+  }
+  return out;
+}
+
+/** `value` with each `{"$bytes": n}` replaced by the `n`th buffer. */
+function resolveBytes(value: unknown, buffers: readonly Uint8Array[]): unknown {
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) value[i] = resolveBytes(value[i], buffers);
+    return value;
+  }
+  if (typeof value !== 'object' || value === null) return value;
+  const record = value as Record<string, unknown>;
+  const n = record['$bytes'];
+  if (typeof n === 'number' && Object.keys(record).length === 1) {
+    const buffer = buffers[n];
+    if (!buffer) throw new WasmLoadError(`Pending ops name bytes ${n}, but there are ${buffers.length}`);
+    return buffer;
+  }
+  for (const key in record) record[key] = resolveBytes(record[key], buffers);
+  return record;
+}
+
 /**
  * Read the pending ops buffer. `memory.buffer` is re-read on every call: the
  * ArrayBuffer is detached whenever linear memory grows.
  */
 function readPendingOps(exports: SwiftBrowserExports): Op[] {
+  // Asked first: it tells Swift this page reads bytes beside the JSON, so
+  // the ops it serializes next name them (docs/ops-protocol.md, "Bytes").
+  const byteCount = typeof exports.sb_bytes_count === 'function' && typeof exports.sb_bytes_ptr === 'function' && typeof exports.sb_bytes_len === 'function' ? exports.sb_bytes_count() >>> 0 : 0;
   const ptr = exports.sb_ops_ptr() >>> 0;
   const len = exports.sb_ops_len() >>> 0;
   if (len === 0) return [];
@@ -396,5 +588,8 @@ function readPendingOps(exports: SwiftBrowserExports): Op[] {
   if (bad !== undefined) {
     throw new WasmLoadError(`Unknown op in pending buffer: ${JSON.stringify(bad)}`);
   }
+  // Image files and other bytes come beside the JSON (docs/ops-protocol.md, "Bytes").
+  const buffers = readPendingBytes(exports, byteCount);
+  if (buffers.length > 0) resolveBytes(parsed, buffers);
   return parsed as Op[];
 }

package/src/webAuth.ts

@@ -0,0 +1,267 @@
+/**
+ * Signing in (docs/ops-protocol.md, "Signing in"): the page side of
+ * AuthenticationServices' `ASWebAuthenticationSession` and SwiftUI's
+ * `WebAuthenticationSession` (Sources/AuthenticationServices). The app sends a
+ * `webAuth` request with the provider's authorize URL; the page opens it in a
+ * popup window and answers with the URL the window ends at.
+ *
+ * An app's OAuth redirect is a URL in its own scheme (`icecubesapp://`), which
+ * a page cannot receive. The shim swaps it for the page's callback page,
+ * `/app/oauth-callback.html?sb_scheme=icecubesapp` (FoundationBridge's
+ * WebAuthRedirects.swift), in the authorize URL and in the app's own requests
+ * to the provider, so the provider redirects the popup there. That page
+ * (public/app/oauth-callback.html) posts its URL to this page, by
+ * `postMessage` to its opener and on a `BroadcastChannel` (which still works
+ * when a provider's `Cross-Origin-Opener-Policy` cut the popup off from its
+ * opener), and closes. The app rebuilds `icecubesapp://?code=…` from it.
+ *
+ * Browsers only open a popup shortly after a tap, and an app usually registers
+ * with the provider first (a network round trip). When the popup is blocked,
+ * the page asks the viewer to continue and opens it from that click. Closing
+ * the popup, or dismissing that prompt, fails the request with `cancelled: …`,
+ * which the app sees as `ASWebAuthenticationSessionError.canceledLogin`.
+ */
+
+import type { WebAuthRequestParams } from './protocol';
+
+/** Where the callback page is served, relative to the site's base. */
+export const CALLBACK_PATH = 'app/oauth-callback.html';
+/** The `type` of the callback page's message. */
+export const CALLBACK_MESSAGE = 'sb-web-auth-callback';
+/** The `BroadcastChannel` the callback page also posts on. */
+export const CALLBACK_CHANNEL = 'sb-web-auth';
+
+/** The value of a `webAuth` `start`: the URL the sign-in window ended at. */
+export interface WebAuthResult {
+  url: string;
+}
+
+/** The parts of a `Window` the session uses (tests substitute them). */
+export interface PopupLike {
+  readonly closed: boolean;
+  close(): void;
+}
+
+/** The browser facilities a sign-in uses; tests substitute them. */
+export interface WebAuthHost {
+  /** Opens `url` in a popup window; null when the browser blocked it. */
+  open(url: string): PopupLike | null;
+  /** Calls `handler` with each URL the callback page reports; returns a function that stops listening. */
+  onCallback(handler: (url: string) => void): () => void;
+  /**
+   * After a blocked popup: asks the viewer to continue, and opens `url` from
+   * their click. Resolves with the popup, or null when they cancel.
+   */
+  askToOpen?(url: string): Promise<PopupLike | null>;
+  /** How often to check whether the viewer closed the popup, in ms (default 500). */
+  pollInterval?: number;
+}
+
+/** The callback page's URL for a page whose base URL (`import.meta.env.BASE_URL` resolved against the location) is `base`. */
+export function callbackPageURL(base: string): string {
+  return new URL(CALLBACK_PATH, base).href;
+}
+
+/** The URL in a callback page's message, or null when `data` is not one. */
+export function callbackURLOf(data: unknown): string | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const message = data as { type?: unknown; url?: unknown };
+  return message.type === CALLBACK_MESSAGE && typeof message.url === 'string' ? message.url : null;
+}
+
+interface PendingSignIn {
+  popup: PopupLike | null;
+  settle: (outcome: { url: string } | { error: string }) => void;
+}
+
+/**
+ * The page's sign-in sessions: one at a time, as on iOS. A new `start`
+ * cancels the one before it.
+ */
+export class WebAuthSessions {
+  private pending: PendingSignIn | null = null;
+
+  constructor(private readonly host: WebAuthHost) {}
+
+  /**
+   * Performs one `webAuth` request. `start` must be called within the task
+   * that received the request: it opens the popup before its first `await`.
+   */
+  perform(params: WebAuthRequestParams): Promise<WebAuthResult | Record<string, never>> {
+    if (params.action === 'cancel') {
+      this.cancel('cancelled: the app cancelled the sign-in');
+      return Promise.resolve({});
+    }
+    if (!params.url || !/^https?:/i.test(params.url)) {
+      return Promise.reject(new Error(`unsupported: cannot sign in at ${params.url ?? '(no URL)'}`));
+    }
+    return this.start(params.url);
+  }
+
+  /** Ends the pending sign-in, if any, with `message`, and closes its window. */
+  cancel(message: string): void {
+    this.pending?.settle({ error: message });
+  }
+
+  private start(url: string): Promise<WebAuthResult> {
+    this.cancel('cancelled: another sign-in started');
+    return new Promise<WebAuthResult>((resolve, reject) => {
+      let timer: ReturnType<typeof setInterval> | null = null;
+      let closedSeen = false;
+      const pending: PendingSignIn = { popup: null, settle: () => {} };
+      const stopListening = this.host.onCallback((callback) => pending.settle({ url: callback }));
+      pending.settle = (outcome) => {
+        if (this.pending !== pending) return;
+        this.pending = null;
+        stopListening();
+        if (timer !== null) clearInterval(timer);
+        try {
+          if (pending.popup && !pending.popup.closed) pending.popup.close();
+        } catch {
+          // A window another origin owns may refuse; it is the viewer's then.
+        }
+        if ('url' in outcome) resolve({ url: outcome.url });
+        else reject(new Error(outcome.error));
+      };
+      this.pending = pending;
+
+      const watch = (popup: PopupLike): void => {
+        pending.popup = popup;
+        timer = setInterval(() => {
+          if (!popup.closed) return;
+          // The callback page posts, then closes itself: give its message one
+          // more tick to arrive before calling the sign-in cancelled.
+          if (!closedSeen) {
+            closedSeen = true;
+            return;
+          }
+          pending.settle({ error: 'cancelled: the viewer closed the sign-in window' });
+        }, this.host.pollInterval ?? 500);
+      };
+
+      // Opened before any await, so a tap's activation still counts.
+      const popup = this.host.open(url);
+      if (popup) {
+        watch(popup);
+        return;
+      }
+      if (!this.host.askToOpen) {
+        pending.settle({ error: 'blocked: the browser blocked the sign-in window' });
+        return;
+      }
+      this.host.askToOpen(url).then(
+        (opened) => {
+          if (this.pending !== pending) {
+            opened?.close();
+            return;
+          }
+          if (opened) watch(opened);
+          else pending.settle({ error: 'cancelled: the viewer did not continue to the sign-in window' });
+        },
+        (error: unknown) => pending.settle({ error: `blocked: ${error instanceof Error ? error.message : String(error)}` }),
+      );
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The browser
+// ---------------------------------------------------------------------------
+
+/** A popup centered on the page, the size of a phone's sign-in sheet. */
+function popupFeatures(): string {
+  const width = 480;
+  const height = 720;
+  const left = Math.max(0, Math.round(window.screenX + (window.outerWidth - width) / 2));
+  const top = Math.max(0, Math.round(window.screenY + (window.outerHeight - height) / 2));
+  return `popup,width=${width},height=${height},left=${left},top=${top}`;
+}
+
+/**
+ * The prompt shown when the browser blocked the popup: the provider's host and
+ * two buttons. Continue opens the popup from the viewer's click.
+ */
+function promptToOpen(url: string, open: (url: string) => PopupLike | null): Promise<PopupLike | null> {
+  let host = url;
+  try {
+    host = new URL(url).host;
+  } catch {
+    // Shown as is.
+  }
+  const overlay = document.createElement('div');
+  overlay.className = 'sb-web-auth-prompt';
+  overlay.setAttribute('role', 'dialog');
+  overlay.setAttribute('aria-modal', 'true');
+  overlay.setAttribute('aria-label', 'Sign in');
+  overlay.style.cssText =
+    'position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;justify-content:center;' +
+    'background:rgba(0,0,0,0.4);font:15px/1.4 -apple-system,system-ui,sans-serif;';
+  const card = document.createElement('div');
+  card.style.cssText =
+    'max-width:300px;margin:16px;padding:20px;border-radius:14px;background:Canvas;color:CanvasText;' +
+    'box-shadow:0 10px 40px rgba(0,0,0,0.3);text-align:center;';
+  const title = document.createElement('p');
+  title.style.cssText = 'margin:0 0 6px;font-weight:600;font-size:17px;';
+  title.textContent = `Sign in to ${host}`;
+  const body = document.createElement('p');
+  body.style.cssText = 'margin:0 0 16px;opacity:0.7;';
+  body.textContent = 'The sign-in page opens in a new window.';
+  const buttons = document.createElement('div');
+  buttons.style.cssText = 'display:flex;gap:8px;justify-content:center;';
+  const button = (label: string, action: string, primary: boolean): HTMLButtonElement => {
+    const element = document.createElement('button');
+    element.type = 'button';
+    element.textContent = label;
+    element.dataset['action'] = action;
+    element.style.cssText =
+      'flex:1;padding:10px 14px;border-radius:10px;border:0;font:inherit;cursor:pointer;' +
+      (primary ? 'background:#007aff;color:#fff;font-weight:600;' : 'background:rgba(120,120,128,0.2);color:inherit;');
+    return element;
+  };
+  const cancel = button('Cancel', 'cancel', false);
+  const proceed = button('Continue', 'continue', true);
+  buttons.append(cancel, proceed);
+  card.append(title, body, buttons);
+  overlay.append(card);
+  document.body.append(overlay);
+  proceed.focus();
+  return new Promise((resolve) => {
+    const finish = (popup: PopupLike | null): void => {
+      overlay.remove();
+      resolve(popup);
+    };
+    proceed.addEventListener('click', () => finish(open(url)));
+    cancel.addEventListener('click', () => finish(null));
+  });
+}
+
+/** The real browser: `window.open`, the callback page's messages, and the prompt. */
+export function browserWebAuthHost(): WebAuthHost | undefined {
+  if (typeof window === 'undefined' || typeof window.open !== 'function') return undefined;
+  const open = (url: string): PopupLike | null => window.open(url, 'sb-web-auth', popupFeatures());
+  const host: WebAuthHost = {
+    open,
+    onCallback(handler) {
+      const onMessage = (event: MessageEvent): void => {
+        if (event.origin !== location.origin) return;
+        const url = callbackURLOf(event.data);
+        if (url) handler(url);
+      };
+      window.addEventListener('message', onMessage);
+      let channel: BroadcastChannel | null = null;
+      if (typeof BroadcastChannel === 'function') {
+        channel = new BroadcastChannel(CALLBACK_CHANNEL);
+        channel.onmessage = (event: MessageEvent) => {
+          const url = callbackURLOf(event.data);
+          if (url) handler(url);
+        };
+      }
+      return () => {
+        window.removeEventListener('message', onMessage);
+        channel?.close();
+      };
+    },
+  };
+  if (typeof document !== 'undefined') host.askToOpen = (url) => promptToOpen(url, open);
+  return host;
+}