@swifttui/web 0.0.6

package/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+Guidance for agentic assistants working in **`@swifttui/web`**. Keep this
+concise; [`README.md`](README.md) is the full reference.
+
+## What this package is
+
+The **browser runtime** for SwiftTUI apps. It owns the browser-safe runtime
+APIs: scene-manifest loading, canvas rendering, ARIA mounting, WebSocket scene
+bridges, and WASI scene bridges. Build/packaging tooling lives in the sibling
+[`@swifttui/build`](../build) workspace package — keep that split.
+
+It lives in the repo's Bun workspace (`packages/web` in `swift-tui-web`). Run
+`bun install` from the repo root or any package dir; one root `bun.lock` is
+maintained.
+
+## Toolchains
+
+- **Bun** for dev, bundling, and the test runner.
+- **`swiftly`** Swift 6.3.1 for any Swift the build path triggers
+  (`swiftly run swift --version`). Do not use bare `swift`/`xcrun swift`.
+
+## Commands
+
+```bash
+bun test                      # this package's tests (or `bun run test`)
+bun run build:web             # bundle index.html + browser entrypoint
+bun run build -- --app <Exe>  # full build (manifest + wasm + web)
+bun run dev                   # watch/dev
+```
+
+`build:manifest` and `build:wasm` delegate to `@swifttui/build` and default to
+`--configuration release`. The org-level gate for this repo is `bun run ci`
+(install --frozen-lockfile + test + build:web), run from the `swift-tui-web` root.
+
+## Architecture notes
+
+- Transport is SwiftTUI's **`web-surface` WASI transport**: the Swift runner
+  emits raster-surface records on stdout and the host draws rects/text to a
+  canvas. **No terminal emulator** — does not use `ghostty-web`/`ghostty-vt.wasm`.
+  `BrowserWASIBridge` sets `TUIGUI_TRANSPORT=surface`.
+- Entry points: `createWebHostApp` (`.`), `createWasmSceneRuntimeFactory`
+  (`./wasi`), `startWasmSceneWorker` (`./wasi-worker`). Subpath exports are
+  declared in `package.json` — keep `exports` in sync when adding modules.
+- Scene switching is controller-managed and retains existing scene runtimes.
+- Terminal styling is host-owned via `WebHostTerminalStyle` (one active
+  palette/theme pair); the library ships no built-in mode switcher.
+
+## Conventions
+
+`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it. Edit `AGENTS.md`.
+Tests are colocated as `*.test.ts` (browser-only specs use `*.browser.ts`).

package/README.md

@@ -0,0 +1,116 @@
+# `@swifttui/web`
+
+Browser runtime package for SwiftTUI apps.
+
+This package owns browser-safe runtime APIs: scene manifest loading, canvas
+rendering, ARIA mounting, WebSocket scene bridges, and WASI scene bridges. Build
+tooling lives in the sibling [`@swifttui/build`](../build) workspace package.
+
+Publication status: the package name is reserved for the first public web
+release. Until it is published to npm or attached as a public release tarball,
+use the source checkout and the `swift-tui-examples/WebExample` template.
+
+## Toolchains
+
+Use Bun for repo-local development of this package, and use the repo-default
+`swiftly` Swift 6.3.1 toolchain for every Swift command that the build pipeline
+triggers.
+
+Quick check:
+
+```bash
+swiftly run swift --version
+```
+
+Native-only development should also work in Xcode, but the documented package
+and wasm build path uses `swiftly` plus Bun.
+
+For source development, run `bun install` from the repo root or from any
+workspace package directory, and Bun will maintain one root `bun.lock` plus
+stable relative workspace links.
+
+## Surface Transport
+
+This package uses SwiftTUI's `web-surface` WASI transport. The Swift runner
+emits structured raster-surface records on stdout, and the browser host draws
+rectangles and text into a canvas. It does not load a terminal emulator and does
+not depend on `ghostty-web` or `ghostty-vt.wasm`.
+
+`web-surface` is the default `SwiftTUIWASI` browser transport. WebHost still
+sets `TUIGUI_TRANSPORT=surface` explicitly so generated app environments are
+self-describing.
+
+## API
+
+```ts
+import { createWebHostApp } from "@swifttui/web";
+
+const controller = await createWebHostApp({
+  mount: document.getElementById("app")!,
+  manifestUrl: new URL("./scene-manifest.json", import.meta.url),
+  style: {
+    palette: {
+      foreground: "#eceff4",
+      background: "#1e222a",
+      cursor: "#56b6c2",
+      selectionBackground: "#2e3440",
+      selectionForeground: "#eceff4",
+    },
+    theme: {
+      foreground: "#eceff4",
+      background: "#1e222a",
+      tint: "#56b6c2",
+      link: "#5ba3ff",
+    },
+  },
+});
+
+await controller.switchScene("dashboard");
+controller.setStyle({ cursorBlink: true, theme: { tint: "#79c0ff" } });
+```
+
+For a static WASI-hosted app, use the WASI subpath:
+
+```ts
+import { createWasmSceneRuntimeFactory } from "@swifttui/web/wasi";
+```
+
+Worker entrypoints can delegate to:
+
+```ts
+import { startWasmSceneWorker } from "@swifttui/web/wasi-worker";
+
+startWasmSceneWorker();
+```
+
+## Scripts
+
+- `bun test`
+- `bun run build:manifest -- --app <AppExecutable>`
+- `bun run build:wasm -- --app <AppExecutable>`
+- `bun run build:web`
+- `bun run build -- --app <AppExecutable>`
+- `bun run dev`
+
+`build:manifest`, `build:wasm`, and `build` delegate manifest/WASI packaging to
+`@swifttui/build`. `build:wasm` and `build` default to
+`--configuration release`; pass `--configuration debug` for local
+debug-oriented wasm builds.
+
+The build flow is intentionally small:
+
+1. `build:manifest` captures `TUIGUI_MODE=manifest` output from the Swift app by invoking `swiftly run swift`.
+2. `build:wasm` copies the app's wasm artifact into `dist/assets/app.wasm`,
+   validates it with the browser `WebAssembly` API, then keeps the stripped
+   artifact only if stripping still produces browser-parseable wasm.
+3. `build:web` bundles `index.html` and the browser entrypoint with Bun.
+
+## Notes
+
+- Scene switching is controller-managed and retains existing scene runtimes.
+- Terminal styling is host-owned through `WebHostTerminalStyle`, which carries
+  one active palette/theme pair plus the runtime payload sent into SwiftTUI.
+- Hosts that want multiple themes swap entire `WebHostTerminalStyle` objects;
+  the library does not provide a built-in mode switcher.
+- `BrowserWASIBridge` sets `TUIGUI_TRANSPORT=surface` and decodes surface
+  frames before handing them to the canvas runtime.

package/cli.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env bun
+
+import { mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import {
+  buildAppWasm,
+  buildSwiftTUIWebApp,
+  generateSceneManifest,
+  type WasmBuildConfiguration,
+} from "../build/index.ts";
+
+void runCli(process.argv.slice(2));
+
+async function runCli(argv: string[]): Promise<void> {
+  const command = argv[0] ?? "build";
+  const flags = parseFlags(argv.slice(1));
+  const packagePath = resolve(flags["package-path"] ?? "../../");
+  const distPath = resolve(flags["dist"] ?? "./dist");
+  const appExecutable = flags.app ?? flags.product ?? flags["app-product"] ?? "";
+  const wasmConfiguration = parseWasmBuildConfiguration(flags.configuration ?? "release");
+
+  switch (command) {
+    case "build:manifest":
+      assertAppExecutable(appExecutable);
+      await generateSceneManifest({
+        packagePath,
+        outputPath: join(distPath, "scene-manifest.json"),
+        appExecutable,
+      });
+      return;
+    case "build:wasm":
+      assertAppExecutable(appExecutable);
+      await buildAppWasm({
+        configuration: wasmConfiguration,
+        packagePath,
+        outputDirectory: distPath,
+        product: appExecutable,
+      });
+      return;
+    case "build:web":
+      await bunBuildWeb({
+        outputDirectory: distPath,
+      });
+      return;
+    case "build":
+      assertAppExecutable(appExecutable);
+      await buildSwiftTUIWebApp({
+        configuration: wasmConfiguration,
+        packagePath,
+        outputDirectory: distPath,
+        product: appExecutable,
+      });
+      await bunBuildWeb({
+        outputDirectory: distPath,
+      });
+      return;
+    case "dev":
+      await bunServe(packagePath, distPath);
+      return;
+    default:
+      throw new Error(`unknown command: ${command}`);
+  }
+}
+
+async function bunBuildWeb(options: {
+  outputDirectory: string;
+}): Promise<void> {
+  await mkdir(options.outputDirectory, { recursive: true });
+  const proc = Bun.spawn({
+    cmd: [
+      "bun",
+      "build",
+      "./index.html",
+      "--outdir",
+      options.outputDirectory,
+    ],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new Error([stdout, stderr].filter(Boolean).join("\n").trim() || "web build failed");
+  }
+}
+
+async function bunServe(
+  packagePath: string,
+  distPath: string
+): Promise<void> {
+  const server = Bun.serve({
+    port: Number(process.env.PORT ?? "3000"),
+    development: {
+      hmr: true,
+      console: true,
+    },
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname === "/") {
+        return new Response(Bun.file(join(distPath, "index.html")));
+      }
+      if (url.pathname === "/scene-manifest.json") {
+        return new Response(Bun.file(join(distPath, "scene-manifest.json")));
+      }
+      if (url.pathname.startsWith("/assets/")) {
+        return new Response(Bun.file(join(distPath, url.pathname.slice(1))));
+      }
+      if (url.pathname.startsWith("/src/")) {
+        return new Response(Bun.file(join(packagePath, url.pathname.slice(1))));
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+
+  console.log(`WebHost dev server running at ${server.url.href}`);
+  await new Promise<void>(() => {});
+}
+
+function parseFlags(
+  argv: string[]
+): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      continue;
+    }
+    const equalsIndex = value.indexOf("=");
+    if (equalsIndex !== -1) {
+      flags[value.slice(2, equalsIndex)] = value.slice(equalsIndex + 1);
+      continue;
+    }
+    const name = value.slice(2);
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags[name] = next;
+      index += 1;
+    } else {
+      flags[name] = "true";
+    }
+  }
+  return flags;
+}
+
+function parseWasmBuildConfiguration(
+  value: string
+): WasmBuildConfiguration {
+  switch (value) {
+    case "debug":
+      return "debug";
+    case "release":
+      return "release";
+    default:
+      throw new Error(`unsupported wasm build configuration: ${value}`);
+  }
+}
+
+function assertAppExecutable(
+  value: string
+): asserts value is string {
+  if (!value) {
+    throw new Error("missing --app or --product flag");
+  }
+}

package/index.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>WebHost</title>
+    <style>
+      :root {
+        color-scheme: dark;
+      }
+
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #000;
+      }
+
+      #webhost-root,
+      .webhost-scene-root,
+      .webhost-scene {
+        width: 100%;
+        height: 100%;
+      }
+
+      .webhost-scene__header {
+        display: none;
+      }
+
+      .webhost-scene__terminal {
+        width: 100%;
+        height: 100%;
+        min-height: 100%;
+        touch-action: none;
+        -webkit-user-select: none;
+        user-select: none;
+        cursor: default;
+      }
+
+      .webhost-scene__terminal canvas {
+        touch-action: none;
+        cursor: default;
+      }
+    </style>
+    <script type="module" src="./src/browser.ts"></script>
+  </head>
+  <body>
+    <main id="webhost-root"></main>
+  </body>
+</html>

package/index.ts

@@ -0,0 +1,8 @@
+export * from "./src/WebHostApp.ts";
+export * from "./src/WebHostSceneManifest.ts";
+export * from "./src/WebHostTerminalStyle.ts";
+export * from "./src/WebHostSurfaceTransport.ts";
+export * from "./src/WebHostSceneRuntime.ts";
+export * from "./src/WebSocketSceneBridge.ts";
+export * from "./src/wasi/BrowserWASIBridge.ts";
+export * from "./src/wasi/StdIOPipe.ts";

package/manifest.ts

@@ -0,0 +1 @@
+export * from "./src/WebHostSceneManifest.ts";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@swifttui/web",
+  "version": "0.0.6",
+  "license": "MIT",
+  "module": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./manifest": "./manifest.ts",
+    "./style.css": "./style.css",
+    "./testing": "./testing.ts",
+    "./wasi": "./wasi.ts",
+    "./wasi-worker": "./wasi-worker.ts",
+    "./websocket": "./websocket.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "build:manifest": "bun run --cwd ../build build:manifest -- --dist ../web/dist",
+    "build:wasm": "bun run --cwd ../build build:wasm -- --dist ../web/dist",
+    "build:web": "bun run cli.ts build:web",
+    "build": "bun run cli.ts build",
+    "dev": "bun run cli.ts dev",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "^0.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.13"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/AccessibilityTree.ts

@@ -0,0 +1,262 @@
+import type {
+  WebHostAccessibilityAnnouncement,
+  WebHostAccessibilityNode,
+} from "./WebHostSurfaceTransport.ts";
+
+interface AccessibilityTreeMetrics {
+  cellWidth: number;
+  cellHeight: number;
+}
+
+interface AccessibilityTreePresentationOptions {
+  synchronizeFocus?: boolean;
+}
+
+interface RoleMapping {
+  role?: string;
+  level?: number;
+}
+
+export class AccessibilityTreeMounter {
+  readonly element: HTMLElement;
+  readonly announcerElement: HTMLElement;
+
+  private readonly nodesById = new Map<string, HTMLElement>();
+  private previousLabelsById = new Map<string, string>();
+  private hasLiveRegionBaseline = false;
+
+  constructor() {
+    this.element = document.createElement("div");
+    this.element.className = "webhost-scene__accessibility-tree";
+    applyScreenReaderOnlyStyle(this.element);
+
+    this.announcerElement = document.createElement("div");
+    this.announcerElement.className = "webhost-scene__accessibility-announcer";
+    this.announcerElement.setAttribute("aria-atomic", "true");
+    applyScreenReaderOnlyStyle(this.announcerElement);
+  }
+
+  present(
+    nodes: WebHostAccessibilityNode[],
+    metrics: AccessibilityTreeMetrics,
+    announcements: WebHostAccessibilityAnnouncement[] = [],
+    options: AccessibilityTreePresentationOptions = {}
+  ): void {
+    this.element.replaceChildren();
+    this.nodesById.clear();
+
+    for (const node of nodes) {
+      const element = this.elementForNode(node, metrics);
+      this.nodesById.set(node.id, element);
+    }
+
+    for (const node of nodes) {
+      const element = this.nodesById.get(node.id);
+      if (!element) {
+        continue;
+      }
+
+      const parent = node.parentId ? this.nodesById.get(node.parentId) : undefined;
+      (parent ?? this.element).appendChild(element);
+    }
+
+    this.announceLiveRegionChanges(nodes, announcements);
+
+    const focused = nodes.find((node) => node.isFocused);
+    if ((options.synchronizeFocus ?? true) && focused) {
+      this.nodesById.get(focused.id)?.focus?.({ preventScroll: true });
+    }
+  }
+
+  private elementForNode(
+    node: WebHostAccessibilityNode,
+    metrics: AccessibilityTreeMetrics
+  ): HTMLElement {
+    const element = document.createElement("div");
+    element.id = `swifttui-a11y-${stableDOMId(node.id)}`;
+    element.dataset.accessibilityId = node.id;
+    element.tabIndex = node.isFocused ? 0 : -1;
+
+    const role = roleMapping(node.role);
+    if (role.role) {
+      element.setAttribute("role", role.role);
+    }
+    if (role.level !== undefined) {
+      element.setAttribute("aria-level", String(role.level));
+    }
+    if (node.label) {
+      element.setAttribute("aria-label", node.label);
+    }
+    if (node.hint) {
+      element.setAttribute("aria-description", node.hint);
+    }
+    if (node.liveRegion) {
+      element.setAttribute("aria-live", node.liveRegion);
+    }
+    if (node.isFocused) {
+      element.dataset.focused = "true";
+    }
+
+    const [x, y, width, height] = node.rect;
+    element.style.position = "absolute";
+    element.style.left = `${x * metrics.cellWidth}px`;
+    element.style.top = `${y * metrics.cellHeight}px`;
+    element.style.width = `${Math.max(1, width) * metrics.cellWidth}px`;
+    element.style.height = `${Math.max(1, height) * metrics.cellHeight}px`;
+
+    return element;
+  }
+
+  private announceLiveRegionChanges(
+    nodes: WebHostAccessibilityNode[],
+    announcements: WebHostAccessibilityAnnouncement[]
+  ): void {
+    const candidates = nodes.filter(
+      (node) => node.liveRegion && node.liveRegion !== "off" && node.label
+    );
+    const currentLabelsById = new Map(candidates.map((node) => [node.id, node.label ?? ""]));
+    const imperativeAssertive = announcements.filter(
+      (announcement) => announcement.politeness === "assertive"
+    );
+    const imperativePolite = announcements.filter(
+      (announcement) => announcement.politeness === "polite"
+    );
+
+    if (!this.hasLiveRegionBaseline) {
+      this.previousLabelsById = currentLabelsById;
+      this.hasLiveRegionBaseline = true;
+      this.publishAnnouncements([], imperativeAssertive, [], imperativePolite);
+      return;
+    }
+
+    const changed = candidates.filter((node) => {
+      const previous = this.previousLabelsById.get(node.id);
+      return previous !== undefined && previous !== node.label;
+    });
+    this.previousLabelsById = currentLabelsById;
+
+    const assertive = changed.filter((node) => node.liveRegion === "assertive");
+    const polite = changed.filter((node) => node.liveRegion === "polite");
+    this.publishAnnouncements(assertive, imperativeAssertive, polite, imperativePolite);
+  }
+
+  private publishAnnouncements(
+    assertive: WebHostAccessibilityNode[],
+    imperativeAssertive: WebHostAccessibilityAnnouncement[],
+    polite: WebHostAccessibilityNode[],
+    imperativePolite: WebHostAccessibilityAnnouncement[]
+  ): void {
+    const ordered = [...assertive, ...imperativeAssertive, ...polite, ...imperativePolite];
+    if (ordered.length === 0) {
+      return;
+    }
+
+    const politeness = assertive.length > 0 || imperativeAssertive.length > 0
+      ? "assertive"
+      : "polite";
+    this.announcerElement.setAttribute("aria-live", politeness);
+    this.announcerElement.textContent = ordered.map((entry) => {
+      if ("message" in entry) {
+        return entry.message;
+      }
+      return entry.label ?? "";
+    }).join("\n");
+  }
+}
+
+function applyScreenReaderOnlyStyle(
+  element: HTMLElement
+): void {
+  element.style.position = "absolute";
+  element.style.left = "0";
+  element.style.top = "0";
+  element.style.width = "1px";
+  element.style.height = "1px";
+  element.style.overflow = "hidden";
+  element.style.clipPath = "inset(50%)";
+  element.style.whiteSpace = "nowrap";
+}
+
+function roleMapping(
+  role: string
+): RoleMapping {
+  const heading = /^heading\(level: ([0-9]+)\)$/.exec(role);
+  if (heading) {
+    return {
+      role: "heading",
+      level: Math.max(1, Math.min(6, Number(heading[1]))),
+    };
+  }
+
+  const custom = /^custom\((.+)\)$/.exec(role);
+  if (custom) {
+    return { role: custom[1] };
+  }
+
+  switch (role) {
+  case "alert":
+  case "button":
+  case "cell":
+  case "checkbox":
+  case "grid":
+  case "group":
+  case "link":
+  case "list":
+  case "menu":
+  case "region":
+  case "separator":
+  case "slider":
+  case "status":
+  case "tab":
+  case "table":
+  case "timer":
+    return { role };
+  case "columnHeader":
+    return { role: "columnheader" };
+  case "confirmationDialog":
+  case "sheet":
+    return { role: "dialog" };
+  case "disclosureGroup":
+  case "scrollView":
+  case "scrollViewWithIndicators":
+  case "section":
+    return { role: "region" };
+  case "image":
+    return { role: "img" };
+  case "menuItem":
+    return { role: "menuitem" };
+  case "picker":
+    return { role: "combobox" };
+  case "progressBar":
+    return { role: "progressbar" };
+  case "rowHeader":
+    return { role: "rowheader" };
+  case "secureField":
+  case "textEditor":
+  case "textField":
+    return { role: "textbox" };
+  case "stepper":
+    return { role: "spinbutton" };
+  case "tabPanel":
+    return { role: "tabpanel" };
+  case "tableRow":
+    return { role: "row" };
+  case "tabView":
+    return { role: "tablist" };
+  case "toggle":
+    return { role: "checkbox" };
+  default:
+    return { role: "group" };
+  }
+}
+
+function stableDOMId(
+  id: string
+): string {
+  return Array.from(id).map((character) => {
+    if (/^[a-zA-Z0-9_-]$/.test(character)) {
+      return character;
+    }
+    return `-${character.codePointAt(0)?.toString(16) ?? "0"}-`;
+  }).join("");
+}