@swiftbrowser/web 0.1.0

package/plugins/bundle-resources.ts

@@ -0,0 +1,195 @@
+/**
+ * The app's resource files (the Xcode target's Copy Bundle Resources phase,
+ * or `resources` in swiftbrowser.json) as one manifest at `/bundle/<App>.json`
+ * (`{ files: [{ path, size }] }`) plus the files at `/bundle/<App>/<path>`,
+ * dev server and `vite build` alike. The page fetches them before loading the
+ * module and mounts them at `/bundle` in the WASI filesystem, where the shim's
+ * `Bundle.main` finds them (docs/ops-protocol.md, "Phase 11").
+ *
+ * A resource entry that is a file is published under its base name, like
+ * Xcode copies it; a directory keeps its name and structure (a folder
+ * reference). Asset catalogs are not resources here: plugins/asset-catalogs.ts
+ * turns them into the catalog manifest.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { Plugin } from 'vite';
+import type { AppSpec } from '../node/apps.js';
+
+export const BUNDLE_DIR = 'bundle';
+
+export interface BundleFile {
+  /** Path inside the bundle, `/`-separated (`missions.json`, `Data/notes.txt`). */
+  path: string;
+  size: number;
+}
+
+export interface BundleManifest {
+  files: BundleFile[];
+}
+
+/** The fields of an {@link AppSpec} this plugin reads. */
+export type BundleSpec = Pick<AppSpec, 'name' | 'resources'>;
+
+export interface BuiltBundle {
+  manifest: BundleManifest;
+  /** Published path (`bundle/App/missions.json`) → source file on disk. */
+  files: Map<string, string>;
+  warnings: string[];
+}
+
+const PUBLISHED = /^[A-Za-z0-9_.\-]+$/;
+
+/** URL path of an app's bundle manifest. */
+export function bundleManifestPath(app: string): string {
+  return `/${BUNDLE_DIR}/${app}.json`;
+}
+
+/** URL path of a file inside an app's bundle. */
+export function bundleFilePath(app: string, file: string): string {
+  return `/${BUNDLE_DIR}/${app}/${file.split('/').map(encodeURIComponent).join('/')}`;
+}
+
+function walk(dir: string, prefix: string, into: (relative: string, file: string) => void): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) walk(full, relative, into);
+    else if (entry.isFile()) into(relative, full);
+  }
+}
+
+/** Lists the resources of a spec as published paths and sources. */
+export function buildBundle(app: string, resources: readonly string[] | undefined): BuiltBundle {
+  const files = new Map<string, string>();
+  const manifest: BundleManifest = { files: [] };
+  const warnings: string[] = [];
+  const add = (relative: string, source: string): void => {
+    if (!relative.split('/').every((part) => PUBLISHED.test(part))) {
+      warnings.push(`${relative}: resource names may use letters, digits, ".", "_" and "-" only; skipped`);
+      return;
+    }
+    if (manifest.files.some((f) => f.path === relative)) {
+      warnings.push(`${relative}: two resources publish under the same name; the first one wins`);
+      return;
+    }
+    manifest.files.push({ path: relative, size: statSync(source).size });
+    files.set(`${BUNDLE_DIR}/${app}/${relative}`, source);
+  };
+  for (const resource of resources ?? []) {
+    if (!existsSync(resource)) {
+      warnings.push(`${resource}: not found`);
+      continue;
+    }
+    if (statSync(resource).isDirectory()) walk(resource, path.basename(resource), add);
+    else add(path.basename(resource), resource);
+  }
+  return { manifest, files, warnings };
+}
+
+export function bundleManifestJson(manifest: BundleManifest): string {
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
+/** The app named by a manifest request URL (`/bundle/<App>.json`), or null. */
+export function bundleRequestApp(url: string): string | null {
+  const match = new RegExp(`^/${BUNDLE_DIR}/([A-Za-z0-9_-]+)\\.json(?:\\?|$)`).exec(url);
+  return match?.[1] ?? null;
+}
+
+/** The app and published path of a resource request (`/bundle/<App>/<path>`), or null. */
+export function bundleRequestFile(url: string): { app: string; fileName: string } | null {
+  const match = new RegExp(`^/${BUNDLE_DIR}/([A-Za-z0-9_-]+)/([^?]+)(?:\\?|$)`).exec(url);
+  if (!match?.[1] || !match[2]) return null;
+  let relative: string;
+  try {
+    relative = match[2].split('/').map(decodeURIComponent).join('/');
+  } catch {
+    return null;
+  }
+  if (!relative.split('/').every((part) => PUBLISHED.test(part) && part !== '.' && part !== '..')) return null;
+  return { app: match[1], fileName: `${BUNDLE_DIR}/${match[1]}/${relative}` };
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.json': 'application/json',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+  '.xml': 'application/xml',
+  '.plist': 'application/xml',
+  '.strings': 'text/plain; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+};
+
+export function bundleContentType(file: string): string {
+  return CONTENT_TYPES[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+}
+
+export function bundleResources(specs: readonly BundleSpec[]): Plugin {
+  const byName = new Map(specs.map((spec) => [spec.name, spec]));
+  return {
+    name: 'swiftbrowser:bundle-resources',
+    configureServer(server) {
+      const warned = new Set<string>();
+      const build = (spec: BundleSpec): BuiltBundle => {
+        const built = buildBundle(spec.name, spec.resources);
+        for (const warning of built.warnings) {
+          if (warned.has(warning)) continue;
+          warned.add(warning);
+          server.config.logger.warn(`[bundle-resources] ${spec.name}: ${warning}`, { timestamp: true });
+        }
+        return built;
+      };
+      server.middlewares.use((req, res, next) => {
+        const url = req.url ?? '';
+        const app = bundleRequestApp(url);
+        if (app !== null) {
+          const spec = byName.get(app);
+          if (!spec) {
+            res.statusCode = 404;
+            res.end();
+            return;
+          }
+          res.setHeader('Content-Type', 'application/json');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(bundleManifestJson(build(spec).manifest));
+          return;
+        }
+        const file = bundleRequestFile(url);
+        if (file === null) return next();
+        const spec = byName.get(file.app);
+        const source = spec ? build(spec).files.get(file.fileName) : undefined;
+        if (!source) {
+          res.statusCode = 404;
+          res.end();
+          return;
+        }
+        res.setHeader('Content-Type', bundleContentType(source));
+        res.setHeader('Cache-Control', 'no-cache');
+        res.end(readFileSync(source));
+      });
+    },
+    generateBundle() {
+      for (const spec of specs) {
+        const built = buildBundle(spec.name, spec.resources);
+        for (const warning of built.warnings) this.warn(`${spec.name}: ${warning}`);
+        this.emitFile({ type: 'asset', fileName: `${BUNDLE_DIR}/${spec.name}.json`, source: bundleManifestJson(built.manifest) });
+        for (const [fileName, source] of built.files) {
+          this.emitFile({ type: 'asset', fileName, source: readFileSync(source) });
+        }
+      }
+    },
+  };
+}

package/plugins/swift-wasm.ts

@@ -0,0 +1,259 @@
+/**
+ * Vite plugin for the registered apps' Wasm modules.
+ *
+ * Dev server:
+ * - Serves `/<name>.wasm` from each spec's `wasm` file (`application/wasm`,
+ *   never cached). When the file is missing, or its sources changed since the
+ *   server started, and the spec has a `build`, the request builds it first.
+ * - Watches every spec's `watch` directories through the dev server's own
+ *   chokidar watcher, debounces changes (300ms) and runs `spec.build()` for
+ *   every app whose sources changed among those the page has requested since
+ *   the server started (`/<name>.wasm` requests register an app). Builds run
+ *   one at a time.
+ * - Sends `sb:build-start` / `sb:build-end` websocket events so the page can
+ *   show a "Rebuilding…" indicator, then a `full-reload` on success or an
+ *   `sb:build-error` with the compiler output on failure. The page stashes the
+ *   app's `@State` snapshot before the reload and feeds it back through the
+ *   `SB_STATE` WASI environment variable (see src/main.ts).
+ *
+ * `vite build`: copies each spec's `wasm` into the output directory as
+ * `<name>.wasm` (building it first when it is missing and the spec can), so
+ * nothing has to ride along in `public/`. Files that are there anyway are
+ * still copied by Vite as before.
+ */
+
+import { copyFileSync, createReadStream, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
+import type { AppSpec } from '../node/apps.js';
+import type { BuildEndPayload, BuildErrorPayload, BuildStartPayload } from '../src/devEvents.js';
+
+export interface SwiftWasmOptions {
+  /** Debounce window for bursts of file changes, in ms. */
+  debounceMs?: number;
+}
+
+/** The app named by a module request URL (`/<name>.wasm`), or null. */
+export function wasmRequestApp(url: string): string | null {
+  const match = /^\/([A-Za-z0-9_-]+)\.wasm(?:\?|$)/.exec(url);
+  return match?.[1] ?? null;
+}
+
+interface BatchResult {
+  ok: boolean;
+  /** The failed app and its compiler output, when `ok` is false. */
+  failure?: { app: string; output: string };
+}
+
+/** The message of a rejected `build()`: the compiler output. */
+function failureOutput(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export function swiftWasm(specs: readonly AppSpec[], options: SwiftWasmOptions = {}): Plugin {
+  const debounceMs = options.debounceMs ?? 300;
+  const byName = new Map(specs.map((spec) => [spec.name, spec]));
+
+  let config: ResolvedConfig | undefined;
+  let server: ViteDevServer | undefined;
+
+  const log = (message: string): void => {
+    config?.logger.info(`[swift-wasm] ${message}`, { timestamp: true });
+  };
+
+  // -------------------------------------------------------------------------
+  // Dev server: build queue
+  // -------------------------------------------------------------------------
+
+  /** Apps requested since the server started; their sources trigger rebuilds. */
+  const tracked = new Set<string>();
+  /** Tracked apps whose sources changed since their last build. */
+  const dirty = new Set<string>();
+  /** Untracked apps whose sources changed: rebuilt before the first request serves them. */
+  const stale = new Set<string>();
+  /** The build in flight or queued for an app, so a request can wait for it instead of starting another. */
+  const queued = new Map<string, Promise<BatchResult>>();
+  /** Builds run one at a time (SwiftPM shares one `.build` directory). */
+  let queue: Promise<unknown> = Promise.resolve();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const runBatch = async (targets: string[]): Promise<BatchResult> => {
+    const started = Date.now();
+    log(`building ${targets.join(', ')}…`);
+    server?.ws.send('sb:build-start', { apps: targets } satisfies BuildStartPayload);
+    const result: BatchResult = { ok: true };
+    for (const app of targets) {
+      const spec = byName.get(app);
+      if (!spec?.build) continue;
+      try {
+        await spec.build();
+      } catch (error) {
+        const output = failureOutput(error);
+        result.ok = false;
+        result.failure = { app, output };
+        log(`build failed for ${app}`);
+        for (const line of output.split('\n')) if (line.trim()) log(`  ${line}`);
+        server?.ws.send('sb:build-error', { app, output } satisfies BuildErrorPayload);
+        break;
+      }
+    }
+    const durationMs = Date.now() - started;
+    server?.ws.send('sb:build-end', { apps: targets, ok: result.ok, durationMs } satisfies BuildEndPayload);
+    if (result.ok) {
+      log(`built ${targets.join(', ')} in ${(durationMs / 1000).toFixed(1)}s; reloading`);
+      server?.ws.send({ type: 'full-reload', path: '*' });
+    }
+    return result;
+  };
+
+  const enqueue = (targets: string[]): Promise<BatchResult> => {
+    const batch = queue.then(() => runBatch(targets));
+    queue = batch.catch(() => undefined);
+    for (const app of targets) {
+      queued.set(app, batch);
+      void batch.finally(() => {
+        if (queued.get(app) === batch) queued.delete(app);
+      });
+    }
+    return batch;
+  };
+
+  /** Waits for the build of `app` if one is queued, else queues one. */
+  const ensureBuilt = (app: string): Promise<BatchResult> => queued.get(app) ?? enqueue([app]);
+
+  const flushDirty = (): void => {
+    const targets = Array.from(dirty).filter((app) => !queued.has(app));
+    dirty.clear();
+    if (targets.length === 0) return;
+    void enqueue(targets);
+  };
+
+  const schedule = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      flushDirty();
+    }, debounceMs);
+  };
+
+  // -------------------------------------------------------------------------
+  // Dev server: serving `/<name>.wasm`
+  // -------------------------------------------------------------------------
+
+  const serveWasm = async (
+    spec: AppSpec,
+    res: import('node:http').ServerResponse,
+    method: string | undefined,
+  ): Promise<void> => {
+    if (spec.build && (!existsSync(spec.wasm) || stale.has(spec.name))) {
+      if (!existsSync(spec.wasm)) log(`${spec.name}: ${path.basename(spec.wasm)} is missing; building it first`);
+      stale.delete(spec.name);
+      const result = await ensureBuilt(spec.name);
+      if (!result.ok && !existsSync(spec.wasm)) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.end(`Build failed for ${spec.name}:\n${result.failure?.output ?? ''}`);
+        return;
+      }
+    }
+    if (!existsSync(spec.wasm)) {
+      res.statusCode = 404;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end(`${spec.name}: ${spec.wasm} does not exist`);
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'application/wasm');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Content-Length', String(statSync(spec.wasm).size));
+    if (method === 'HEAD') {
+      res.end();
+      return;
+    }
+    createReadStream(spec.wasm).pipe(res);
+  };
+
+  // -------------------------------------------------------------------------
+  // `vite build`: copy the modules into the bundle
+  // -------------------------------------------------------------------------
+
+  const copyModules = async (outDir: string): Promise<void> => {
+    for (const spec of specs) {
+      if (!existsSync(spec.wasm) && spec.build) {
+        log(`${spec.name}: ${spec.wasm} is missing; building it`);
+        await spec.build();
+      }
+      if (!existsSync(spec.wasm)) {
+        if (spec.build) throw new Error(`[swift-wasm] ${spec.name}: ${spec.wasm} still does not exist after building it`);
+        config?.logger.warn(`[swift-wasm] ${spec.name}: ${spec.wasm} does not exist; the site has no module for it`);
+        continue;
+      }
+      mkdirSync(outDir, { recursive: true });
+      const dest = path.join(outDir, `${spec.name}.wasm`);
+      if (path.resolve(spec.wasm) !== path.resolve(dest)) copyFileSync(spec.wasm, dest);
+    }
+    // Modules of apps outside the registry (the examples' `public/*.wasm`,
+    // copied with the public dir) are not part of this site.
+    const known = new Set(specs.map((spec) => `${spec.name}.wasm`));
+    for (const entry of readdirSync(outDir)) {
+      if (entry.endsWith('.wasm') && !known.has(entry)) rmSync(path.join(outDir, entry), { force: true });
+    }
+  };
+
+  return {
+    name: 'swiftbrowser:swift-wasm',
+    configResolved(resolved) {
+      config = resolved;
+    },
+    configureServer(devServer) {
+      server = devServer;
+      const watched = specs.flatMap((spec) =>
+        (spec.watch ?? []).map((dir) => ({ app: spec.name, root: path.resolve(dir) })),
+      );
+      const appsOf = (file: string): string[] =>
+        file.endsWith('.swift')
+          ? watched.filter(({ root }) => file.startsWith(root + path.sep)).map(({ app }) => app)
+          : [];
+
+      devServer.middlewares.use((req, res, next) => {
+        const name = wasmRequestApp(req.url ?? '');
+        const spec = name === null ? undefined : byName.get(name);
+        // Unknown names fall through to Vite (a stray file in `public/`, or a 404).
+        if (!spec) return next();
+        if (!tracked.has(spec.name)) {
+          tracked.add(spec.name);
+          log(`tracking ${spec.name} for rebuilds`);
+        }
+        serveWasm(spec, res, req.method).catch((error: unknown) => {
+          config?.logger.error(`[swift-wasm] ${spec.name}: ${failureOutput(error)}`);
+          if (!res.headersSent) res.statusCode = 500;
+          res.end();
+        });
+      });
+
+      const roots = Array.from(new Set(watched.map(({ root }) => root))).filter((root) => existsSync(root));
+      if (roots.length > 0) devServer.watcher.add(roots);
+      devServer.watcher.on('all', (event, file) => {
+        if (event === 'addDir' || event === 'unlinkDir') return;
+        const apps = appsOf(file);
+        if (apps.length === 0) return;
+        log(`${event} ${file}`);
+        for (const app of new Set(apps)) {
+          if (!byName.get(app)?.build) continue;
+          if (tracked.has(app)) dirty.add(app);
+          else stale.add(app);
+        }
+        if (dirty.size > 0) schedule();
+      });
+      if (roots.length > 0) {
+        log(`watching ${roots.join(', ')} for .swift changes (apps: ${specs.map((spec) => spec.name).join(', ')})`);
+      }
+    },
+    async writeBundle(outputOptions) {
+      if (!config) return;
+      const outDir = outputOptions.dir ?? path.resolve(config.root, config.build.outDir);
+      await copyModules(outDir);
+    },
+  };
+}

package/public/_headers

@@ -0,0 +1,23 @@
+# Cloudflare Pages headers (https://developers.cloudflare.com/pages/configuration/headers/)
+
+# The Wasm modules are not content-hashed: always revalidate them.
+/*.wasm
+  Cache-Control: no-cache
+  Content-Type: application/wasm
+
+# Vite's hashed bundles can be cached forever.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Web app manifests (one per example, see plugins/app-manifests.ts).
+/manifest.webmanifest
+  Content-Type: application/manifest+json
+  Cache-Control: no-cache
+/manifests/*
+  Content-Type: application/manifest+json
+  Cache-Control: no-cache
+
+# Asset catalog manifests and files (one directory per example, see
+# plugins/asset-catalogs.ts). Not content-hashed: always revalidate.
+/catalog/*
+  Cache-Control: no-cache

package/public/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="180" height="180">
+  <!-- SwiftBrowser: a phone outline on the iOS accent blue. The same picture is
+       drawn as apple-touch-icon.png (iOS masks the corners itself). -->
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#2f9bff"/>
+      <stop offset="1" stop-color="#0060df"/>
+    </linearGradient>
+  </defs>
+  <rect width="180" height="180" fill="url(#bg)"/>
+  <rect x="55" y="30" width="70" height="120" rx="14" ry="14" fill="none" stroke="#ffffff" stroke-width="8"/>
+  <rect x="76" y="42" width="28" height="6" rx="3" ry="3" fill="#ffffff"/>
+  <circle cx="90" cy="92" r="16" fill="#ffffff"/>
+</svg>

package/public/manifest.webmanifest

@@ -0,0 +1,14 @@
+{
+  "name": "SwiftBrowser",
+  "short_name": "SwiftBrowser",
+  "description": "SwiftUI example apps compiled to WebAssembly, rendered in the browser.",
+  "start_url": "/app/",
+  "scope": "/",
+  "display": "standalone",
+  "orientation": "portrait",
+  "background_color": "#000000",
+  "icons": [
+    { "src": "/icon.svg", "sizes": "any", "type": "image/svg+xml" },
+    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
+  ]
+}