@swiftbrowser/native 0.0.0-stage → 0.10.0

package/src/fetch.ts

@@ -0,0 +1,305 @@
+/**
+ * `fetch`, `Headers`, `Request`, `Response` and `AbortController` over the
+ * bridge's `fetch` primitive (`URLSession` on the Swift side). Bodies cross
+ * as base64; a `Response` reads them back as text, JSON or bytes. Streams
+ * and `Blob` are not here: a body is whole.
+ */
+
+import type { NativeBridge, NativeFetchResult } from './bridge';
+import { base64Decode, base64Encode, utf8Decode, utf8Encode } from './encoding';
+
+type HeadersInitLike = SimpleHeaders | Record<string, string> | [string, string][];
+
+export class SimpleHeaders {
+  private map = new Map<string, string>();
+
+  constructor(init?: HeadersInitLike) {
+    if (init instanceof SimpleHeaders) {
+      for (const [k, v] of init) this.map.set(k, v);
+    } else if (Array.isArray(init)) {
+      for (const [k, v] of init) this.append(k, v);
+    } else if (init) {
+      for (const [k, v] of Object.entries(init)) this.set(k, v);
+    }
+  }
+  append(name: string, value: string): void {
+    const key = name.toLowerCase();
+    const current = this.map.get(key);
+    this.map.set(key, current === undefined ? String(value) : `${current}, ${value}`);
+  }
+  delete(name: string): void {
+    this.map.delete(name.toLowerCase());
+  }
+  get(name: string): string | null {
+    return this.map.get(name.toLowerCase()) ?? null;
+  }
+  has(name: string): boolean {
+    return this.map.has(name.toLowerCase());
+  }
+  set(name: string, value: string): void {
+    this.map.set(name.toLowerCase(), String(value));
+  }
+  forEach(callback: (value: string, key: string, parent: SimpleHeaders) => void): void {
+    for (const [k, v] of this.map) callback(v, k, this);
+  }
+  keys(): IterableIterator<string> {
+    return this.map.keys();
+  }
+  values(): IterableIterator<string> {
+    return this.map.values();
+  }
+  entries(): IterableIterator<[string, string]> {
+    return this.map.entries();
+  }
+  [Symbol.iterator](): IterableIterator<[string, string]> {
+    return this.map.entries();
+  }
+  /** The headers as a plain object, for the bridge. */
+  toObject(): Record<string, string> {
+    return Object.fromEntries(this.map);
+  }
+}
+
+export class SimpleAbortSignal {
+  aborted = false;
+  reason: unknown = undefined;
+  onabort: ((event: { type: 'abort' }) => void) | null = null;
+  private listeners = new Set<(event: { type: 'abort' }) => void>();
+
+  addEventListener(type: string, listener: (event: { type: 'abort' }) => void): void {
+    if (type === 'abort') this.listeners.add(listener);
+  }
+  removeEventListener(type: string, listener: (event: { type: 'abort' }) => void): void {
+    if (type === 'abort') this.listeners.delete(listener);
+  }
+  throwIfAborted(): void {
+    if (this.aborted) throw this.reason;
+  }
+  /** @internal */
+  _abort(reason: unknown): void {
+    if (this.aborted) return;
+    this.aborted = true;
+    this.reason = reason;
+    const event = { type: 'abort' as const };
+    this.onabort?.(event);
+    for (const listener of this.listeners) listener(event);
+  }
+  static abort(reason?: unknown): SimpleAbortSignal {
+    const signal = new SimpleAbortSignal();
+    signal._abort(reason ?? abortError());
+    return signal;
+  }
+  static timeout(ms: number): SimpleAbortSignal {
+    const signal = new SimpleAbortSignal();
+    setTimeout(() => signal._abort(timeoutError()), ms);
+    return signal;
+  }
+}
+
+export class SimpleAbortController {
+  readonly signal = new SimpleAbortSignal();
+  abort(reason?: unknown): void {
+    this.signal._abort(reason ?? abortError());
+  }
+}
+
+function abortError(): Error {
+  const error = new Error('The operation was aborted.');
+  error.name = 'AbortError';
+  return error;
+}
+function timeoutError(): Error {
+  const error = new Error('The operation timed out.');
+  error.name = 'TimeoutError';
+  return error;
+}
+
+type BodyInitLike = string | ArrayBuffer | ArrayBufferView | SimpleURLSearchParamsLike | null | undefined;
+interface SimpleURLSearchParamsLike {
+  toString(): string;
+  [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+
+/** Bytes of a body, and the content type it implies when the caller set none. */
+function encodeBody(body: BodyInitLike): { bytes: Uint8Array | null; contentType: string | null } {
+  if (body === null || body === undefined) return { bytes: null, contentType: null };
+  if (typeof body === 'string') return { bytes: utf8Encode(body), contentType: 'text/plain;charset=UTF-8' };
+  if (body instanceof ArrayBuffer) return { bytes: new Uint8Array(body), contentType: null };
+  if (ArrayBuffer.isView(body)) return { bytes: new Uint8Array(body.buffer, body.byteOffset, body.byteLength), contentType: null };
+  if (typeof body === 'object' && Symbol.iterator in body && typeof body.toString === 'function') {
+    return { bytes: utf8Encode(body.toString()), contentType: 'application/x-www-form-urlencoded;charset=UTF-8' };
+  }
+  return { bytes: utf8Encode(String(body)), contentType: 'text/plain;charset=UTF-8' };
+}
+
+class Body {
+  protected bytes: Uint8Array | null;
+  bodyUsed = false;
+  constructor(bytes: Uint8Array | null) {
+    this.bytes = bytes;
+  }
+  get body(): null {
+    // No streams; read the body whole with the methods below.
+    return null;
+  }
+  private take(): Uint8Array {
+    if (this.bodyUsed) throw new TypeError('body used already');
+    this.bodyUsed = true;
+    return this.bytes ?? new Uint8Array(0);
+  }
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    const bytes = this.take();
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  }
+  async bytesArray(): Promise<Uint8Array> {
+    return this.take();
+  }
+  async text(): Promise<string> {
+    return utf8Decode(this.take());
+  }
+  async json(): Promise<unknown> {
+    return JSON.parse(utf8Decode(this.take()));
+  }
+}
+
+export interface RequestInitLike {
+  method?: string;
+  headers?: HeadersInitLike;
+  body?: BodyInitLike;
+  signal?: SimpleAbortSignal | null;
+  [key: string]: unknown;
+}
+
+export class SimpleRequest extends Body {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: SimpleHeaders;
+  readonly signal: SimpleAbortSignal;
+
+  constructor(input: string | SimpleRequest | { href: string }, init: RequestInitLike = {}) {
+    const base = input instanceof SimpleRequest ? input : null;
+    const { bytes, contentType } = encodeBody(init.body);
+    super(bytes ?? base?.rawBytes() ?? null);
+    this.url = typeof input === 'string' ? input : input instanceof SimpleRequest ? input.url : input.href;
+    this.method = (init.method ?? base?.method ?? 'GET').toUpperCase();
+    this.headers = new SimpleHeaders(init.headers ?? base?.headers);
+    if (contentType && !this.headers.has('content-type')) this.headers.set('content-type', contentType);
+    this.signal = init.signal ?? base?.signal ?? new SimpleAbortSignal();
+  }
+  /** @internal */
+  rawBytes(): Uint8Array | null {
+    return this.bytes;
+  }
+  clone(): SimpleRequest {
+    return new SimpleRequest(this, { body: this.bytes });
+  }
+}
+
+export interface ResponseInitLike {
+  status?: number;
+  statusText?: string;
+  headers?: HeadersInitLike;
+  url?: string;
+}
+
+export class SimpleResponse extends Body {
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: SimpleHeaders;
+  readonly url: string;
+  readonly type = 'basic';
+  readonly redirected = false;
+
+  constructor(body: BodyInitLike = null, init: ResponseInitLike = {}) {
+    const { bytes, contentType } = encodeBody(body);
+    super(bytes);
+    this.status = init.status ?? 200;
+    this.statusText = init.statusText ?? '';
+    this.headers = new SimpleHeaders(init.headers);
+    if (contentType && !this.headers.has('content-type')) this.headers.set('content-type', contentType);
+    this.url = init.url ?? '';
+  }
+  get ok(): boolean {
+    return this.status >= 200 && this.status < 300;
+  }
+  clone(): SimpleResponse {
+    return new SimpleResponse(this.bytes, { status: this.status, statusText: this.statusText, headers: this.headers, url: this.url });
+  }
+  static json(data: unknown, init: ResponseInitLike = {}): SimpleResponse {
+    const response = new SimpleResponse(JSON.stringify(data), init);
+    response.headers.set('content-type', 'application/json');
+    return response;
+  }
+  static error(): SimpleResponse {
+    return new SimpleResponse(null, { status: 0 });
+  }
+}
+
+export interface FetchGlobals {
+  fetch: (input: string | SimpleRequest | { href: string }, init?: RequestInitLike) => Promise<SimpleResponse>;
+  Headers: typeof SimpleHeaders;
+  Request: typeof SimpleRequest;
+  Response: typeof SimpleResponse;
+  AbortController: typeof SimpleAbortController;
+  AbortSignal: typeof SimpleAbortSignal;
+  /** The bridge's answer; Swift calls it as `__sbFetchResult(id, result)`. */
+  __sbFetchResult: (id: number, result: NativeFetchResult | string) => void;
+}
+
+/** The fetch globals over the bridge. */
+export function createFetch(native: Pick<NativeBridge, 'fetch'>): FetchGlobals {
+  let nextId = 1;
+  const pending = new Map<number, { resolve: (response: SimpleResponse) => void; reject: (error: unknown) => void }>();
+
+  const fetch: FetchGlobals['fetch'] = (input, init = {}) => {
+    const request = new SimpleRequest(input, init);
+    return new Promise<SimpleResponse>((resolve, reject) => {
+      if (request.signal.aborted) {
+        reject(request.signal.reason);
+        return;
+      }
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      request.signal.addEventListener('abort', () => {
+        if (pending.delete(id)) reject(request.signal.reason);
+      });
+      const bytes = request.rawBytes();
+      native.fetch(id, {
+        url: request.url,
+        method: request.method,
+        headers: request.headers.toObject(),
+        body: bytes ? base64Encode(bytes) : null,
+      });
+    });
+  };
+
+  const __sbFetchResult: FetchGlobals['__sbFetchResult'] = (id, raw) => {
+    const waiting = pending.get(id);
+    if (!waiting) return;
+    pending.delete(id);
+    const result: NativeFetchResult = typeof raw === 'string' ? (JSON.parse(raw) as NativeFetchResult) : raw;
+    if (result.error !== undefined) {
+      const error = new TypeError(`fetch failed: ${result.error}`);
+      waiting.reject(error);
+      return;
+    }
+    waiting.resolve(
+      new SimpleResponse(result.body ? base64Decode(result.body) : null, {
+        status: result.status ?? 200,
+        statusText: result.statusText ?? '',
+        headers: result.headers ?? {},
+        url: result.url ?? '',
+      }),
+    );
+  };
+
+  return {
+    fetch,
+    Headers: SimpleHeaders,
+    Request: SimpleRequest,
+    Response: SimpleResponse,
+    AbortController: SimpleAbortController,
+    AbortSignal: SimpleAbortSignal,
+    __sbFetchResult,
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @swiftbrowser/native: a @swiftbrowser/react app running in JavaScriptCore
+ * inside an iOS app, drawn by real SwiftUI (docs/native.md).
+ *
+ * ```tsx
+ * import { run } from '@swiftbrowser/native';
+ * run(<App />);
+ * ```
+ *
+ * The bundle `swiftbrowser-native build` writes starts with the runtime
+ * (./runtime), so the web globals are there before React loads.
+ */
+
+export { run, type RunOptions, type Running } from './run';
+export { Native, type NativeProps } from './native';
+export { installRuntime, type InstallOptions } from './runtime';
+export { nativeBridge, launchArguments, type NativeBridge, type NativeFetchRequest, type NativeFetchResult } from './bridge';
+export { SimpleHeaders, SimpleRequest, SimpleResponse, SimpleAbortController, SimpleAbortSignal, createFetch } from './fetch';
+export { SimpleURL, SimpleURLSearchParams } from './url';
+export { SimpleTextEncoder, SimpleTextDecoder, base64Encode, base64Decode, utf8Encode, utf8Decode } from './encoding';

package/src/native.ts

@@ -0,0 +1,35 @@
+/**
+ * `<Native name props onEvent>`: the escape hatch (docs/native.md). The
+ * element kind `native`, which only this producer emits, names a SwiftUI view
+ * the app registered with `NativeRegistry.register(name)`; `props` reach it
+ * as JSON, its children as SwiftUI views, and what it sends back arrives at
+ * `onEvent`.
+ */
+
+import { createElement, type ReactElement, type ReactNode } from 'react';
+
+export interface NativeProps {
+  /** The name registered on the Swift side. */
+  name: string;
+  /** JSON-serializable props for the view. */
+  props?: Record<string, unknown>;
+  /** A value the native view sent (`context.send(value)`). */
+  onEvent?: (value: unknown) => void;
+  children?: ReactNode;
+}
+
+/** The shape of a `native` event (`RendererEvent` has no such member). */
+interface NativeEvent {
+  type: 'native';
+  id: number;
+  name: string;
+  value: unknown;
+}
+
+export function Native({ name, props, onEvent, children }: NativeProps): ReactElement {
+  // The host element of @swiftbrowser/react: `sb` with the protocol kind and
+  // props, and the handlers by event type (packages/react/src/host/instance.ts).
+  const hostProps: Record<string, unknown> = { kind: 'native', props: { name, props: props ?? {} } };
+  if (onEvent) hostProps['on'] = { native: (event: NativeEvent) => onEvent(event.value) };
+  return children === undefined ? createElement('sb', hostProps) : createElement('sb', hostProps, children);
+}

package/src/refresh.ts

@@ -0,0 +1,29 @@
+/**
+ * React Fast Refresh for the dev loop (docs/native.md, "Development loop").
+ * The refresh runtime must install its hook before React's reconciler loads,
+ * so the vendor bundle imports this module first. The app bundle's modules,
+ * transformed by `react-refresh/babel` (devBuild.ts), register their
+ * components through `__sbRefresh`; `run` performs the refresh when the app
+ * bundle is evaluated again.
+ */
+
+import RefreshRuntime from 'react-refresh/runtime';
+
+export interface RefreshGlobal {
+  register: (type: unknown, id: string) => void;
+  createSignatureFunctionForTransform: typeof RefreshRuntime.createSignatureFunctionForTransform;
+  /** Applies the registered updates to the mounted roots; true when something was refreshed. */
+  perform: () => boolean;
+}
+
+RefreshRuntime.injectIntoGlobalHook(globalThis as unknown as Window);
+
+const refresh: RefreshGlobal = {
+  register: (type, id) => RefreshRuntime.register(type, id),
+  createSignatureFunctionForTransform: RefreshRuntime.createSignatureFunctionForTransform,
+  perform: () => RefreshRuntime.performReactRefresh() !== null,
+};
+
+(globalThis as unknown as { __sbRefresh: RefreshGlobal }).__sbRefresh = refresh;
+
+export { refresh };

package/src/run.ts

@@ -0,0 +1,98 @@
+/**
+ * `run(element)`: a `@swiftbrowser/react` root whose ops go to the native
+ * renderer over the bridge, and whose events come back from it. The native
+ * counterpart of `mount` in @swiftbrowser/react, without the DOM.
+ *
+ * The bridge is synchronous both ways: `__sbApplyOps` returns when the tree
+ * has the pass, and Swift's `__sbDispatch(json)` returns when the handler
+ * ran and its pass was applied (docs/native.md, "Synchronous calls").
+ */
+
+import { createSwiftUIRoot, type SwiftUIRoot } from '@swiftbrowser/react';
+import type { Op, RendererEvent } from '@swiftbrowser/web/src/protocol';
+import type { ReactNode } from 'react';
+import { nativeBridge, type NativeBridge } from './bridge';
+
+export interface RunOptions {
+  /** The bridge to render through; the global `__sbNative` by default. */
+  native?: NativeBridge;
+  /** Called with an error applying ops threw on the native side, or a handler threw. */
+  onError?: (error: unknown) => void;
+}
+
+export interface Running {
+  root: SwiftUIRoot;
+  /** Deliver an event as the native side does (tests). */
+  dispatch(event: RendererEvent | string): void;
+  unmount(): void;
+}
+
+/** The environment fields the native side sends; the rest of the event is ignored. */
+interface EnvironmentFields {
+  colorScheme?: 'light' | 'dark';
+  dynamicTypeSize?: string;
+  horizontalSizeClass?: 'compact' | 'regular';
+}
+
+/** The running app, when `run` was called (the dev loop calls it again on every save). */
+let current: Running | null = null;
+
+export function run(element: ReactNode, options: RunOptions = {}): Running {
+  const native = options.native ?? nativeBridge();
+  if (!native) throw new Error('run(): no native bridge (__sbNative); this entry runs inside a SwiftBrowser Native app');
+  const report = options.onError ?? ((error: unknown) => native.log('error', error instanceof Error ? (error.stack ?? error.message) : String(error)));
+
+  if (current) {
+    // Fast Refresh (devBuild.ts): the app bundle was evaluated again. Its
+    // modules re-registered their components; the refresh runtime updates
+    // the mounted ones in place (state kept where the hooks are unchanged),
+    // and the new tree renders into the same root.
+    const refresh = (globalThis as unknown as { __sbRefresh?: { perform: () => boolean } }).__sbRefresh;
+    try {
+      refresh?.perform();
+      current.root.render(element);
+    } catch (error) {
+      report(error);
+    }
+    return current;
+  }
+
+  const root = createSwiftUIRoot((ops: Op[]) => {
+    const failure = native.applyOps(JSON.stringify(ops));
+    if (failure) report(new Error(`applyOps: ${failure}`));
+  });
+
+  const dispatch = (event: RendererEvent | string): void => {
+    const parsed = typeof event === 'string' ? (JSON.parse(event) as RendererEvent) : event;
+    try {
+      if (parsed.type === 'environment') {
+        const fields = parsed as EnvironmentFields;
+        const next: Partial<{ colorScheme: 'light' | 'dark'; dynamicTypeSize: never; horizontalSizeClass: 'compact' | 'regular' }> = {};
+        if (fields.colorScheme) next.colorScheme = fields.colorScheme;
+        if (fields.dynamicTypeSize) (next as Record<string, unknown>)['dynamicTypeSize'] = fields.dynamicTypeSize;
+        if (fields.horizontalSizeClass) next.horizontalSizeClass = fields.horizontalSizeClass;
+        if (Object.keys(next).length > 0) root.setEnvironment(next);
+        return;
+      }
+      root.dispatch(parsed);
+    } catch (error) {
+      report(error);
+    }
+  };
+
+  const g = globalThis as unknown as Record<string, unknown>;
+  g['__sbDispatch'] = (json: string) => dispatch(json);
+
+  root.render(element);
+
+  current = {
+    root,
+    dispatch,
+    unmount() {
+      root.unmount();
+      if (g['__sbDispatch']) delete g['__sbDispatch'];
+      current = null;
+    },
+  };
+  return current;
+}