@vibesdotdev/terminal-client 0.0.0-stage → 1.0.0-rc.3

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @vibesdotdev/terminal-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Terminal sessions for Vibes apps: open a local PTY or a remote PTY on a named
+fleet host, keep it alive across reconnects, drive it from an agent tool, and
+render it in a browser, a desktop window, or a text UI.
+
+The package composes `runtime/execution` (which allocates the PTY) and
+`runtime/rpc` (which carries remote sessions). It never allocates a PTY
+itself. Its semantic TerminalClient is registered as runtime/client:terminal.
+
+## Install
+
+```sh
+bun add @vibesdotdev/terminal-client @vibesdotdev/kernel
+```
+
+The Svelte surface uses optional peers (`svelte`, `@vibesdotdev/kit`,
+`@lucide/svelte`). Install them only if you use
+`@vibesdotdev/terminal-client/svelte`.
+
+## Compose the client
+
+Portable hosts compose `@vibesdotdev/terminal-client/api-client-plugin`.
+Consumer hosts retain `@vibesdotdev/terminal-client/plugin` (also available as
+`./consumer-plugin`), which adds the terminal tool and composes that client.
+The portable slice imports no consumer, TUI or host adapter implementations.
+
+Resolve `getVibesClient<TerminalClient>('terminal', runtime)` from
+`@vibesdotdev/kernel/client`. The kernel shares that owner within a runtime;
+its disposal terminates tool sessions, process trees and remote PTYs, then releases
+remote connections and counters. Remote PTYs are terminated even if no output
+subscriber ever attached.
+Remote helpers require this composition. Malformed remote references refuse with
+`INVALID_INPUT / terminal-remote-reference-invalid`; explicit local references
+retain `terminal-remote-reference-local`.
+
+## Open a session
+
+```ts
+import { openLocalSession } from '@vibesdotdev/terminal-client';
+
+const session = await openLocalSession(runtime, {
+  command: 'sh',
+  cols: 80,
+  rows: 24
+});
+session.onOutput((bytes) => terminal.write(bytes));
+```
+
+Servers that keep sessions across requests use
+`@vibesdotdev/terminal-client/server/session-store` (ownership, backlog,
+detach-vs-kill, idle cleanup) and browsers attach over HTTP with
+`openHttpSession(runtime, options)` from
+`@vibesdotdev/terminal-client/client/http-session`. Agents drive shells
+through the `terminal` tool (`execute`, `spawn`, interactive `session`).
+
+## Entrypoints
+
+- `@vibesdotdev/terminal-client` — `openLocalSession`, `openRemoteSession`
+- `@vibesdotdev/terminal-client/api-client-plugin` — portable semantic owner
+- `@vibesdotdev/terminal-client/plugin`, `./consumer-plugin` — consumer tool composition
+- `@vibesdotdev/terminal-client/client` — session composition helpers
+- `@vibesdotdev/terminal-client/workspace` — rune-free workspace lifecycle, place, and receipt contracts
+- `@vibesdotdev/terminal-client/server/session-store` — server store + SSE helpers
+- `@vibesdotdev/terminal-client/client/http-session` — browser HTTP adapter
+- `@vibesdotdev/terminal-client/pty-bridge` — compatibility names for the runtime PTY wire contract
+- `@vibesdotdev/terminal-client/pty-bridge/server` — compatibility delegation to the Bun host
+- `@vibesdotdev/terminal-client/ansi` — key-chord to byte-sequence map
+- `@vibesdotdev/terminal-client/tui` — terminal launcher views and state
+- `@vibesdotdev/terminal-client/tui/plugin` — launcher app, command, registry
+- `@vibesdotdev/terminal-client/svelte` — xterm renderer and workspace
+- `@vibesdotdev/terminal-client/svelte/workspace` — compatibility alias for the universal workspace contract
+- `@vibesdotdev/terminal-client/svelte/plugin` — docs topic and tool card
+
+## Verify
+
+From the repository root, run `bun run --cwd repos/platform/framework/terminal-client check`,
+then `test` and `build` with the same prefix. Check includes every TypeScript/TSX
+test and Svelte-adjacent source. Build emits production code only.
+The test script includes the real loopback PTY-to-headless-xterm proof: computed
+shell output must paint into xterm, and the shell must exit cleanly within runtime
+lifecycle deadlines. Session completion waits for remote connection cleanup.
+The proof also observes attached and never-attached PTYs terminate on caller
+disposal while the receiving host remains alive.
+
+Session, HTTP, store and tool options are owned by `src/schemas/`; existing helper
+exports remain compatible. `OpenTerminalOptionsSchema` and
+`SessionOpenOptionsSchema` are identical, including the schema exported by the
+server store subpath. HTTP reconnect defaults and store limits are declared in
+those schemas; reconnect callbacks and extra HTTP open-body fields are preserved.
+
+## Documentation
+
+- Contract: [SPEC.md](SPEC.md)
+- Svelte surface: [src/svelte/SPEC.md](src/svelte/SPEC.md)
+- PTY bridge: [src/pty-bridge/SPEC.md](src/pty-bridge/SPEC.md)
+- Key map: [src/ansi/SPEC.md](src/ansi/SPEC.md)
+- Package guide: https://docs.vibes.dev/terminal-client
+- Vibes docs: https://docs.vibes.dev
+
+## License
+
+Business Source License 1.1 (BUSL-1.1). See [LICENSE](LICENSE) for the terms.

package/dist/ansi/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @vibesdotdev/terminal-client/ansi
+ *
+ * The one genuinely reusable piece mined out of the desktop terminal driver:
+ * the key-name → terminal-byte-sequence map. Zero runtime deps. The 857-line
+ * ANSI/CSI parser in `desktop` is NOT carried — xterm.js owns parsing.
+ *
+ * This package registers no runtime kinds; it is pure logic.
+ */
+export { chordToSequence, resolveSequence, SPECIAL_KEYS, type KeyChord } from './keymap.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/ansi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ansi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACN,eAAe,EACf,eAAe,EACf,YAAY,EACZ,KAAK,QAAQ,EACb,MAAM,aAAa,CAAC"}

package/dist/ansi/index.js

@@ -0,0 +1,11 @@
+/**
+ * @vibesdotdev/terminal-client/ansi
+ *
+ * The one genuinely reusable piece mined out of the desktop terminal driver:
+ * the key-name → terminal-byte-sequence map. Zero runtime deps. The 857-line
+ * ANSI/CSI parser in `desktop` is NOT carried — xterm.js owns parsing.
+ *
+ * This package registers no runtime kinds; it is pure logic.
+ */
+export { chordToSequence, resolveSequence, SPECIAL_KEYS } from "./keymap.js";
+//# sourceMappingURL=index.js.map

package/dist/ansi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ansi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACN,eAAe,EACf,eAAe,EACf,YAAY,EAEZ,MAAM,aAAa,CAAC"}

package/dist/ansi/keymap.d.ts

@@ -0,0 +1,77 @@
+/**
+ * keymap — the key-name → terminal-byte-sequence map.
+ *
+ * Extracted and hardened from
+ * `desktop/src/runtime/terminal.ts:keyToSequence` (lines 569-642),
+ * the one genuinely reusable piece of the desktop terminal driver. The 857-line
+ * ANSI/CSI *parser* in that file is deliberately NOT extracted — xterm.js owns
+ * parsing in the browser; copying the parser would re-import the exact wheel
+ * xterm already turns correctly. Only the byte-sequence map moves here (the
+ * thing xterm does NOT hand us for free: byte sequences for non-printing keys).
+ *
+ * Zero runtime deps. Consumed by `@vibesdotdev/terminal-client/svelte` (browser keydown
+ * → bytes) and re-exportable for `@vibesdotdev/test-tui`'s headless input helpers
+ * (eventually replacing its `ansi-input.ts` constant duplication).
+ */
+/**
+ * A key chord, named the way `KeyboardEvent.key` + modifier booleans express it
+ * in the browser (e.g. `{ key: 'ArrowUp' }`, `{ key: 'c', ctrl: true }`,
+ * `{ key: 'x', alt: true }`). Casing of `key` is normalized internally, so both
+ * `'ArrowUp'` and `'up'` resolve.
+ */
+export interface KeyChord {
+    /** `'a'` | `'Enter'` | `'ArrowUp'` | `'F5'` | `'Home'` | … (KeyboardEvent.key). */
+    key: string;
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    /** Meta/Super key (Cmd on macOS, Win on Windows). */
+    meta?: boolean;
+}
+/**
+ * The special-key table — arrows, F-keys, home/end/pageup/down/insert/delete,
+ * enter/tab/escape/backspace/space. Keys are the lowercased short names the
+ * desktop driver used (`up`/`f1`/`home`/…); the resolver also maps the browser's
+ * `KeyboardEvent.key` long-names (`ArrowUp`/`F1`/`Home`/…) onto these.
+ *
+ * Verbatim byte sequences from the desktop `keyToSequence` table.
+ */
+export declare const SPECIAL_KEYS: Readonly<Record<string, string>>;
+/**
+ * Resolve the *raw* byte sequence for a chord, regardless of whether xterm.js
+ * would also handle it. Always returns a string. Use this when you own the input
+ * path end-to-end (e.g. test harnesses, the desktop driver). For the browser
+ * surface that lets xterm handle most keys, use {@link chordToSequence}.
+ *
+ * Modifier handling:
+ *   - Ctrl on a single printable char → its control character (Ctrl-A = 0x01,
+ *     Ctrl-C = 0x03, Ctrl-D = 0x04, Ctrl-L = 0x0c, Ctrl-Z = 0x1a, …).
+ *   - Alt → ESC-prefix the resulting sequence.
+ *   - Shift + special key → xterm/DEC modifier parameter encoding:
+ *       - CSI arrows/Home/End:   ESC [ 1 ; mod <letter>
+ *       - Tilde-family:          ESC [ N ; mod ~
+ *       - SS3 F1-F4:             ESC [ 1 ; mod <letter>  (converted from SS3)
+ *   - Shift on a printable char is consumed by the key's own case.
+ */
+export declare function resolveSequence(chord: KeyChord): string;
+/**
+ * Map a key chord to the terminal byte sequence for the **browser** surface.
+ * Returns `null` for chords xterm.js already encodes natively (so the component
+ * lets xterm handle them) — only the gaps come back as a string:
+ *   - F1–F12 (xterm does not emit these by default),
+ *   - Modified special keys (shift/ctrl + arrows/Home/End/F-keys/Delete/…),
+ *   - Alt-<key> meta sequences,
+ *   - Ctrl-<letter> control chars,
+ *   - the `space` alias when explicitly modified.
+ *
+ * Returns `null` (never sends to PTY) for clipboard chords:
+ *   - Ctrl+V, Cmd+V, Ctrl+Shift+V (paste),
+ *   - Cmd+C, Ctrl+Shift+C (copy),
+ *   - Ctrl+Shift+X (cut).
+ *
+ * IMPORTANT: plain Ctrl+C still returns 0x03 (SIGINT).
+ *
+ * A plain printable key with no modifier returns `null` (xterm types it itself).
+ */
+export declare function chordToSequence(chord: KeyChord): string | null;
+//# sourceMappingURL=keymap.d.ts.map

package/dist/ansi/keymap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keymap.d.ts","sourceRoot":"","sources":["../../src/ansi/keymap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BxD,CAAC;AAwDH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CA0DvD;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAsC9D"}

package/dist/ansi/keymap.js

@@ -0,0 +1,257 @@
+/**
+ * keymap — the key-name → terminal-byte-sequence map.
+ *
+ * Extracted and hardened from
+ * `desktop/src/runtime/terminal.ts:keyToSequence` (lines 569-642),
+ * the one genuinely reusable piece of the desktop terminal driver. The 857-line
+ * ANSI/CSI *parser* in that file is deliberately NOT extracted — xterm.js owns
+ * parsing in the browser; copying the parser would re-import the exact wheel
+ * xterm already turns correctly. Only the byte-sequence map moves here (the
+ * thing xterm does NOT hand us for free: byte sequences for non-printing keys).
+ *
+ * Zero runtime deps. Consumed by `@vibesdotdev/terminal-client/svelte` (browser keydown
+ * → bytes) and re-exportable for `@vibesdotdev/test-tui`'s headless input helpers
+ * (eventually replacing its `ansi-input.ts` constant duplication).
+ */
+/**
+ * The special-key table — arrows, F-keys, home/end/pageup/down/insert/delete,
+ * enter/tab/escape/backspace/space. Keys are the lowercased short names the
+ * desktop driver used (`up`/`f1`/`home`/…); the resolver also maps the browser's
+ * `KeyboardEvent.key` long-names (`ArrowUp`/`F1`/`Home`/…) onto these.
+ *
+ * Verbatim byte sequences from the desktop `keyToSequence` table.
+ */
+export const SPECIAL_KEYS = Object.freeze({
+    return: '\r',
+    enter: '\r',
+    tab: '\t',
+    escape: '\x1b',
+    esc: '\x1b',
+    backspace: '\x7f',
+    delete: '\x1b[3~',
+    up: '\x1b[A',
+    down: '\x1b[B',
+    right: '\x1b[C',
+    left: '\x1b[D',
+    home: '\x1b[H',
+    end: '\x1b[F',
+    pageup: '\x1b[5~',
+    pagedown: '\x1b[6~',
+    insert: '\x1b[2~',
+    f1: '\x1bOP',
+    f2: '\x1bOQ',
+    f3: '\x1bOR',
+    f4: '\x1bOS',
+    f5: '\x1b[15~',
+    f6: '\x1b[17~',
+    f7: '\x1b[18~',
+    f8: '\x1b[19~',
+    f9: '\x1b[20~',
+    f10: '\x1b[21~',
+    f11: '\x1b[23~',
+    f12: '\x1b[24~',
+    space: ' '
+});
+/**
+ * Browser `KeyboardEvent.key` long-names → the short names used by SPECIAL_KEYS.
+ * Lets a raw `KeyboardEvent` flow straight in: `{ key: 'ArrowUp' }`,
+ * `{ key: 'PageUp' }`, `{ key: 'F5' }`, `{ key: ' ' }` all resolve.
+ */
+const KEY_ALIASES = Object.freeze({
+    arrowup: 'up',
+    arrowdown: 'down',
+    arrowright: 'right',
+    arrowleft: 'left',
+    pageup: 'pageup',
+    pagedown: 'pagedown',
+    ' ': 'space',
+    spacebar: 'space',
+    del: 'delete'
+});
+/** Keys xterm.js already encodes correctly on its own — let them through. */
+const XTERM_NATIVE_KEYS = new Set([
+    'enter',
+    'return',
+    'tab',
+    'backspace',
+    'escape',
+    'esc',
+    'up',
+    'down',
+    'left',
+    'right',
+    'home',
+    'end',
+    'pageup',
+    'pagedown',
+    'insert',
+    'delete'
+]);
+function normalizeKeyName(key) {
+    const lower = key.toLowerCase();
+    return KEY_ALIASES[lower] ?? lower;
+}
+/**
+ * Compute the xterm/DEC modifier parameter for a chord's modifier keys.
+ * Returns undefined when no modifiers are active (avoids injecting ";1" which
+ * is technically valid but not emitted by real terminals).
+ *
+ * mod = 1 + (shift?1:0) + (alt?2:0) + (ctrl?4:0)
+ */
+function modParam(chord) {
+    const mod = 1 + (chord.shift ? 1 : 0) + (chord.alt ? 2 : 0) + (chord.ctrl ? 4 : 0);
+    return mod === 1 ? undefined : mod;
+}
+/**
+ * Resolve the *raw* byte sequence for a chord, regardless of whether xterm.js
+ * would also handle it. Always returns a string. Use this when you own the input
+ * path end-to-end (e.g. test harnesses, the desktop driver). For the browser
+ * surface that lets xterm handle most keys, use {@link chordToSequence}.
+ *
+ * Modifier handling:
+ *   - Ctrl on a single printable char → its control character (Ctrl-A = 0x01,
+ *     Ctrl-C = 0x03, Ctrl-D = 0x04, Ctrl-L = 0x0c, Ctrl-Z = 0x1a, …).
+ *   - Alt → ESC-prefix the resulting sequence.
+ *   - Shift + special key → xterm/DEC modifier parameter encoding:
+ *       - CSI arrows/Home/End:   ESC [ 1 ; mod <letter>
+ *       - Tilde-family:          ESC [ N ; mod ~
+ *       - SS3 F1-F4:             ESC [ 1 ; mod <letter>  (converted from SS3)
+ *   - Shift on a printable char is consumed by the key's own case.
+ */
+export function resolveSequence(chord) {
+    const name = normalizeKeyName(chord.key);
+    // Special (non-printing) keys map to a fixed escape sequence; printable keys
+    // pass through as their own character.
+    let sequence = SPECIAL_KEYS[name] ?? chord.key;
+    // Modifier parameter encoding for special (escape sequence) keys.
+    // Only applies when shift/alt/ctrl are used on a non-printing key, and only
+    // when we have a recognizable CSI/SS3 sequence to transform.
+    const isSpecial = name in SPECIAL_KEYS;
+    if (isSpecial && (chord.shift || chord.ctrl)) {
+        const mod = modParam(chord);
+        if (mod !== undefined) {
+            // SS3 form F1-F4: ESC O P/Q/R/S  →  CSI 1 ; mod P/Q/R/S
+            const ss3Letter = sequence.startsWith('\x1bO') && sequence.length === 3 ? sequence[2] : undefined;
+            if (ss3Letter && /^[A-Z]$/.test(ss3Letter)) {
+                sequence = `\x1b[1;${mod}${ss3Letter}`;
+            }
+            // Tilde-family (F5-F12, Insert, Delete, PgUp, PgDn):
+            // ESC [ N ~  →  ESC [ N ; mod ~
+            const tildeDigits = sequence.startsWith('\x1b[') && sequence.endsWith('~')
+                ? sequence.slice(2, -1)
+                : '';
+            if (/^\d+$/.test(tildeDigits)) {
+                sequence = `\x1b[${tildeDigits};${mod}~`;
+            }
+            // CSI letter form (arrows, Home, End): ESC [ <letter>
+            // →  ESC [ 1 ; mod <letter>
+            const csiLetter = sequence.startsWith('\x1b[') && sequence.length === 3 ? sequence[2] : undefined;
+            if (csiLetter && /^[A-Za-z]$/.test(csiLetter)) {
+                sequence = `\x1b[1;${mod}${csiLetter}`;
+            }
+        }
+    }
+    // Ctrl modifier — convert a single printable char to its control character.
+    // (Only runs for non-special keys — special keys were handled above.)
+    if (chord.ctrl && !isSpecial && sequence.length === 1) {
+        const code = sequence.toUpperCase().charCodeAt(0);
+        if (code >= 64 && code <= 95) {
+            // @ A-Z [ \ ] ^ _  →  0x00–0x1F (Ctrl-@ = NUL, Ctrl-A = 0x01, …).
+            sequence = String.fromCharCode(code - 64);
+        }
+        else {
+            const lowerKey = chord.key.toLowerCase();
+            if (lowerKey === 'c')
+                sequence = '\x03';
+            else if (lowerKey === 'd')
+                sequence = '\x04';
+            else if (lowerKey === 'z')
+                sequence = '\x1a';
+            else if (lowerKey === 'l')
+                sequence = '\x0c';
+        }
+    }
+    // Alt modifier — prepend ESC (meta).
+    if (chord.alt) {
+        sequence = `\x1b${sequence}`;
+    }
+    return sequence;
+}
+/**
+ * Browser-clipboard chords that must NOT be sent to the PTY.  The browser's
+ * native copy/paste handling fires *before* the keydown handler; sending a PTY
+ * sequence would prefix the pasted content with the quoted-insert byte (0x16)
+ * or duplicate a Ctrl-C SIGINT when the user is just copying text.
+ *
+ * Plain Ctrl-C is NOT in this set — it is still SIGINT (0x03).
+ */
+function isClipboardChord(chord) {
+    const key = chord.key.toLowerCase();
+    // Ctrl+V / Cmd+V / Ctrl+Shift+V — paste
+    if (key === 'v' && (chord.ctrl || chord.meta))
+        return true;
+    // Ctrl+Shift+C / Cmd+C — copy (Cmd+C is the primary macOS copy chord)
+    if (key === 'c' && chord.meta)
+        return true;
+    if (key === 'c' && chord.ctrl && chord.shift)
+        return true;
+    // Ctrl+Shift+X — cut
+    if (key === 'x' && chord.ctrl && chord.shift)
+        return true;
+    return false;
+}
+/**
+ * Map a key chord to the terminal byte sequence for the **browser** surface.
+ * Returns `null` for chords xterm.js already encodes natively (so the component
+ * lets xterm handle them) — only the gaps come back as a string:
+ *   - F1–F12 (xterm does not emit these by default),
+ *   - Modified special keys (shift/ctrl + arrows/Home/End/F-keys/Delete/…),
+ *   - Alt-<key> meta sequences,
+ *   - Ctrl-<letter> control chars,
+ *   - the `space` alias when explicitly modified.
+ *
+ * Returns `null` (never sends to PTY) for clipboard chords:
+ *   - Ctrl+V, Cmd+V, Ctrl+Shift+V (paste),
+ *   - Cmd+C, Ctrl+Shift+C (copy),
+ *   - Ctrl+Shift+X (cut).
+ *
+ * IMPORTANT: plain Ctrl+C still returns 0x03 (SIGINT).
+ *
+ * A plain printable key with no modifier returns `null` (xterm types it itself).
+ */
+export function chordToSequence(chord) {
+    const name = normalizeKeyName(chord.key);
+    // Clipboard chords must never reach the PTY.
+    if (isClipboardChord(chord))
+        return null;
+    // F-keys: xterm does not emit these by default — always supply the sequence.
+    // Also handles modified F-keys (shift+F1, ctrl+F5, etc.) via resolveSequence.
+    if (/^f([1-9]|1[0-2])$/.test(name)) {
+        const seq = resolveSequence(chord);
+        return seq.length > 0 ? seq : null;
+    }
+    // Alt always needs the ESC-prefix that xterm's default handler won't add.
+    if (chord.alt) {
+        return resolveSequence(chord);
+    }
+    // Shift or Ctrl on a native special key → modifier-parameter encoding.
+    // resolveSequence handles the ESC [ 1 ; mod <letter> / ESC [ N ; mod ~ forms.
+    if ((chord.shift || chord.ctrl) && XTERM_NATIVE_KEYS.has(name)) {
+        return resolveSequence(chord);
+    }
+    // Ctrl + a single printable letter → control char xterm may not produce.
+    if (chord.ctrl) {
+        const seq = resolveSequence(chord);
+        // Only override when we actually produced a control char (length 1, < 0x20)
+        // or a special-key sequence; otherwise let xterm decide.
+        if (seq.length === 1 && seq.charCodeAt(0) < 0x20)
+            return seq;
+        return null;
+    }
+    // Unmodified special keys xterm already handles — let it through.
+    if (XTERM_NATIVE_KEYS.has(name))
+        return null;
+    // Everything else (plain printable) — xterm types it; nothing to inject.
+    return null;
+}
+//# sourceMappingURL=keymap.js.map

package/dist/ansi/keymap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keymap.js","sourceRoot":"","sources":["../../src/ansi/keymap.ts"],"names":[],"mappings":"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"}

package/dist/api-client-plugin.d.ts

@@ -0,0 +1,4 @@
+/** Portable semantic client slice: no tool, TUI or host adapter loaders. */
+declare const terminalClientPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default terminalClientPlugin;
+//# sourceMappingURL=api-client-plugin.d.ts.map

package/dist/api-client-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client-plugin.d.ts","sourceRoot":"","sources":["../src/api-client-plugin.ts"],"names":[],"mappings":"AAIA,4EAA4E;AAC5E,QAAA,MAAM,oBAAoB,6CAUxB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/dist/api-client-plugin.js

@@ -0,0 +1,16 @@
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import { runtimeClientKind } from '@vibesdotdev/kernel/client';
+/** Portable semantic client slice: no tool, TUI or host adapter loaders. */
+const terminalClientPlugin = createRuntimePlugin({
+    id: 'terminal-client.api',
+    kinds: [runtimeClientKind],
+    descriptors: [{ kind: 'runtime/client', id: 'terminal', description: 'Terminal session and process custody' }],
+    loaders: [loader('terminal', { kind: 'runtime/client' }, () => import("./terminal-runtime.js"))],
+    async onDispose(runtime) {
+        // tryGetVibesClient intentionally refuses aborted runtimes. Teardown peeks the
+        // kernel cache while registration is still live; it never activates a client.
+        await runtime.query('runtime/client').withId('terminal').peek?.()?.dispose();
+    }
+});
+export default terminalClientPlugin;
+//# sourceMappingURL=api-client-plugin.js.map

package/dist/api-client-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client-plugin.js","sourceRoot":"","sources":["../src/api-client-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE/D,4EAA4E;AAC5E,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;IAChD,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,CAAC,iBAAiB,CAAC;IAC1B,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,sCAAsC,EAAE,CAAC;IAC9G,OAAO,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAChG,KAAK,CAAC,SAAS,CAAC,OAAO;QACtB,+EAA+E;QAC/E,8EAA8E;QAC9E,MAAM,OAAO,CAAC,KAAK,CAAwB,gBAAgB,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;IACrG,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/dist/client/http-session.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @vibesdotdev/terminal-client/client/http-session — browser ExecutionSession adapter.
+ *
+ * Implements the L3 `ExecutionSession` interface against the `/api/session/**`
+ * bridge endpoints. Works for BOTH remote fleet sessions (hq-web) and local PTY
+ * sessions (consumer-hq): both surfaces use the identical wire format.
+ *
+ *   - `onOutput` ← Server-Sent Events from `GET /api/session/{id}/output`
+ *   - `write`/`resize`/`signal`/`kill` → `POST /api/session/{id}/{verb}`
+ *   - `exited()` ← resolves when the SSE stream signals exit (or the channel ends)
+ *
+ * ### Auto-reconnect
+ *
+ * When the EventSource drops (network blip, server restart), the adapter retries
+ * transparently with jittered exponential backoff. Callers get `onReconnecting` /
+ * `onReconnected` hooks to show a UI banner. The same server-side backlog ring
+ * replays missed output on re-attach. A clean exit from the session (the server
+ * sends `event: exit`) is NOT retried — it resolves `exited()` normally.
+ *
+ * `<Terminal>` doesn't care which transport backs the session — it only ever sees
+ * an `ExecutionSession`. The SSE-error → `exited()`-reject path maps to the
+ * component's `onDisconnect` banner once retries are exhausted.
+ *
+ * BROWSER-ONLY. Depends on `fetch` and `EventSource` (both available in browsers
+ * and in Bun).
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { ExecutionSession } from '../client.ts';
+export { type ReconnectOptions, type OpenHttpSessionOptions } from '../schemas/http.ts';
+import { type OpenHttpSessionOptions } from '../schemas/http.ts';
+export interface OpenedHttpSession {
+    session: ExecutionSession;
+    id: string;
+    environmentId: string;
+}
+/**
+ * Open a terminal session over HTTP and return a browser `ExecutionSession` bound
+ * to it. Call from `onMount` (uses `EventSource` / `fetch`).
+ *
+ * Returns `{ session, id, environmentId }` so callers can inspect metadata if
+ * needed; the `session` is ready to pass to `<Terminal session={session} />`.
+ */
+export declare function openHttpSession(runtime: VibesRuntime, input: OpenHttpSessionOptions): Promise<OpenedHttpSession>;
+//# sourceMappingURL=http-session.d.ts.map

package/dist/client/http-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-session.d.ts","sourceRoot":"","sources":["../../src/client/http-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAKN,KAAK,YAAY,EACjB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAoErD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EACqD,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAcpH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,sBAAsB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAa5B"}