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

package/dist/svelte/Terminal.svelte

@@ -0,0 +1,567 @@
+<script lang="ts">
+	/**
+	 * <Terminal session={…} /> — the xterm.js rendering surface.
+	 *
+	 * Renders an L3 `ExecutionSession`'s byte stream. Transport-agnostic: the
+	 * session may be a real local PTY (L9a) or an RPC proxy (L9b) — the component
+	 * only ever sees the `ExecutionSession` interface.
+	 *
+	 * SSR safety: `@xterm/xterm` + addons are browser-only (they touch `document`
+	 * and WebGL). They are imported INSIDE `onMount` via dynamic `import()`, never
+	 * at module top-level, so this component is import-safe in a SvelteKit server
+	 * render. This also sidesteps the `*-svelte` barrel-index `$state` trap — no
+	 * eager xterm/DOM import leaks into a non-browser context.
+	 *
+	 * connectionState precedence (P6):
+	 *   The component internally derives 'live' / 'exited' from session events.
+	 *   When the `connectionState` prop is supplied by the parent (e.g. 'reconnecting',
+	 *   'reconnected', 'failed') it takes precedence over the internal derivation, so
+	 *   the parent can drive the full state machine (transport reconnect flows).
+	 */
+	import { onMount } from 'svelte';
+	import { peekRuntimeSvelteContext } from '@vibesdotdev/surface-sveltekit/svelte';
+	import { cn } from '@vibesdotdev/kit/utils';
+	import { resolveSequence, chordToSequence } from '@vibesdotdev/terminal-client/ansi';
+	import { CapabilityError, CaughtFailureSchema } from '@vibesdotdev/kernel';
+	import type { ExecutionSession } from '@vibesdotdev/kernel/execution';
+	import { DEFAULT_FONT, DEFAULT_TERMINAL_THEME, type TerminalProps } from './types.js';
+	import { TerminalSessionAuthority } from './terminal-session-authority.js';
+	import { observeTerminalAppearance, readTerminalAppearance } from './terminal-theme.js';
+	import ReconnectBanner from './ReconnectBanner.svelte';
+	import TerminalMobileToolbar from './TerminalMobileToolbar.svelte';
+
+	/**
+	 * Connection state values driven externally or derived internally.
+	 *  connecting   — xterm not yet mounted (boot async in progress)
+	 *  live         — session active, no banner
+	 *  reconnecting — transport dropped, retry in progress
+	 *  reconnected  — transport restored (auto-dismissed by caller)
+	 *  failed       — unrecoverable transport drop
+	 *  exited       — shell process exited cleanly
+	 */
+	export type ConnectionState =
+		'connecting' | 'live' | 'reconnecting' | 'reconnected' | 'failed' | 'exited';
+
+	interface ExtendedProps extends TerminalProps {
+		/**
+		 * External connection state override. When provided it takes precedence
+		 * over the component's internally-derived state (live / exited).
+		 * Defaults to 'connecting' on first render.
+		 */
+		connectionState?: ConnectionState;
+		/** Called when the user clicks "Start new session" in failed/exited state. */
+		onNewSession?: () => void;
+	}
+
+	let {
+		session = null,
+		onReady,
+		onInputReady,
+		theme,
+		font,
+		class: className = '',
+		onExit,
+		onDisconnect,
+		readonly = false,
+		connectionState: externalConnectionState,
+		onNewSession,
+		cols: lockedCols,
+		rows: lockedRows
+	}: ExtendedProps = $props();
+
+	function lockedGrid(): { cols: number; rows: number } | null {
+		const cols = Number(lockedCols);
+		const rows = Number(lockedRows);
+		if (Number.isInteger(cols) && cols > 0 && Number.isInteger(rows) && rows > 0) {
+			return { cols, rows };
+		}
+		return null;
+	}
+
+	let host = $state<HTMLDivElement | null>(null);
+
+	/**
+	 * Internal derived state — updated from session lifecycle events.
+	 * 'connecting' until xterm boots, then 'live', then 'exited'/'disconnected'.
+	 */
+	let internalState = $state<'connecting' | 'live' | 'exited' | 'disconnected'>('connecting');
+	let internalDetail = $state<string>('');
+	let rendererFallback = $state<string>('');
+
+	/**
+	 * Effective connection state — external prop wins when present.
+	 * See file-level docblock for precedence rules.
+	 */
+	const effectiveState = $derived<ConnectionState>(
+		externalConnectionState !== undefined
+			? externalConnectionState
+			: internalState === 'disconnected'
+				? 'failed'
+				: internalState
+	);
+
+	/**
+	 * Map effectiveState to the ReconnectBanner status slot.
+	 * null → banner hidden (live / connecting).
+	 */
+	const bannerStatus = $derived.by<'reconnecting' | 'reconnected' | 'failed' | null>(() => {
+		switch (effectiveState) {
+			case 'reconnecting':
+				return 'reconnecting';
+			case 'reconnected':
+				return 'reconnected';
+			case 'failed':
+				return 'failed';
+			case 'exited':
+				return 'failed'; // exited reuses the failed slot with a distinct message
+			default:
+				return null;
+		}
+	});
+
+	/**
+	 * Human-readable failure/exit reason forwarded to the banner.
+	 */
+	const bannerReason = $derived.by<string>(() => {
+		if (effectiveState === 'exited') {
+			return 'Session ended — the shell stopped running.';
+		}
+		if (effectiveState === 'failed') {
+			return internalDetail
+				? `Connection lost — ${internalDetail}`
+				: 'Connection lost and could not be restored.';
+		}
+		return '';
+	});
+
+	/** Whether the state calls for a "Start new session" button. */
+	const bannerShowAction = $derived<boolean>(
+		effectiveState === 'failed' || effectiveState === 'exited'
+	);
+
+	let appearance = $state({
+		theme: { ...DEFAULT_TERMINAL_THEME },
+		fontFamily: DEFAULT_FONT.family
+	});
+	const mergedTheme = $derived({ ...appearance.theme, ...theme });
+	const fontFamily = $derived(font?.family ?? appearance.fontFamily);
+	const fontSize = $derived(font?.size ?? DEFAULT_FONT.size);
+	let refit: (() => void) | null = null;
+	let mobileCtrl = $state(false);
+	let mobileAlt = $state(false);
+
+	const encoder = new TextEncoder();
+	const runtimeStore = peekRuntimeSvelteContext();
+
+	/**
+	 * The xterm instance once booted, and the session currently wired to it.
+	 * Input paths (onData / key chords / onResize) are registered ONCE at boot
+	 * and route through `sessionAuthority` so a session can attach late or be
+	 * swapped without re-registering xterm handlers.
+	 */
+	let xterm = $state<import('@xterm/xterm').Terminal | null>(null);
+	const sessionAuthority = new TerminalSessionAuthority<ExecutionSession>();
+	let detachActiveSession: (() => void) | null = null;
+
+	onMount(() => {
+		// All xterm imports are deferred to the browser. Cleanup is registered as
+		// teardown handles inside the async boot; onMount's returned disposer drains
+		// them whether or not boot finished.
+		let disposed = false;
+		const teardown: Array<() => void> = [];
+		const observeUiTask = (task: Promise<void>): void => {
+			void task
+				.then(
+					() => ({ kind: 'complete' as const }),
+					(cause) => ({
+						kind: 'failure' as const,
+						failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+					})
+				)
+				.then((outcome) => {
+					if (outcome.kind === 'complete' || disposed) return;
+					internalState = 'disconnected';
+					internalDetail = outcome.failure.message;
+					onDisconnect?.(outcome.failure.message);
+				});
+		};
+		const runTeardown = (dispose: () => void) => {
+			try {
+				dispose();
+				return { kind: 'complete' as const };
+			} catch (cause) {
+				return {
+					kind: 'failure' as const,
+					failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+				};
+			}
+		};
+
+		const boot = async () => {
+			const { Terminal } = await import('@xterm/xterm');
+			const { FitAddon } = await import('@xterm/addon-fit');
+			await import('@xterm/xterm/css/xterm.css');
+
+			if (disposed || !host) return;
+			appearance = readTerminalAppearance(host);
+			teardown.push(
+				observeTerminalAppearance(host, () => {
+					if (host) appearance = readTerminalAppearance(host);
+				})
+			);
+
+			const term = new Terminal({
+				cursorBlink: true,
+				minimumContrastRatio: 4.5,
+				allowProposedApi: true,
+				// Start immediately with native metrics while an edge font is downloading.
+				// The font effect switches families after loading, invalidating xterm's metrics.
+				fontFamily: document.fonts.check(`${fontSize}px ${fontFamily}`) ? fontFamily : 'monospace',
+				fontSize,
+				theme: mergedTheme,
+				scrollback: 5000
+			});
+
+			const fit = new FitAddon();
+			term.loadAddon(fit);
+			term.open(host);
+
+			// P1 AUTOFOCUS — focus the terminal after mount, but only when the
+			// current active element is not an input/textarea/contenteditable outside
+			// the terminal. This eliminates the "click first to type" dead zone while
+			// respecting pre-existing focus (e.g. a form field the user is editing).
+			if (!disposed && host) {
+				const active = document.activeElement;
+				const isExternalInput =
+					active instanceof HTMLElement &&
+					!host.contains(active) &&
+					(active.tagName === 'INPUT' || active.tagName === 'TEXTAREA' || active.isContentEditable);
+				if (!isExternalInput) {
+					term.focus();
+				}
+			}
+
+			// P7 FIT/PADDING — run initial fit AFTER flex layout settles via rAF.
+			// The surface has no padding (moved to a CSS wrapper) so FitAddon
+			// measures the full content box. A follow-up rAF ensures the browser
+			// has completed its layout pass before we ask for cols/rows.
+			const applyFit = () => {
+				if (disposed) return;
+				const lock = lockedGrid();
+				if (lock) term.resize(lock.cols, lock.rows);
+				else if (host && host.clientWidth > 0 && host.clientHeight > 0) fit.fit();
+			};
+			refit = applyFit;
+			teardown.push(() => {
+				refit = null;
+			});
+			const fontsLoaded = () => {
+				// xterm caches metrics even when a face arrives later under the same name.
+				// A public font option change remeasures cells and rebuilds the glyph atlas.
+				const family = term.options.fontFamily;
+				term.options.fontFamily = 'monospace';
+				term.options.fontFamily = family;
+				applyFit();
+			};
+			document.fonts?.addEventListener('loadingdone', fontsLoaded);
+			teardown.push(() => document.fonts?.removeEventListener('loadingdone', fontsLoaded));
+
+			// Initial fit: wait one animation frame for flex to settle, then report
+			// the fitted grid via onReady so the parent opens its session at the
+			// RIGHT size from the start. No boot-time PTY resize happens this way —
+			// crucial because Bun TUI children cache process.stdout.columns and
+			// never observe a post-boot resize.
+			//
+			// P8 RENDERER-BEFORE-FIT — the WebGL renderer must attach BEFORE the
+			// initial fit so fit-time cell metrics equal render-time metrics. The
+			// DOM renderer measures a wider cell (~7.95px at the default font)
+			// than WebGL renders (~7.0px); a fit taken against the DOM renderer
+			// under-reports cols, and because the PTY grid is fixed at the onReady
+			// size (no post-boot resize, see above) every route then shows a
+			// permanent dead band on the right. WebGL stays an optional
+			// enhancement, never a readiness dependency: the import is raced
+			// against a short timeout and any failure (no GPU, context refused,
+			// chunk stall) falls back to the default renderer, whose metrics the
+			// fit below then measures correctly. A late-arriving WebGL module is
+			// deliberately NOT loaded after the fit — that would reintroduce the
+			// exact metric mismatch this ordering exists to prevent.
+			const prepareRenderer = async () => {
+				if (disposed) return;
+				const loadRenderer = async () => {
+					// Standalone renderers need only a session. An enclosing runtime owns
+					// the optional GPU enhancement's deadline and cancellation when present.
+					if (!runtimeStore) return null;
+					const runtime = await runtimeStore.load();
+					return runtime.lifecycle.wait(() => import('@xterm/addon-webgl'), {
+						timeoutMs: 1000, reason: 'optional terminal renderer'
+					});
+				};
+				const renderer = await loadRenderer()
+					.then(
+						(module) => ({ kind: 'available' as const, module }),
+						(cause) => ({
+							kind: 'unavailable' as const,
+							failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+						})
+					);
+				if (renderer.kind === 'unavailable') {
+					rendererFallback = renderer.failure.message;
+				} else if (!disposed && renderer.module) {
+						const webgl = new renderer.module.WebglAddon();
+						webgl.onContextLoss(() => {
+							webgl.dispose();
+						});
+						term.loadAddon(webgl);
+						teardown.push(() => webgl.dispose());
+				}
+				if (disposed) return;
+				applyFit();
+				onReady?.({ cols: term.cols, rows: term.rows });
+			};
+			requestAnimationFrame(() => {
+				observeUiTask(prepareRenderer());
+			});
+
+			// --- Data path: xterm input → PTY (routes via session authority so the
+			// session may attach late or be swapped without re-registering) -------
+			// READ-ONLY GATE: when `readonly` is set, keystrokes are NOT forwarded to
+			// the PTY — the terminal renders output only (observe mode). The prop is
+			// read live inside the handler so toggling it takes effect without
+			// re-registering xterm handlers.
+			const onDataDisposable = term.onData((data: string) => {
+				if (readonly) return;
+				const input = data.length === 1 && (mobileCtrl || mobileAlt)
+					? resolveSequence({ key: data, ctrl: mobileCtrl, alt: mobileAlt }) : data;
+				mobileCtrl = false;
+				mobileAlt = false;
+				sessionAuthority.current?.write(encoder.encode(input));
+			});
+			teardown.push(() => onDataDisposable.dispose());
+
+			// --- Non-printing keys via the extracted key-map --------------------
+			// P4 NULL-SAFETY: chordToSequence may return null to mean "let the browser
+			// handle this key natively" (e.g. Ctrl/Cmd+V for paste). When it returns
+			// null we must NOT call session.write and must NOT preventDefault — return
+			// true so xterm passes the event to the browser.
+			term.attachCustomKeyEventHandler((ev: KeyboardEvent) => {
+				if (ev.type !== 'keydown') return true;
+				// READ-ONLY GATE: don't consume or forward any chord — let the browser
+				// handle it natively (selection, copy, etc.) and never write to the PTY.
+				if (readonly) return true;
+				const seq = chordToSequence({
+					key: ev.key,
+					ctrl: ev.ctrlKey,
+					alt: ev.altKey,
+					shift: ev.shiftKey
+				});
+				// null → browser-native behavior (clipboard paste, etc.) — do not consume.
+				if (seq === null) return true;
+				sessionAuthority.current?.write(encoder.encode(seq));
+				return false; // we owned this key
+			});
+
+			// --- Resize: FitAddon → PTY -----------------------------------------
+			const onResizeDisposable = term.onResize(({ cols, rows }) => {
+				// Propagate fitted cols/rows to the session resize callback.
+				sessionAuthority.current?.resize(cols, rows);
+			});
+			teardown.push(() => onResizeDisposable.dispose());
+
+			// P7 ResizeObserver-driven refit — reuses the existing observer pattern.
+			// The observer fires on every layout change so cols/rows always track
+			// the container; the onResize handler above forwards them to the PTY.
+			const ro = new ResizeObserver(() => applyFit());
+			if (host) {
+				ro.observe(host);
+				teardown.push(() => ro.disconnect());
+			}
+
+			teardown.push(() => term.dispose());
+
+			// Publish the booted instance — the $effect below attaches the session
+			// (output stream, exit watcher, input-ready flag) when both exist.
+			xterm = term;
+			teardown.push(() => {
+				detachActiveSession?.();
+				detachActiveSession = null;
+				sessionAuthority.detach();
+				xterm = null;
+			});
+		};
+		observeUiTask(boot());
+
+		return () => {
+			disposed = true;
+			for (const fn of teardown.splice(0)) {
+				const outcome = runTeardown(fn);
+				if (outcome.kind === 'failure') rendererFallback = outcome.failure.message;
+			}
+		};
+	});
+
+	$effect(() => {
+		if (!xterm) return;
+		xterm.options.theme = mergedTheme;
+	});
+
+	$effect(() => {
+		const term = xterm;
+		const family = fontFamily;
+		const size = fontSize;
+		if (!term || (term.options.fontFamily === family && term.options.fontSize === size)) return;
+		let cancelled = false;
+		const apply = () => {
+			if (cancelled) return;
+			term.options.fontFamily = family;
+			term.options.fontSize = size;
+			refit?.();
+		};
+		// Measure after the face loads; failed downloads still use the browser fallback.
+		void document.fonts
+			.load(`${size}px ${family}`)
+			.then(
+				() => ({ kind: 'loaded' as const }),
+				(cause) => ({
+					kind: 'fallback' as const,
+					failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+				})
+			)
+			.then((outcome) => {
+				if (outcome.kind === 'fallback') rendererFallback = outcome.failure.message;
+				apply();
+			});
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	// Attach/detach the session to the booted xterm. Runs when either the
+	// session prop or the xterm instance becomes available; supports a session
+	// arriving after boot (the onReady → open-at-fitted-size flow).
+	$effect(() => {
+		const term = xterm;
+		const s = session;
+		if (!term) return;
+		if (!s) {
+			detachActiveSession?.();
+			detachActiveSession = null;
+			sessionAuthority.detach();
+			return;
+		}
+		if (s === sessionAuthority.current) return;
+
+		detachActiveSession?.();
+		detachActiveSession = null;
+		const attachment = sessionAuthority.attach(s);
+
+		// --- Data path: PTY output → xterm ----------------------------------
+		const decoder = new TextDecoder();
+		const unsubscribeOutput = s.onOutput((bytes: Uint8Array) => {
+			// xterm.write accepts string or Uint8Array; we decode so multibyte
+			// and escape sequences survive intact (PTY stream is raw bytes).
+			term.write(decoder.decode(bytes, { stream: true }));
+		});
+
+		// Align the PTY with the current grid. When the parent opened the session
+		// at the onReady dimensions this is a no-op server-side; it only matters
+		// if the layout changed between open and attach.
+		s.resize(term.cols, term.rows);
+
+		internalState = 'live';
+
+		// Signal to test harnesses that the input path is fully wired END-TO-END
+		// (xterm onData registered at boot AND a session attached) so keystrokes
+		// typed on this flag are guaranteed to reach the PTY. The buffer reader
+		// is for tui:shot / Playwright waits: WebGL paints to a canvas, so
+		// `.xterm-screen` innerText is empty.
+		Reflect.set(window, '__vibesTerminalInputReady', true);
+		Reflect.set(window, '__vibesReadTerminalBuffer', () => {
+				const buf = term.buffer.active;
+				const lines: string[] = [];
+				for (let i = 0; i < buf.length; i++) {
+					lines.push(buf.getLine(i)?.translateToString(true) ?? '');
+				}
+				return lines.join('\n');
+			});
+		onInputReady?.();
+
+		// --- Lifecycle: exit + disconnect -----------------------------------
+		void s.exited()
+			.then(
+				(result) => ({ kind: 'exit' as const, result }),
+				(cause) => ({
+					kind: 'failure' as const,
+					failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+				})
+			)
+			.then((outcome) => {
+				if (!sessionAuthority.isCurrent(attachment)) return;
+				if (outcome.kind === 'failure') {
+					internalState = 'disconnected';
+					internalDetail = outcome.failure.message;
+					onDisconnect?.(outcome.failure.message);
+					return;
+				}
+				const { result } = outcome;
+				internalState = 'exited';
+				internalDetail =
+					result.exitCode === null
+						? 'process terminated'
+						: `process exited (code ${result.exitCode})`;
+				onExit?.(result);
+			});
+
+		detachActiveSession = () => {
+			unsubscribeOutput();
+			Reflect.deleteProperty(window, '__vibesTerminalInputReady');
+			Reflect.deleteProperty(window, '__vibesReadTerminalBuffer');
+			sessionAuthority.detach(s);
+		};
+	});
+</script>
+
+<div
+	class={cn('relative flex h-full min-h-0 w-full flex-col overflow-hidden rounded-md', className)}
+	style:background={mergedTheme.background}
+>
+	<!-- P6 F3 loading skeleton — shown while xterm is booting (connectionState='connecting') -->
+	{#if effectiveState === 'connecting'}
+		<div
+			class="absolute inset-0 z-10 flex items-center justify-start gap-2 px-3.5 py-3 font-mono text-xs text-muted-foreground"
+			role="status"
+			aria-label="Connecting…"
+		>
+			<span
+				class="size-2 shrink-0 animate-pulse rounded-full bg-muted-foreground"
+				aria-hidden="true"
+			></span>
+			<span class="animate-pulse">connecting…</span>
+		</div>
+	{/if}
+
+	<!-- xterm host — always in DOM so xterm can attach; invisible during connecting -->
+	<div
+		class={cn('min-h-0 w-full flex-1', effectiveState === 'connecting' ? 'invisible' : '')}
+		bind:this={host}
+	></div>
+
+	{#if !readonly}
+		<TerminalMobileToolbar
+			class="sm:hidden"
+			bind:ctrlActive={mobileCtrl}
+			bind:altActive={mobileAlt}
+			disabled={effectiveState !== 'live' || !session}
+			onInput={sequence => sessionAuthority.current?.write(encoder.encode(sequence))}
+		/>
+	{/if}
+
+	<!-- P6 ReconnectBanner replaces the old inline banner -->
+	<ReconnectBanner
+		status={bannerStatus}
+		reason={bannerReason}
+		onNewSession={bannerShowAction ? onNewSession : undefined}
+	/>
+	{#if rendererFallback}
+		<span class="sr-only" aria-live="polite">Optional terminal renderer unavailable.</span>
+	{/if}
+</div>

package/dist/svelte/Terminal.svelte.d.ts

@@ -0,0 +1,25 @@
+import { type TerminalProps } from './types.ts';
+/**
+ * Connection state values driven externally or derived internally.
+ *  connecting   — xterm not yet mounted (boot async in progress)
+ *  live         — session active, no banner
+ *  reconnecting — transport dropped, retry in progress
+ *  reconnected  — transport restored (auto-dismissed by caller)
+ *  failed       — unrecoverable transport drop
+ *  exited       — shell process exited cleanly
+ */
+export type ConnectionState = 'connecting' | 'live' | 'reconnecting' | 'reconnected' | 'failed' | 'exited';
+interface ExtendedProps extends TerminalProps {
+    /**
+     * External connection state override. When provided it takes precedence
+     * over the component's internally-derived state (live / exited).
+     * Defaults to 'connecting' on first render.
+     */
+    connectionState?: ConnectionState;
+    /** Called when the user clicks "Start new session" in failed/exited state. */
+    onNewSession?: () => void;
+}
+declare const Terminal: import("svelte").Component<ExtendedProps, {}, "">;
+type Terminal = ReturnType<typeof Terminal>;
+export default Terminal;
+//# sourceMappingURL=Terminal.svelte.d.ts.map

package/dist/svelte/Terminal.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Terminal.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/Terminal.svelte.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAwC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAOrF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAC1B,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9E,UAAU,aAAc,SAAQ,aAAa;IAC5C;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AA6fF,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}