feat: term.update() folds CapabilityEvents into runtime capabilities

[natemoo-re]

Part 4/4 (final) of the terminfo foundation stack. Requires #132.

• term.update() is now the single entry point for resize and capability changes: pass a { width, height }, any InputEvent, or an array of them; it returns bytes to write (empty for now)
• createTerm({ terminfo }) seeds the renderer from a TerminalInfo; term.capabilities exposes the current snapshot (256-color baseline when omitted)
• validated() forwards the new capabilities getter
• Changeset covers detectTerminal/TerminalInfo, the createTerm option, and the update({ events }) → update(events) break
• Out of scope: no change to rendered bytes yet; first consumer is color encoding modes (💡 Color-encoding modes (16-color / 256-color) derived from terminfo #60), other protocol follow-ups in Track terminfo capability follow-ups #129

Split from #106 for reviewability; #106 closes when this stack lands.

[bombshell-cooper]

Changeset suggestion

The current changeset no longer matches this PR. This review contains a corrected replacement.

Why: Changeset package scope does not match the affected packages confidently. Changeset bump does not match the consumer-visible impact. Changeset contains implementation or roadmap noise. Changeset contains unsupported consumer-facing claims.

View the proposed changeset

---
'@bomb.sh/tty': minor
---

Adds `detectTerminal()`, `TerminalInfo`, `Capabilities`, `DetectOptions`, `KeyTable`, and `MAX_TERMINFO_ENTRY` to the public API, and a `terminfo` option to `createTerm`.

`detectTerminal()` reads the compiled terminfo entry for the current terminal (from the ncurses search path, or from bytes passed as `entry`), applies environment evidence (`COLORTERM`), and resolves a frozen `TerminalInfo` carrying static `capabilities`, a `probe` query batch to write to stdout, and opaque `keys` for the input parser.

Pass the returned `TerminalInfo` as `terminfo` to `createTerm` and `createInput`. `term.capabilities` exposes a frozen `RuntimeCapabilities` snapshot seeded from `terminfo.capabilities` (or the 256-color baseline when omitted) and kept current by `update()`.

`term.update()` now accepts one change or an array of changes — a `{ width, height }` resize or any `InputEvent` — instead of an `{ events }` bag. Capability events from `scan()` are folded into `term.capabilities`; other input events are ignored, so the full `events` array can be passed without filtering. `update()` returns a `Uint8Array` of bytes to write immediately (empty when there are none).

#### Migration

```diff
-term.update({ events });
+const out = term.update(events);
+if (out.length) process.stdout.write(out);
```

To enable terminfo-aware rendering:

```diff
+const terminfo = await detectTerminal({ env: process.env });
+const term = await createTerm({ width, height, terminfo });
+const input = await createInput({ terminfo });
+process.stdout.write(terminfo.probe);
```

Review this changeset manually

If this draft is correct, react with 🚀 and Cooper will commit it to this branch.

[bombshell-cooper]

Changeset needs revision.

Changeset package scope does not match the affected packages confidently. Changeset bump does not match the consumer-visible impact. Changeset contains implementation or roadmap noise. Changeset contains unsupported consumer-facing claims.

View the proposed replacement

---
'@bomb.sh/tty': minor
---

Adds `detectTerminal()`, `TerminalInfo`, `Capabilities`, `DetectOptions`, `KeyTable`, and `MAX_TERMINFO_ENTRY` to the public API, and a `terminfo` option to `createTerm`.

`detectTerminal()` reads the compiled terminfo entry for the current terminal (from the ncurses search path, or from bytes passed as `entry`), applies environment evidence (`COLORTERM`), and resolves a frozen `TerminalInfo` carrying static `capabilities`, a `probe` query batch to write to stdout, and opaque `keys` for the input parser.

Pass the returned `TerminalInfo` as `terminfo` to `createTerm` and `createInput`. `term.capabilities` exposes a frozen `RuntimeCapabilities` snapshot seeded from `terminfo.capabilities` (or the 256-color baseline when omitted) and kept current by `update()`.

`term.update()` now accepts one change or an array of changes — a `{ width, height }` resize or any `InputEvent` — instead of an `{ events }` bag. Capability events from `scan()` are folded into `term.capabilities`; other input events are ignored, so the full `events` array can be passed without filtering. `update()` returns a `Uint8Array` of bytes to write immediately (empty when there are none).

#### Migration

```diff
-term.update({ events });
+const out = term.update(events);
+if (out.length) process.stdout.write(out);
```

To enable terminfo-aware rendering:

```diff
+const terminfo = await detectTerminal({ env: process.env });
+const term = await createTerm({ width, height, terminfo });
+const input = await createInput({ terminfo });
+process.stdout.write(terminfo.probe);
```

[github-actions]

Size Increased — +9.8 KB

121.4 KB unpacked

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@bomb.sh/tty@133

commit: eb3b262

[codspeed]

Merging this PR will not alter performance

✅ 10 untouched benchmarks

---

_{Comparing feat/term-capability-sink (eb3b262) with feat/input-probe-events (5081cb4)¹}

Footnotes

1. No successful run was found on feat/input-probe-events (0d1f019) during the generation of this report, so 3527203 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩