@swiftbrowser/native 0.0.0-stage → 0.10.0

package/src/build.ts

@@ -0,0 +1,185 @@
+/**
+ * Builds `app.js` for an Xcode target: the runtime first (./runtime, so the
+ * web globals exist before React's scheduler reads them), then the app, as
+ * one script JavaScriptCore evaluates with `NativeApp.load`. `react-dom` is
+ * aliased to stubs (no DOM here); `@swiftbrowser/react` and React are
+ * bundled in. Node only (the CLI in ../bin and build scripts use it).
+ */
+
+import * as esbuild from 'esbuild';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface BuildOptions {
+  /** The app's entry module, which calls `run(<App />)`. */
+  entry: string;
+  /** Where to write the bundle (`<App>/app.js` in the Xcode target's folder). */
+  outfile: string;
+  minify?: boolean;
+  sourcemap?: boolean;
+  /** `process.env.NODE_ENV`; `production` when minifying, else `development`. */
+  mode?: 'development' | 'production';
+}
+
+export interface BuildResult {
+  code: string;
+  bytes: number;
+  warnings: string[];
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** The runtime's source; the package ships `src` so this resolves from `dist` too. */
+const runtimeEntry = fileURLToPath(new URL('../src/runtime.ts', import.meta.url));
+const reactSources = fileURLToPath(new URL('../../react/src/index.ts', import.meta.url));
+const stubs: Record<string, string> = {
+  'react-dom/client': fileURLToPath(new URL('../src/stubs/react-dom-client.ts', import.meta.url)),
+  'react-dom': fileURLToPath(new URL('../src/stubs/react-dom.ts', import.meta.url)),
+  // This package from its sources, so a bundle never needs its `dist` built first.
+  '@swiftbrowser/native/runtime': runtimeEntry,
+  '@swiftbrowser/native': fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+  // In this repository, @swiftbrowser/react from its sources too (installed, it is a built package).
+  ...(existsSync(reactSources) ? { '@swiftbrowser/react': reactSources } : {}),
+};
+
+function common(options: BuildOptions): esbuild.BuildOptions {
+  const mode = options.mode ?? (options.minify ? 'production' : 'development');
+  return {
+    bundle: true,
+    write: false,
+    format: 'iife',
+    platform: 'browser',
+    // JavaScriptCore on iOS 17 has every ES2022 feature.
+    target: ['safari16'],
+    minify: options.minify ?? false,
+    sourcemap: options.sourcemap ? 'inline' : false,
+    define: { 'process.env.NODE_ENV': JSON.stringify(mode), 'import.meta.env.DEV': JSON.stringify(mode === 'development') },
+    jsx: 'automatic',
+    logLevel: 'silent',
+    absWorkingDir: here,
+  };
+}
+
+/** Builds the two halves and joins them. */
+export async function bundle(options: BuildOptions): Promise<BuildResult> {
+  const runtime = await esbuild.build({ ...common(options), entryPoints: [runtimeEntry] });
+  const app = await esbuild.build({ ...common(options), entryPoints: [options.entry], alias: stubs });
+  const code = `${text(runtime)}\n${text(app)}`;
+  return {
+    code,
+    bytes: Buffer.byteLength(code),
+    warnings: [...runtime.warnings, ...app.warnings].map((warning) => warning.text),
+  };
+}
+
+function text(result: esbuild.BuildResult): string {
+  return result.outputFiles?.map((file) => file.text).join('\n') ?? '';
+}
+
+/** Builds and writes the bundle. */
+export async function buildApp(options: BuildOptions): Promise<BuildResult> {
+  const result = await bundle(options);
+  await mkdir(dirname(options.outfile), { recursive: true });
+  await writeFile(options.outfile, result.code);
+  return result;
+}
+
+export interface ServeOptions extends BuildOptions {
+  port?: number;
+  /** Called after every build (a log line). */
+  onBuild?: (result: BuildResult | Error) => void;
+}
+
+/**
+ * The dev loop: serves the dev bundle (devBuild.ts) for `NativeApp.watch(url:)`:
+ *
+ * | path | what |
+ * |---|---|
+ * | `/manifest.json` | `{ "vendor": <hash>, "app": <hash> }`, polled; `Cache-Control: no-store` |
+ * | `/vendor.js` | the vendor half, evaluated once (again when its hash changes) |
+ * | `/app.js` | the app half, evaluated again on every change: Fast Refresh |
+ *
+ * Rebuilds when the sources change (esbuild's watcher over the app's
+ * inputs), and writes the plain single bundle to `outfile` too, so an app
+ * built from Xcode without the server gets the latest. Returns a function
+ * that stops everything.
+ */
+export async function serve(options: ServeOptions): Promise<() => Promise<void>> {
+  const { buildDev } = await import('./devBuild.js');
+  let vendor = { code: '', hash: '' };
+  let app = { code: '', hash: '' };
+  const rebuild = async (): Promise<void> => {
+    try {
+      const dev = await buildDev({ entry: options.entry, sourcemap: options.sourcemap ?? false });
+      vendor = { code: dev.vendor, hash: hash(dev.vendor) };
+      app = { code: dev.app, hash: hash(dev.app) };
+      const full = await buildApp(options);
+      options.onBuild?.({ ...full, warnings: [...full.warnings, ...dev.warnings] });
+    } catch (error) {
+      options.onBuild?.(error instanceof Error ? error : new Error(String(error)));
+    }
+  };
+  await rebuild();
+
+  // esbuild's watcher over the app build's inputs.
+  const context = await esbuild.context({
+    ...common(options),
+    entryPoints: [options.entry],
+    alias: stubs,
+    plugins: [
+      {
+        name: 'swiftbrowser-native-rebuild',
+        setup(build) {
+          let first = true;
+          build.onEnd(() => {
+            if (first) {
+              first = false;
+              return;
+            }
+            void rebuild();
+          });
+        },
+      },
+    ],
+  });
+  await context.watch();
+
+  const port = options.port ?? 5173;
+  const server = createServer((request, response) => {
+    const url = request.url ?? '/';
+    const send = (body: string, type: string, etag: string): void => {
+      response.setHeader('Content-Type', type);
+      response.setHeader('Cache-Control', 'no-store');
+      response.setHeader('ETag', `"${etag}"`);
+      if (request.headers['if-none-match'] === `"${etag}"`) {
+        response.statusCode = 304;
+        response.end();
+        return;
+      }
+      response.end(request.method === 'HEAD' ? undefined : body);
+    };
+    if (url === '/manifest.json' || url === '/') {
+      send(JSON.stringify({ vendor: vendor.hash, app: app.hash }), 'application/json', `${vendor.hash}-${app.hash}`);
+    } else if (url === '/vendor.js') {
+      send(vendor.code, 'text/javascript; charset=utf-8', vendor.hash);
+    } else if (url === '/app.js') {
+      send(app.code, 'text/javascript; charset=utf-8', app.hash);
+    } else {
+      response.statusCode = 404;
+      response.end('not found');
+    }
+  });
+  await new Promise<void>((resolve) => server.listen(port, resolve));
+
+  return async () => {
+    await context.dispose();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  };
+}
+
+function hash(text: string): string {
+  return createHash('sha1').update(text).digest('hex').slice(0, 12);
+}

package/src/devBuild.ts

@@ -0,0 +1,152 @@
+/**
+ * The dev bundle in two halves, for Fast Refresh (docs/native.md):
+ *
+ * - `vendor.js`: vendor.ts (the runtime, the refresh runtime, React,
+ *   `@swiftbrowser/react`, this package), evaluated once per vendor change.
+ * - `app.js`: the app's own modules, with `react`, `react/jsx-runtime`,
+ *   `@swiftbrowser/react` and `@swiftbrowser/native` resolved to shims that
+ *   read `__sbVendor`, and every module run through `react-refresh/babel`
+ *   so its components register with the refresh runtime. Evaluated again
+ *   on every save; `run` then refreshes the mounted components in place.
+ *
+ * Node only (serve in build.ts uses it).
+ */
+
+import { transformAsync } from '@babel/core';
+import * as esbuild from 'esbuild';
+import { createRequire } from 'node:module';
+import { dirname, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const vendorEntry = fileURLToPath(new URL('../src/vendor.ts', import.meta.url));
+const ownIndex = fileURLToPath(new URL('../src/index.ts', import.meta.url));
+const reactSources = fileURLToPath(new URL('../../react/src/index.ts', import.meta.url));
+
+/** The modules the app half takes from the vendor half. */
+const VENDORED = ['react', 'react/jsx-runtime', 'react/jsx-dev-runtime', '@swiftbrowser/react', '@swiftbrowser/native'];
+
+export interface DevBuildOptions {
+  entry: string;
+  sourcemap?: boolean;
+}
+
+export interface DevBundle {
+  vendor: string;
+  app: string;
+  warnings: string[];
+}
+
+function common(options: DevBuildOptions): esbuild.BuildOptions {
+  return {
+    bundle: true,
+    write: false,
+    format: 'iife',
+    platform: 'browser',
+    target: ['safari16'],
+    sourcemap: options.sourcemap ? 'inline' : false,
+    define: { 'process.env.NODE_ENV': '"development"', 'import.meta.env.DEV': 'true' },
+    jsx: 'automatic',
+    logLevel: 'silent',
+    absWorkingDir: here,
+  };
+}
+
+/** The export names of a module, for a shim with static exports. */
+async function exportNames(name: string): Promise<string[]> {
+  if (name === '@swiftbrowser/native') return names(ownIndex);
+  if (name === '@swiftbrowser/react') return names(reactSources);
+  // CommonJS (React): its exports are enumerable once required.
+  return Object.keys(require(name) as object).filter((key) => key !== 'default' && key !== '__esModule');
+}
+
+/** The export names of an ES module (its sources), from esbuild's metafile. */
+async function names(entry: string): Promise<string[]> {
+  const result = await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    write: false,
+    format: 'esm',
+    metafile: true,
+    platform: 'browser',
+    logLevel: 'silent',
+    absWorkingDir: here,
+    external: ['react', 'react-dom', 'react-dom/client', 'react-reconciler', 'react-reconciler/constants', 'react-refresh/runtime', '@babel/core', 'esbuild', 'node:*'],
+    alias: { '@swiftbrowser/react': reactSources },
+  });
+  return Object.values(result.metafile!.outputs).flatMap((output) => output.exports).filter((key) => key !== 'default');
+}
+
+/** The vendor half: vendor.ts with its dependencies. */
+export async function buildVendor(options: DevBuildOptions): Promise<{ code: string; warnings: string[] }> {
+  const result = await esbuild.build({
+    ...common(options),
+    entryPoints: [vendorEntry],
+    alias: {
+      'react-dom/client': fileURLToPath(new URL('../src/stubs/react-dom-client.ts', import.meta.url)),
+      'react-dom': fileURLToPath(new URL('../src/stubs/react-dom.ts', import.meta.url)),
+      '@swiftbrowser/react': reactSources,
+    },
+  });
+  return { code: result.outputFiles!.map((file) => file.text).join('\n'), warnings: result.warnings.map((w) => w.text) };
+}
+
+/** The app half: the entry's own modules over the vendor shims, with the refresh transform. */
+export async function buildApp(options: DevBuildOptions): Promise<{ code: string; warnings: string[] }> {
+  const shims = new Map<string, string>();
+  for (const name of VENDORED) {
+    const exports = await exportNames(name);
+    shims.set(
+      name,
+      [
+        `const m = globalThis.__sbVendor[${JSON.stringify(name)}];`,
+        `if (!m) throw new Error(${JSON.stringify(`vendor.js was not loaded before app.js (no ${name})`)});`,
+        'export default m.default ?? m;',
+        ...exports.map((key) => `export const ${key} = m[${JSON.stringify(key)}];`),
+      ].join('\n'),
+    );
+  }
+  const refreshPlugin = require.resolve('react-refresh/babel');
+  const result = await esbuild.build({
+    ...common(options),
+    entryPoints: [options.entry],
+    plugins: [
+      {
+        name: 'swiftbrowser-native-dev',
+        setup(build) {
+          const filter = new RegExp(`^(${VENDORED.map((name) => name.replace(/[/]/g, '\\/')).join('|')})$`);
+          build.onResolve({ filter }, (args) => ({ path: args.path, namespace: 'sb-vendor' }));
+          build.onLoad({ filter: /.*/, namespace: 'sb-vendor' }, (args) => ({ contents: shims.get(args.path)!, loader: 'js' }));
+          // The app's own modules: TypeScript and JSX compiled by esbuild, then
+          // the refresh transform, with the registration functions in scope.
+          build.onLoad({ filter: /\.[jt]sx?$/ }, async (args) => {
+            if (args.path.includes('/node_modules/')) return null;
+            const { readFile } = await import('node:fs/promises');
+            const source = await readFile(args.path, 'utf8');
+            const loader = extname(args.path).slice(1) as esbuild.Loader;
+            const compiled = await esbuild.transform(source, { loader, jsx: 'automatic', format: 'esm', sourcefile: args.path, target: 'es2022' });
+            const refreshed = await transformAsync(compiled.code, {
+              filename: args.path,
+              configFile: false,
+              babelrc: false,
+              sourceType: 'module',
+              plugins: [[refreshPlugin, { skipEnvCheck: true }]],
+            });
+            const prelude = [
+              `const $RefreshReg$ = (type, id) => globalThis.__sbRefresh.register(type, ${JSON.stringify(args.path)} + ' ' + id);`,
+              'const $RefreshSig$ = globalThis.__sbRefresh.createSignatureFunctionForTransform;',
+            ].join('\n');
+            return { contents: `${prelude}\n${refreshed?.code ?? compiled.code}`, loader: 'js' };
+          });
+        },
+      },
+    ],
+  });
+  return { code: result.outputFiles!.map((file) => file.text).join('\n'), warnings: result.warnings.map((w) => w.text) };
+}
+
+export async function buildDev(options: DevBuildOptions): Promise<DevBundle> {
+  const [vendor, app] = await Promise.all([buildVendor(options), buildApp(options)]);
+  return { vendor: vendor.code, app: app.code, warnings: [...vendor.warnings, ...app.warnings] };
+}

package/src/encoding.ts

@@ -0,0 +1,130 @@
+/**
+ * UTF-8 and base64, for the globals bare JavaScriptCore lacks (`TextEncoder`,
+ * `TextDecoder`, `atob`, `btoa`) and for the bytes that cross the bridge as
+ * base64 (fetch bodies). No dependencies, so the runtime can carry them.
+ */
+
+export function utf8Encode(text: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const low = text.charCodeAt(i + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        i++;
+      }
+    }
+    if (code < 0x80) out.push(code);
+    else if (code < 0x800) out.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+    else if (code < 0x10000) out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+    else out.push(0xf0 | (code >> 18), 0x80 | ((code >> 12) & 63), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+  }
+  return Uint8Array.from(out);
+}
+
+export function utf8Decode(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; ) {
+    const a = bytes[i]!;
+    let code: number;
+    if (a < 0x80) {
+      code = a;
+      i += 1;
+    } else if ((a & 0xe0) === 0xc0) {
+      code = ((a & 31) << 6) | (bytes[i + 1]! & 63);
+      i += 2;
+    } else if ((a & 0xf0) === 0xe0) {
+      code = ((a & 15) << 12) | ((bytes[i + 1]! & 63) << 6) | (bytes[i + 2]! & 63);
+      i += 3;
+    } else {
+      code = ((a & 7) << 18) | ((bytes[i + 1]! & 63) << 12) | ((bytes[i + 2]! & 63) << 6) | (bytes[i + 3]! & 63);
+      i += 4;
+    }
+    if (Number.isNaN(code)) break;
+    out += String.fromCodePoint(code);
+  }
+  return out;
+}
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_INDEX: Record<string, number> = {};
+for (let i = 0; i < B64.length; i++) B64_INDEX[B64[i]!] = i;
+
+/** Standard base64 (RFC 4648, padded). */
+export function base64Encode(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i]!;
+    const b = i + 1 < bytes.length ? bytes[i + 1]! : 0;
+    const c = i + 2 < bytes.length ? bytes[i + 2]! : 0;
+    const n = (a << 16) | (b << 8) | c;
+    out += B64[(n >> 18) & 63]! + B64[(n >> 12) & 63]!;
+    out += i + 1 < bytes.length ? B64[(n >> 6) & 63]! : '=';
+    out += i + 2 < bytes.length ? B64[n & 63]! : '=';
+  }
+  return out;
+}
+
+export function base64Decode(text: string): Uint8Array {
+  const clean = text.replace(/[^A-Za-z0-9+/]/g, '');
+  const out: number[] = [];
+  for (let i = 0; i < clean.length; i += 4) {
+    const a = B64_INDEX[clean[i]!] ?? 0;
+    const b = B64_INDEX[clean[i + 1]!] ?? 0;
+    const c = i + 2 < clean.length ? B64_INDEX[clean[i + 2]!]! : -1;
+    const d = i + 3 < clean.length ? B64_INDEX[clean[i + 3]!]! : -1;
+    out.push((a << 2) | (b >> 4));
+    if (c >= 0) out.push(((b & 15) << 4) | (c >> 2));
+    if (d >= 0) out.push(((c & 3) << 6) | d);
+  }
+  return Uint8Array.from(out);
+}
+
+/** `TextEncoder` (UTF-8 only), as the runtime installs it. */
+export class SimpleTextEncoder {
+  readonly encoding = 'utf-8';
+  encode(input = ''): Uint8Array {
+    return utf8Encode(String(input));
+  }
+  encodeInto(input: string, destination: Uint8Array): { read: number; written: number } {
+    const bytes = utf8Encode(input);
+    const written = Math.min(bytes.length, destination.length);
+    destination.set(bytes.subarray(0, written));
+    return { read: input.length, written };
+  }
+}
+
+/** `TextDecoder` (UTF-8 only), as the runtime installs it. */
+export class SimpleTextDecoder {
+  readonly encoding: string;
+  readonly fatal = false;
+  readonly ignoreBOM = false;
+  constructor(label = 'utf-8') {
+    this.encoding = label.toLowerCase();
+  }
+  decode(input?: ArrayBuffer | ArrayBufferView | null): string {
+    if (!input) return '';
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    return utf8Decode(bytes);
+  }
+}
+
+/** `btoa`: a binary string (char codes 0...255) to base64. */
+export function btoaPolyfill(binary: string): string {
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    const code = binary.charCodeAt(i);
+    if (code > 255) throw new Error('btoa: the string contains a character outside the Latin1 range');
+    bytes[i] = code;
+  }
+  return base64Encode(bytes);
+}
+
+/** `atob`: base64 to a binary string. */
+export function atobPolyfill(text: string): string {
+  const bytes = base64Decode(text);
+  let out = '';
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+}