FrankenTerm integration

FrankenTUI and FrankenTerm are two projects that share a backend seam. FrankenTUI is the portable TUI kernel you are reading the docs for. FrankenTerm is a browser-facing terminal emulator that consumes FrankenTUI’s web backend. Historically they were planned to live in one workspace; today they do not, and the README is explicit on this.

What is in-tree — right now, in this repo

Every one of those is self-contained. You can build, test, and ship the FrankenTUI workspace to crates.io without any FrankenTerm crate being present anywhere on your disk.

What is adjacent — and not in this workspace

The build-wasm.sh script in this repo conditionally builds a crates/frankenterm-web directory if it is present. In a stock FrankenTUI checkout that directory is absent and the step is a no-op. In the FrankenTerm monorepo that vendors both codebases as a single workspace, both crates build together.

Why the README and specs still mention the absent names

Two reasons:

1. History. The original plan was a single workspace. The spec documents (docs/spec/frankenterm-architecture.md, docs/spec/frankenterm-*.md, and others) were written against that plan and still reference crates/frankenterm-core / crates/frankenterm-web as if they lived here. When you see those paths, read them as names, not as directory locations in this tree.

2. Contract stability. Even though the crates live elsewhere, their contracts are authored and versioned alongside FrankenTUI. The WebSocket protocol, the VT support matrix, the remote threat model, the golden trace format — all of those specs live in docs/spec/ of this repo because FrankenTUI’s backend is the producer side of those contracts. Moving the specs out would de-link them from the code that enforces them.

The FrankenTUI README says it cleanly:

This checkout does not currently vendor local crates/frankenterm-core or crates/frankenterm-web workspace members. Those names still appear in specs and adjacent integration docs, but the in-tree browser surface today is ftui-web plus the ftui-showcase-wasm target.

How the two sides talk

 ┌──────────────────────┐      patch format       ┌──────────────────────┐
 │    ftui-web          │  ──── u32 cell runs ──> │   frankenterm-web    │
 │  (this repo)         │       dirty spans       │   (adjacent, WASM)   │
 │                      │       FNV-1a hash       │                      │
 │  WebEventSource  <── │  ──── JSON input ────── │  DOM/canvas renderer │
 └──────────┬───────────┘                         └──────────┬───────────┘
            │                                                │
            │                                          ws-codec framing
            │                                                │
 ┌──────────▼───────────┐      WebSocket          ┌──────────▼───────────┐
 │    ftui-pty          │  ─── binary frames ──── │   frankenterm-core   │
 │  ws_bridge (tests)   │                         │   (external crate)   │
 └──────────────────────┘                         └──────────────────────┘

• Patch format — ftui-web emits cell runs; frankenterm-web repaints. Documented in web-backend.
• JSON input — browser DOM events are serialized to JSON and parsed by ftui-web::input_parser into ftui_core::event::Event.
• WebSocket codec — remote-session framing. ftui-pty::ws_bridge links against frankenterm-core for the wire format.

The contracts are small, versioned, and documented in docs/spec/. The three you are most likely to want:

• docs/spec/frankenterm-web-api.md — the JS-side API surface.
• docs/spec/frankenterm-websocket-protocol.md — the binary wire format.
• docs/spec/wasm-showcase-runner-contract.md — the ShowcaseRunner JS API exposed by ftui-showcase-wasm.

When you will and will not see these names

You will see frankenterm-* mentioned:

• In the ftui-pty Cargo.toml as a crates.io dependency.
• In build-wasm.sh, wrapped so the command no-ops when the adjacent crate is absent.
• Throughout docs/spec/ and docs/adr/ where contract authorship lives.
• In the README’s “Web/WASM Backend” and “FrankenTerm Integration” sections.

You will not see them:

• As directories in crates/.
• As members in the root Cargo.toml [workspace].members.
• As compile-time dependencies of any runtime-facing FrankenTUI crate (ftui-core, ftui-runtime, ftui-widgets, etc.).

If you are building FrankenTerm itself

The integration workflow from FrankenTerm’s side is:

1. Depend on the latest ftui-web from crates.io (or a git pin).
2. Consume the patch format documented on the web-backend page.
3. Pipe JSON input through ftui-web::input_parser’s JSON schema.
4. If you need remote sessions, bring in frankenterm-core and use the ws-codec feature.

The point of the seam is that FrankenTUI can ship new widgets, new render optimizations, and new intelligence features without requiring coordinated releases on the FrankenTerm side — you pick up the improvements by bumping the ftui-web pin.

Pitfalls

• Do not file bugs in this repo for FrankenTerm rendering issues. If the patch format is being applied incorrectly, that is an frankenterm-web bug. If the patch format itself is wrong, that is an ftui-web bug. The first thing to check is whether another ShowcaseRunner frame with the same input reproduces the glitch — if yes, it is on this side; if no, it is on the adjacent side.
• Do not add crates/frankenterm-core or crates/frankenterm-web as workspace members “to make the specs match.” The specs are correct; the workspace is correct; they just describe different topologies.
• Do not assume the WebSocket bridge is a FrankenTUI runtime feature. It lives in ftui-pty for testing remote sessions. Production remote workflows use FrankenTerm directly.

See also

• Platforms overview — the backend seam
• Web backend — the producer side of the patch format
• WASM showcase — what ftui-showcase-wasm builds
• PTY utilities — where frankenterm-core integration lives
• Runtime overview · Demo showcase overview · Contributing — dev loop