Skip to content

Add platform bindings for Node and xterm.js - #79

Draft
natemoo-re wants to merge 1 commit into
mainfrom
spike/platform
Draft

natemoo-re wants to merge 1 commit into
mainfrom
spike/platform

Conversation

@natemoo-re

Copy link
Copy Markdown
Member

What does this PR do?

Follow-up to #74, spiking on @cowboyd's point that we can't assume process or SIGINT when running in a browser on xterm.js.

Host-specific code now lives behind a small Platform interface. The package's export conditions pick the binding, so callers never create one themselves:

interface Platform {
  size(): Size;
  write(bytes: Uint8Array): Promise<void>;
  listen(events: { resize(size: Size): void; interrupt(): void }, signal: AbortSignal): void;
}

UIOptions keeps the same fields, but they're all optional now, so this works:

const ui = await createUI();
await ui.main(); // runs until SIGINT/SIGTERM, then restores the terminal
  • Node, Bun, Deno (index.ts): output defaults to process.stdout. Size is width/height if passed, otherwise the TTY's columns/rows, otherwise 80×24. The UI follows terminal resizes. It stops on SIGINT/SIGTERM only when no signal is passed; if you pass one, signal handling stays yours, so existing callers behave the same.
  • Browser (index.browser.ts, via the browser condition): createUI({ output: terminal, signal }), where terminal is an xterm.js terminal. This entry has its own UIOptions and its own types under the condition. XtermTerminal only describes the part of xterm's API we use, so there's no @xterm/xterm dependency.

Also:

  • Fixes bench/helpers.ts, which Require an AbortSignal for UI lifetime #74 left calling createUI without a signal (flagged by @dreyfus92).
  • The Node platform keeps the event loop alive while the UI runs. Before that change, a zero-argument createUI() exited right away with an unsettled top-level await (code 13), because input is never read and signal listeners don't hold the process open. The same thing happens on main whenever the caller doesn't hold the process open themselves.

Notes

  • Why export conditions and not #platform subpath imports: bsh build runs tsdown with config: false, which resolves #platform at build time and bakes the Node binding into dist/ui.mjs. If we taught @bomb.sh/tools to leave # imports unresolved, we could collapse the two entry points into one.
  • Bun and Deno use the Node binding. A native Deno.stdout binding doesn't buy anything while @bomb.sh/tty depends on node: modules.

Open questions

  • tty needs its own browser export. esm/wasm.js uses brotliDecompressSync from node:zlib, and esm/terminfo.js imports node:fs/promises, node:url and node:process; mod.js re-exports terminfo statically. Until that's split, the browser entry won't actually load in a browser. The xterm binding is only tested against a fake terminal.
  • Input and raw mode aren't wired up. Once they are, Ctrl+C arrives as \x03 rather than SIGINT, so interrupt probably needs to come from input parsing too. Input likely becomes another listen event.

Type of change

  • Bug fix
  • Feature
  • Refactor (no behavior change)
  • Documentation
  • Performance improvement
  • Tests
  • Chore (dependencies, CI, tooling)

Checklist

  • All tests pass (pnpm test)
  • Files are formatted (pnpm format)
  • I have added/updated tests for my changes (if applicable)
  • I have added a changeset

AI-generated code disclosure

  • This PR includes AI-generated code

@pkg-pr-new

pkg-pr-new Bot commented Nov 15, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/bombshell-dev/ui/@clack/ui@79

commit: 653d87a

@cowboyd cowboyd left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! One thing to consider is the order of operations with some of the TTY refactors

Comment thread packages/ui/src/ui.ts
Comment on lines +46 to +51
platform.write(term.update([{ type: 'resize', width, height }])).then(
() => render.request(),
() => stop.abort(),
);
},
interrupt: () => stop.abort(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we won't need to write anything in the future if term.update() is going to return void. We should probably settle that change in tty first first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants