@swiftbrowser/native 0.18.3 → 0.21.0

package/src/hostRequests.ts

@@ -14,23 +14,31 @@
  * `webAuthenticate` is the sign-in window apps open for OAuth: the system's
  * sheet, resolving with the callback URL.
  *
+ * `audioEngine` is `AVAudioEngine` (@swiftbrowser/react): each command an
+ * `audioEngine` request, which Host/AudioEngineBridge.swift performs as it
+ * arrives, in order. `languageModel` is Foundation Models' on-device model
+ * (`LanguageModelSession`): `languageModel` requests, which
+ * Host/LanguageModelBridge.swift answers.
+ *
  * `files` is the app's sandbox for `fileManager` (@swiftbrowser/react): the
- * `files` requests of Host/FilesBridge.swift, bytes crossing as base64, with
+ * `files` requests of Host/FilesBridge.swift, bytes crossing as views beside the JSON (base64 to an older host), with
  * the standard directories from the bridge's `appDirectories()`.
  */
 
-import { objectURL, SimpleBlob, SimpleFile } from './blob';
+import { blobBytes, LazyFile, objectURL, SimpleBlob, SimpleFile } from './blob';
 import type { NativeBridge } from './bridge';
-import { base64Decode, base64Encode } from './encoding';
+import { base64Encode, bridgedBytes } from './encoding';
 import { nativeUndoHost } from './undo';
 
-export type HostRequestBridge = Required<Pick<NativeBridge, 'hostRequest'>> & Pick<NativeBridge, 'appDirectories'>;
+export type HostRequestBridge = Required<Pick<NativeBridge, 'hostRequest'>> & Pick<NativeBridge, 'appDirectories' | 'hostRequestBytes'>;
 
-/** A file as it crosses the bridge: its name, MIME type and bytes (base64). */
+/** A file as it crosses the bridge: its name, MIME type and bytes (a view beside the JSON, or base64 to a host without them). */
 export interface BridgedFile {
   name: string;
   type: string;
-  data: string;
+  /** The bytes; absent when the file is still on disk, named by `url`. */
+  data?: string | Uint8Array;
+  url?: string;
 }
 
 export interface WebAuthenticateOptions {
@@ -50,14 +58,15 @@ export function installHostRequests(native: HostRequestBridge): void {
   fileWatchers.clear();
 }
 
-/** The bridge's `__sbHostResponse(id, result)`. */
-export function receiveHostResponse(id: number, result: string | { value?: unknown; error?: string }): void {
+/** The bridge's `__sbHostResponse(id, result, ...buffers)`: the buffers go where the JSON says `{ "$bytes": n }`. */
+export function receiveHostResponse(id: number, result: string | { value?: unknown; error?: string }, ...buffers: ArrayBufferView[]): void {
   const waiting = pending.get(id);
   if (!waiting) return;
   pending.delete(id);
   let parsed: { value?: unknown; error?: string };
   try {
-    parsed = typeof result === 'string' ? (JSON.parse(result) as { value?: unknown; error?: string }) : result;
+    parsed =
+      typeof result === 'string' ? (JSON.parse(result, buffers.length ? placeBytes(buffers) : undefined) as { value?: unknown; error?: string }) : result;
   } catch {
     waiting.reject(new Error('host: malformed response'));
     return;
@@ -80,8 +89,40 @@ export function hostRequest<T = unknown>(kind: string, params: Record<string, un
     }
     const id = nextId++;
     pending.set(id, { resolve: resolve as (value: unknown) => void, reject });
-    bridge.hostRequest(id, kind, JSON.stringify(params));
+    // Through `hostRequestBytes` whenever the host has it, views or not: the
+    // host then answers with bytes beside the JSON too.
+    const { json, views } = liftBytes(params, bridge.hostRequestBytes !== undefined);
+    if (bridge.hostRequestBytes) bridge.hostRequestBytes(id, kind, json, ...views);
+    else bridge.hostRequest(id, kind, json);
+  });
+}
+
+/**
+ * The params as JSON with their bytes lifted out: each typed array or
+ * `ArrayBuffer` becomes `{ "$bytes": n }` and the nth of `views`, for a host
+ * with `hostRequestBytes`; without one, base64 of its bytes in place, the
+ * form every host reads (docs/notes/bytes.md).
+ */
+export function liftBytes(params: unknown, lift: boolean): { json: string; views: ArrayBufferView[] } {
+  const views: ArrayBufferView[] = [];
+  const json = JSON.stringify(params, (_key, value: unknown) => {
+    const view = value instanceof ArrayBuffer ? new Uint8Array(value) : ArrayBuffer.isView(value) ? value : null;
+    if (!view) return value;
+    if (!lift) return base64Encode(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+    views.push(view);
+    return { $bytes: views.length - 1 };
   });
+  return { json, views };
+}
+
+/** A JSON reviver putting `buffers` where the text says `{ "$bytes": n }`. */
+function placeBytes(buffers: ArrayBufferView[]): (key: string, value: unknown) => unknown {
+  return (_key, value) => {
+    if (value && typeof value === 'object' && typeof (value as { $bytes?: unknown }).$bytes === 'number') {
+      return buffers[(value as { $bytes: number }).$bytes] ?? value;
+    }
+    return value;
+  };
 }
 
 /** Forgets the bridge and the waiting requests, for tests. */
@@ -92,12 +133,33 @@ export function resetHostRequests(): void {
 }
 
 async function bridgedFile(file: SimpleBlob & { name?: string }): Promise<BridgedFile> {
-  return { name: file.name ?? 'file', type: file.type, data: base64Encode(file.bytes()) };
+  // A picked file still on disk goes as its URL: the host reads it itself.
+  if (file instanceof LazyFile && file.isWhole) return { name: file.name ?? 'file', type: file.type, url: file.url };
+  return { name: file.name ?? 'file', type: file.type, data: await blobBytes(file) };
+}
+
+/** A file as a host answers it: bytes in place (`data`), or still on disk (`url`, `size`), read on demand through the files bridge. */
+interface AnsweredFile {
+  name: string;
+  type: string;
+  data?: string | Uint8Array;
+  url?: string;
+  size?: number;
+  lastModified?: number;
+}
+
+/** Reads a range of a file on disk through the files bridge (FilesBridge.swift `readRange`). */
+async function readFileRange(url: string, start: number, end: number): Promise<Uint8Array> {
+  return bridgedBytes((await hostRequest<{ data?: string | Uint8Array }>('files', { action: 'readRange', url, start, end }))?.data ?? '');
 }
 
 function filesOf(value: unknown): SimpleFile[] {
-  const files = (value as { files?: BridgedFile[] } | undefined)?.files ?? [];
-  return files.map((file) => new SimpleFile([base64Decode(file.data)], file.name, { type: file.type }));
+  const files = (value as { files?: AnsweredFile[] } | undefined)?.files ?? [];
+  return files.map((file) => {
+    const options = { type: file.type, ...(typeof file.lastModified === 'number' ? { lastModified: file.lastModified } : {}) };
+    if (file.data === undefined && typeof file.url === 'string') return LazyFile.make(file.url, file.name, file.size ?? 0, readFileRange, options);
+    return new SimpleFile([bridgedBytes(file.data ?? '')], file.name, options);
+  });
 }
 
 /**
@@ -159,18 +221,36 @@ function nativeFiles(directories: FileDirectories): Record<string, unknown> {
   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))),
+    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),
+    read: async (url: string): Promise<Uint8Array> => bridgedBytes((await files<{ data?: string | Uint8Array }>({ action: 'read', url }))?.data ?? ''),
+    // A range read through `FileHandle`, so a large file is read a piece at a time (FilesBridge.swift `readRange`).
+    readRange: async (url: string, start: number, end: number): Promise<Uint8Array> =>
+      bridgedBytes((await files<{ data?: string | Uint8Array }>({ action: 'readRange', url, start, end }))?.data ?? ''),
+    // A file the viewer picked or dropped (a `LazyFile`, still on disk) is copied there by the host (`importItem`); other bytes cross the bridge.
+    write: async (url: string, data: Uint8Array | SimpleBlob): Promise<void> => {
+      if (data instanceof LazyFile) {
+        if (data.isWhole) {
+          await files({ action: 'importItem', from: data.url, to: url });
+          return;
+        }
+        await files({ action: 'write', url, data: await data.bytesAsync() });
+        return;
+      }
+      await files({ action: 'write', url, data: data instanceof SimpleBlob ? data.bytes() : data });
+    },
     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; 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 });
+      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,
@@ -192,6 +272,9 @@ export function nativeHostEnvironment(): Record<string, unknown> {
   const directories = appDirectories();
   return {
     ...(directories ? { files: nativeFiles(directories) } : {}),
+    // A file dropped on the app, left on disk by the host (Drawing.swift's drop destination): a `LazyFile` read by range.
+    fileFromReference: (item: { type: string; name?: string; path?: string; url: string; size?: number }): SimpleFile =>
+      LazyFile.make(item.url, item.path ?? item.name ?? 'file', item.size ?? 0, readFileRange, { type: item.type }),
     share: async (data: { title?: string; text?: string; url?: string; files?: SimpleFile[] }): Promise<void> => {
       const params: Record<string, unknown> = {};
       if (data.title) params['title'] = data.title;
@@ -207,20 +290,35 @@ export function nativeHostEnvironment(): Record<string, unknown> {
     },
     canShare: () => true,
     download: (blob: SimpleBlob, filename: string): void => {
-      void hostRequest('share', { files: [{ name: filename, type: blob.type, data: base64Encode(blob.bytes()) }] }).catch(() => undefined);
+      // A picked file still on disk goes by URL (the host copies it); bytes go in the same turn.
+      const file = blob instanceof LazyFile && blob.isWhole ? { name: filename, type: blob.type, url: blob.url } : null;
+      if (file) {
+        void hostRequest('share', { files: [file] }).catch(() => undefined);
+        return;
+      }
+      if (blob instanceof LazyFile) {
+        void blob
+          .bytesAsync()
+          .then((data) => hostRequest('share', { files: [{ name: filename, type: blob.type, data }] }))
+          .catch(() => undefined);
+        return;
+      }
+      void hostRequest('share', { files: [{ name: filename, type: blob.type, data: blob.bytes() }] }).catch(() => undefined);
     },
-    pickFiles: async (options: { accept: string; multiple: boolean }): Promise<SimpleFile[]> => filesOf(await hostRequest('pickFiles', { accept: options.accept, multiple: options.multiple })),
+    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),
+    // A picked file still on disk is its own URL (the image loader and AVPlayer read files); bytes become a `data:` URL.
+    objectURL: (file: SimpleBlob): string => (file instanceof LazyFile && file.isWhole ? file.url : objectURL(file)),
     clipboard: {
       writeText: (text: string): Promise<void> => hostRequest('clipboard', { action: 'write', text }).then(() => undefined),
       writeImage: async (png: Promise<SimpleBlob>): Promise<void> => {
         const file = await png;
-        await hostRequest('clipboard', { action: 'write', files: [{ name: 'image.png', type: file.type || 'image/png', data: base64Encode(file.bytes()) }] });
+        await hostRequest('clipboard', { action: 'write', files: [{ name: 'image.png', type: file.type || 'image/png', data: await blobBytes(file) }] });
       },
       readText: async (): Promise<string> => (await hostRequest<{ text?: string }>('clipboard', { action: 'readText' }))?.text ?? '',
     },
@@ -228,7 +326,16 @@ export function nativeHostEnvironment(): Record<string, unknown> {
     // 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',
+      credentialState: async (user: string): Promise<string> =>
+        (await hostRequest<{ state?: string } | null>('appleSignIn', { action: 'credentialState', user }))?.state ?? 'unknown',
+    },
+    // `AVAudioEngine` (AudioEngineBridge.swift): the app's engine commands, answered in the order sent.
+    audioEngine: {
+      perform: (command: Record<string, unknown>): Promise<unknown> => hostRequest('audioEngine', command),
+    },
+    // Foundation Models (LanguageModelBridge.swift): the app's sessions and streams, a `next` answered as a stream grows.
+    languageModel: {
+      perform: (command: Record<string, unknown>): Promise<unknown> => hostRequest('languageModel', command),
     },
     // `AVAudioRecorder` (AudioRecorderBridge.swift): a recording ends as a file URL in Documents; `trim` writes another.
     audioRecorder: {

package/src/index.ts

@@ -12,13 +12,12 @@
  */
 
 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';
 export { SimpleURL, SimpleURLSearchParams } from './url';
-export { SimpleBlob, SimpleFile, SimpleFormData, encodeMultipart, objectURL } from './blob';
+export { LazyFile, SimpleBlob, SimpleFile, SimpleFormData, blobBytes, encodeMultipart, encodeMultipartAsync, objectURL, partsBytes, type BodyPart } from './blob';
 export { NativeWebSocket, type NativeWebSocketEvent } from './webSocket';
 export { createSubtleCrypto } from './subtle';
 export { matchMedia, updateMediaEnvironment, type MediaEnvironment } from './matchMedia';

package/src/ios.ts

@@ -0,0 +1,253 @@
+/**
+ * What a CI job needs to hand an app's iOS build to phones, outside Xcode:
+ * an ad hoc provisioning profile made fresh through the App Store Connect
+ * API, and the over-the-air install page around the exported IPA. The
+ * reusable workflows (.github/workflows/sb-ios-adhoc.yml in the SwiftBrowser
+ * repository) run them as `swiftbrowser-native ios-profile` and
+ * `swiftbrowser-native ios-install-page`, from the app's own
+ * node_modules, so they come at the version of the app's @swiftbrowser
+ * packages.
+ */
+
+import { sign } from 'node:crypto';
+import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export interface AppStoreConnectKey {
+  /** The key's ID (ASC_KEY_ID). */
+  keyId: string;
+  /** The team's issuer ID (ASC_ISSUER_ID). */
+  issuer: string;
+  /** The .p8 key's text (ASC_KEY_P8). It needs the Admin or App Manager role. */
+  key: string;
+}
+
+export interface AdhocProfileOptions extends AppStoreConnectKey {
+  bundleId: string;
+  /** The profile's name, which the archive's PROVISIONING_PROFILE_SPECIFIER names. */
+  profileName: string;
+  /** The app's name, for the bundle ID when the team has none yet. */
+  appName: string;
+  /** Where profiles are installed; the user's home by default. */
+  home?: string;
+  /** For tests. */
+  fetch?: typeof fetch;
+  log?: (line: string) => void;
+}
+
+export interface AdhocProfile {
+  uuid: string;
+  /** The files written, one per folder Xcode reads profiles from. */
+  files: string[];
+  devices: string[];
+  certificates: number;
+}
+
+/** A JWT for the App Store Connect API, good for 20 minutes. */
+export function appStoreConnectToken({ keyId, issuer, key }: AppStoreConnectKey, now = Date.now()): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  const seconds = Math.floor(now / 1000);
+  const body = `${encode({ alg: 'ES256', kid: keyId, typ: 'JWT' })}.${encode({ iss: issuer, iat: seconds, exp: seconds + 1200, aud: 'appstoreconnect-v1' })}`;
+  const signature = sign('sha256', Buffer.from(body), { key, dsaEncoding: 'ieee-p1363' });
+  return `${body}.${signature.toString('base64url')}`;
+}
+
+interface Resource {
+  id: string;
+  attributes: Record<string, string | undefined>;
+}
+
+/**
+ * Makes the ad hoc profile `profileName` for `bundleId` again, with every
+ * enabled iOS device and every valid distribution certificate of the team,
+ * so a phone registered since the last build is in the next one: registers
+ * the bundle ID when the team has none, deletes the profile of that name if
+ * there is one, and installs the new one where Xcode looks.
+ */
+export async function makeAdhocProfile(options: AdhocProfileOptions): Promise<AdhocProfile> {
+  const { bundleId, profileName, appName } = options;
+  const request = options.fetch ?? fetch;
+  const log = options.log ?? ((line: string) => console.log(line));
+  const authorization = `Bearer ${appStoreConnectToken(options)}`;
+
+  const api = async (method: string, path: string, body?: unknown): Promise<{ data: Resource | Resource[]; links?: { next?: string } } | null> => {
+    const response = await request(`https://api.appstoreconnect.apple.com${path}`, {
+      method,
+      headers: { authorization, 'content-type': 'application/json' },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const text = await response.text();
+    if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${text}`);
+    return text ? JSON.parse(text) : null;
+  };
+  /** Every page of a list. */
+  const list = async (path: string): Promise<Resource[]> => {
+    const items: Resource[] = [];
+    let next: string | null = path;
+    while (next) {
+      const page = await api('GET', next);
+      items.push(...((page?.data as Resource[]) ?? []));
+      const link = page?.links?.next;
+      next = link ? new URL(link).pathname + new URL(link).search : null;
+    }
+    return items;
+  };
+  const query = (params: Record<string, string>): string => new URLSearchParams(params).toString();
+
+  let bundle = (await list(`/v1/bundleIds?${query({ 'filter[identifier]': bundleId, limit: '200' })}`)).find(
+    (item) => item.attributes['identifier'] === bundleId,
+  );
+  if (!bundle) {
+    log(`Registering the bundle ID ${bundleId}.`);
+    bundle = (await api('POST', '/v1/bundleIds', { data: { type: 'bundleIds', attributes: { identifier: bundleId, name: appName, platform: 'IOS' } } }))!
+      .data as Resource;
+  }
+
+  const now = Date.now();
+  const certificates = (await list(`/v1/certificates?${query({ 'filter[certificateType]': 'DISTRIBUTION,IOS_DISTRIBUTION', limit: '200' })}`)).filter(
+    (item) => !item.attributes['expirationDate'] || Date.parse(item.attributes['expirationDate']) > now,
+  );
+  if (certificates.length === 0) throw new Error('The team has no valid distribution certificate.');
+
+  const devices = await list(`/v1/devices?${query({ 'filter[platform]': 'IOS', 'filter[status]': 'ENABLED', limit: '200' })}`);
+  if (devices.length === 0) throw new Error('The team has no enabled iOS devices: an ad hoc profile needs at least one.');
+
+  for (const old of await list(`/v1/profiles?${query({ 'filter[name]': profileName, limit: '200' })}`)) {
+    if (old.attributes['name'] !== profileName) continue;
+    log(`Deleting the old profile ${old.id}.`);
+    await api('DELETE', `/v1/profiles/${old.id}`);
+  }
+
+  const profile = (await api('POST', '/v1/profiles', {
+    data: {
+      type: 'profiles',
+      attributes: { name: profileName, profileType: 'IOS_APP_ADHOC' },
+      relationships: {
+        bundleId: { data: { type: 'bundleIds', id: bundle.id } },
+        certificates: { data: certificates.map((item) => ({ type: 'certificates', id: item.id })) },
+        devices: { data: devices.map((item) => ({ type: 'devices', id: item.id })) },
+      },
+    },
+  }))!.data as Resource;
+
+  const uuid = profile.attributes['uuid']!;
+  const content = Buffer.from(profile.attributes['profileContent']!, 'base64');
+  const home = options.home ?? homedir();
+  const files: string[] = [];
+  // Xcode 16 and later read the first; older ones the second.
+  for (const dir of [join(home, 'Library/Developer/Xcode/UserData/Provisioning Profiles'), join(home, 'Library/MobileDevice/Provisioning Profiles')]) {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${uuid}.mobileprovision`);
+    writeFileSync(file, content);
+    files.push(file);
+  }
+  const names = devices.map((device) => `${device.attributes['name']} (${device.attributes['model'] ?? device.attributes['deviceClass']})`);
+  log(`Made "${profileName}" (${uuid}) for ${bundleId}: ${devices.length} device(s), ${certificates.length} certificate(s).`);
+  for (const name of names) log(`- ${name}`);
+  return { uuid, files, devices: names, certificates: certificates.length };
+}
+
+export interface InstallPageOptions {
+  /** The exported IPA. */
+  ipa: string;
+  /** Where the page will be served from (`https://ios.app.pages.dev`): the manifest names the IPA there. */
+  url: string;
+  bundleId: string;
+  /** The build's version (`1.0.42`), its CFBundleVersion. */
+  version: string;
+  /** The app's name on the page and in the install prompt; the IPA's name by default. */
+  title?: string;
+  /** The same app in the browser, linked from the page. */
+  web?: string;
+  /** The commit it was built from. */
+  commit?: string;
+  /** When it was built; now by default. */
+  built?: Date;
+}
+
+const escapeXml = (text: string): string => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** The itms-services manifest for an IPA served at `ipaUrl`. */
+export function installManifest({ ipaUrl, bundleId, version, title }: { ipaUrl: string; bundleId: string; version: string; title: string }): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict><key>items</key><array><dict>
+  <key>assets</key><array><dict>
+    <key>kind</key><string>software-package</string>
+    <key>url</key><string>${escapeXml(ipaUrl)}</string>
+  </dict></array>
+  <key>metadata</key><dict>
+    <key>bundle-identifier</key><string>${escapeXml(bundleId)}</string>
+    <key>bundle-version</key><string>${escapeXml(version)}</string>
+    <key>kind</key><string>software</string>
+    <key>title</key><string>${escapeXml(title)}</string>
+  </dict>
+</dict></array></dict></plist>
+`;
+}
+
+/**
+ * Writes the install page into `outDir`: the IPA, its manifest, an
+ * `index.html` whose button installs it over the air (on a phone the
+ * profile names), and the `_headers` Cloudflare Pages serves them with.
+ * Returns the files written, relative to `outDir`.
+ */
+export function writeInstallPage(outDir: string, options: InstallPageOptions): string[] {
+  const ipaName = basename(options.ipa);
+  const title = options.title ?? ipaName.replace(/\.ipa$/, '');
+  const base = options.url.replace(/\/+$/, '');
+  const built = (options.built ?? new Date()).toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+  const html = (text: string): string => escapeXml(text);
+  mkdirSync(outDir, { recursive: true });
+  copyFileSync(options.ipa, join(outDir, ipaName));
+  writeFileSync(join(outDir, 'manifest.plist'), installManifest({ ipaUrl: `${base}/${ipaName}`, bundleId: options.bundleId, version: options.version, title }));
+  writeFileSync(
+    join(outDir, '_headers'),
+    `/manifest.plist
+  Content-Type: application/xml
+  Cache-Control: no-store
+/${ipaName}
+  Content-Type: application/octet-stream
+  Cache-Control: no-store
+`,
+  );
+  const install = `itms-services://?action=download-manifest&url=${base}/manifest.plist`;
+  writeFileSync(
+    join(outDir, 'index.html'),
+    `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="color-scheme" content="light dark" />
+  <title>Install ${html(title)}</title>
+  <style>
+    :root { --bg: #f2f2f7; --card: #fff; --fg: #000; --muted: #6e6e73; --tint: #007aff; }
+    @media (prefers-color-scheme: dark) { :root { --bg: #000; --card: #1c1c1e; --fg: #fff; --muted: #98989f; --tint: #0a84ff; } }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 24px 16px;
+      background: var(--bg); color: var(--fg); font: 17px/1.4 -apple-system, BlinkMacSystemFont, system-ui, sans-serif; }
+    main { width: 100%; max-width: 420px; background: var(--card); border-radius: 22px; padding: 28px 24px; text-align: center; }
+    h1 { font-size: 28px; margin: 0 0 4px; }
+    p { color: var(--muted); margin: 8px 0; font-size: 15px; }
+    a.install { display: block; margin: 24px 0 16px; padding: 14px; border-radius: 14px; background: var(--tint);
+      color: #fff; font-weight: 600; text-decoration: none; }
+    a { color: var(--tint); }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>${html(title)}</h1>
+    <p>Version ${html(options.version)} · built ${built}${options.commit ? ` from ${html(options.commit.slice(0, 7))}` : ''}</p>
+    <a class="install" href="${html(install)}">Install on this iPhone</a>
+    <p>Open this page in Safari on an iPhone whose device is registered with the team: an ad hoc build installs only on the devices its profile names. After installing, open Settings → General → VPN &amp; Device Management if iOS asks you to trust the developer.</p>${
+      options.web ? `\n    <p><a href="${html(options.web)}">Try it in the browser</a></p>` : ''
+    }
+  </main>
+</body>
+</html>
+`,
+  );
+  return [ipaName, 'manifest.plist', '_headers', 'index.html'];
+}

package/src/runtime.ts

@@ -33,7 +33,7 @@
  */
 
 import { nativeBridge, type NativeBridge } from './bridge';
-import { atobPolyfill, base64Decode, btoaPolyfill, SimpleTextDecoder, SimpleTextEncoder } from './encoding';
+import { atobPolyfill, base64Decode, btoaPolyfill, installNativeUTF8, SimpleTextDecoder, SimpleTextEncoder } from './encoding';
 import { createFetch } from './fetch';
 import { createImageGlobals } from './image';
 import { SimpleURL, SimpleURLSearchParams } from './url';
@@ -128,7 +128,10 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
       return String(value);
     }
   };
-  const log = (level: string) => (...args: unknown[]) => native.log(level, args.map(format).join(' '));
+  const log =
+    (level: string) =>
+    (...args: unknown[]) =>
+      native.log(level, args.map(format).join(' '));
   const timersByLabel = new Map<string, number>();
   const counts = new Map<string, number>();
   define('console', {
@@ -182,7 +185,12 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
   define('atob', atobPolyfill);
   define('btoa', btoaPolyfill);
 
-  const fetchGlobals = createFetch(native);
+  // Typed arrays beside the JSON both ways (docs/notes/bytes.md): a host with
+  // `hostRequestBytes` carries them for fetch, sockets and files alike.
+  const carriesBytes = typeof native.hostRequestBytes === 'function';
+  // UTF-8 on the host past a few dozen characters (encoding.ts).
+  installNativeUTF8(native.decodeUTF8 && native.encodeUTF8 ? { decode: native.decodeUTF8.bind(native), encode: native.encodeUTF8.bind(native) } : null);
+  const fetchGlobals = createFetch(native, { bytes: carriesBytes, streams: carriesBytes && native.fetchStreams?.() === true });
   define('fetch', fetchGlobals.fetch);
   define('Headers', fetchGlobals.Headers);
   define('Request', fetchGlobals.Request);
@@ -204,12 +212,15 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
     urlStatics.createObjectURL = (blob: SimpleBlob) => objectURL(blob);
     urlStatics.revokeObjectURL = () => {};
   }
-  const random = (count: number): Uint8Array => base64Decode(native.randomBytes(count));
+  const random = (count: number): Uint8Array => (native.randomValues ? native.randomValues(count) : base64Decode(native.randomBytes(count)));
   setBodyRandomness(random);
 
   // WebSockets (webSocket.ts) over the host's `URLSessionWebSocketTask`.
   if (native.wsOpen && native.wsSend && native.wsClose) {
-    NativeWebSocket.install({ wsOpen: native.wsOpen.bind(native), wsSend: native.wsSend.bind(native), wsClose: native.wsClose.bind(native) });
+    NativeWebSocket.install(
+      { wsOpen: native.wsOpen.bind(native), wsSend: native.wsSend.bind(native), wsClose: native.wsClose.bind(native) },
+      { bytes: carriesBytes },
+    );
     define('WebSocket', NativeWebSocket);
     define('__sbWebSocketEvent', NativeWebSocket.receive);
   }
@@ -219,7 +230,11 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
 
   // Host requests (hostRequests.ts): the share sheet, the pickers, the pasteboard, a sign-in.
   if (native.hostRequest && !native.workerPostMessage) {
-    installHostRequests({ hostRequest: native.hostRequest.bind(native), ...(native.appDirectories ? { appDirectories: native.appDirectories.bind(native) } : {}) });
+    installHostRequests({
+      hostRequest: native.hostRequest.bind(native),
+      ...(native.hostRequestBytes ? { hostRequestBytes: native.hostRequestBytes.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`.
@@ -251,14 +266,14 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
 
   define('crypto', {
     getRandomValues: <T extends ArrayBufferView>(array: T): T => {
-      const bytes = base64Decode(native.randomBytes(array.byteLength));
+      const bytes = random(array.byteLength);
       new Uint8Array(array.buffer, array.byteOffset, array.byteLength).set(bytes.subarray(0, array.byteLength));
       return array;
     },
     // Digests and HMAC on the host's CryptoKit (subtle.ts).
     subtle: createSubtleCrypto(native),
     randomUUID: (): string => {
-      const bytes = base64Decode(native.randomBytes(16));
+      const bytes = new Uint8Array(random(16));
       bytes[6] = (bytes[6]! & 0x0f) | 0x40;
       bytes[8] = (bytes[8]! & 0x3f) | 0x80;
       const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');

package/src/subtle.ts

@@ -9,7 +9,7 @@
 import type { NativeBridge } from './bridge';
 import { base64Decode, base64Encode } from './encoding';
 
-export type SubtleBridge = Pick<NativeBridge, 'digest' | 'hmac'>;
+export type SubtleBridge = Pick<NativeBridge, 'digest' | 'hmac' | 'digestBytes' | 'hmacBytes'>;
 
 type Algorithm = string | { name: string; hash?: string | { name: string } };
 
@@ -31,15 +31,16 @@ function algorithmName(algorithm: Algorithm): string {
 function hashName(algorithm: Algorithm): string {
   if (typeof algorithm === 'string') return algorithm.toUpperCase();
   const hash = algorithm.hash;
-  return (typeof hash === 'string' ? hash : hash?.name ?? '').toUpperCase();
+  return (typeof hash === 'string' ? hash : (hash?.name ?? '')).toUpperCase();
 }
 
 function bytesOf(data: ArrayBuffer | ArrayBufferView): Uint8Array {
   return data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 }
 
-function toBuffer(base64: string): ArrayBuffer {
-  const bytes = base64Decode(base64);
+/** A result as an `ArrayBuffer` of its own: base64 from an older host, or a typed array. */
+function toBuffer(result: string | Uint8Array): ArrayBuffer {
+  const bytes = typeof result === 'string' ? base64Decode(result) : result;
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
 }
 
@@ -55,7 +56,7 @@ export function createSubtleCrypto(native: SubtleBridge) {
     async digest(algorithm: Algorithm, data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer> {
       const name = algorithmName(algorithm);
       if (!DIGESTS.has(name)) throw notSupported(`the ${name} digest`);
-      const result = native.digest?.(name, base64Encode(bytesOf(data)));
+      const result = native.digestBytes ? native.digestBytes(name, bytesOf(data)) : native.digest?.(name, base64Encode(bytesOf(data)));
       if (!result) throw notSupported(`the ${name} digest`);
       return toBuffer(result);
     },
@@ -70,7 +71,10 @@ export function createSubtleCrypto(native: SubtleBridge) {
 
     async sign(algorithm: Algorithm, key: HmacKey, data: ArrayBuffer | ArrayBufferView): Promise<ArrayBuffer> {
       if (algorithmName(algorithm) !== 'HMAC' || key.algorithm?.name !== 'HMAC') throw notSupported(`signing with ${algorithmName(algorithm)}`);
-      const result = native.hmac?.(key.algorithm.hash.name, base64Encode(key.bytes), base64Encode(bytesOf(data)));
+      const hash = key.algorithm.hash.name;
+      const result = native.hmacBytes
+        ? native.hmacBytes(hash, key.bytes, bytesOf(data))
+        : native.hmac?.(hash, base64Encode(key.bytes), base64Encode(bytesOf(data)));
       if (!result) throw notSupported('HMAC');
       return toBuffer(result);
     },