Platforms overview

FrankenTUI ships a single rendering kernel that runs unchanged against a native terminal, a browser canvas, or an in-memory test harness. The seam that makes this possible is a small trait contract in the ftui-backend crate; every host (ftui-tty, ftui-web, and the PTY test fixtures in ftui-pty) is just one more implementation of that contract.

The portability claim

The runtime’s Elm-style loop, the render pipeline, the widget library, text shaping, and the intelligence layer all compile to wasm32-unknown-unknown with zero conditional compilation. That is a load-bearing design constraint: any feature that needs std::time::Instant, std::thread, or file I/O goes behind a backend trait instead of into core.

The upshot is that the browser demo, the native binary, and every deterministic E2E test drive the exact same widget code. When a widget behaves one way in the terminal and a different way in the browser, that is a backend bug, not a widget bug, and it is fixable without touching UI code.

The ftui-backend seam

The ftui-backend crate defines three independent capabilities that every host must supply:

BackendFeatures advertises optional capabilities (synchronized output, bracketed paste, OSC 8 hyperlinks, Kitty keyboard protocol). The runtime asks the backend what it supports and downgrades gracefully instead of assuming a least-common-denominator baseline.

The three hosts in this workspace

Mental model

 ┌─────────────────────────────────────────────────────────┐
 │   widgets · runtime · render · text · style · a11y      │   portable core
 │   (compiles to wasm32, zero platform deps)              │
 └───────────┬──────────────┬───────────────┬──────────────┘
             │              │               │
       ┌─────▼────┐   ┌─────▼────┐   ┌──────▼──────┐
       │ ftui-tty │   │ ftui-web │   │  ftui-pty   │       one trait impl each
       │  Backend │   │  Backend │   │  (tests)    │
       └─────┬────┘   └─────┬────┘   └──────┬──────┘
             │              │               │
        ┌────▼───┐    ┌─────▼─────┐   ┌─────▼─────┐
        │  TTY   │    │  Browser  │   │ subprocess│
        │ (Unix) │    │ (frankenterm-web)│ VT state│
        └────────┘    └───────────┘   └───────────┘

The diagram is deliberately boring: that is the point. All of the interesting engineering sits above the backend line, not below it.

Example: a single frame, two hosts

while let Some(event) = backend.poll_event(Duration::from_millis(16))? {
    model.update(event, &mut cmds);
}

Why ftui-pty sits here

ftui-pty is a test-only crate, but it participates in the same platform story. It spawns a real shell, runs a binary that uses ftui-tty, and scrapes the output through a virtual terminal state machine to assert what the user would actually see. It also carries the WebSocket bridge that integrates with the external frankenterm-core streaming codec. Details on pty-utilities.

Adjacent, not in-tree

Pitfalls

• Do not sprinkle #[cfg(target_arch = "wasm32")] into widgets. Push the platform concern down into the backend crate instead. Reviewers will reject widget PRs that leak host details.
• Do not assume Instant::now() is cheap in the browser. The backend gives you a monotonic clock; use it. Direct Instant usage in portable code will not compile to wasm32.
• Do not invent a custom event type per host. Everything normalizes to ftui_core::event::Event. If a host sends something that does not map, the backend returns Ok(None) and drops it.

See also

• Runtime overview — the loop that sits above every backend
• Demo showcase overview — the same screens, both natively and in-browser
• Contributing — dev loop — building and testing across backends
• Web backend · WASM showcase · Windows