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

package/dist/server/sse-stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @vibesdotdev/terminal-client — SSE stream builder for terminal output.
+ *
+ * Builds the `ReadableStream<Uint8Array>` body for `GET /api/session/{id}/output`.
+ * Used by both hq-web (remote PTY) and consumer-hq (local PTY): the wire format is
+ * identical regardless of what backs the session.
+ *
+ * Wire format:
+ *   event: data\ndata: <base64>\n\n   — a chunk of PTY output
+ *   event: exit\ndata: {"exitCode":N|null}\n\n  — session exited (final event)
+ *
+ * SERVER-ONLY.
+ */
+import { base64ToBytes, bytesToBase64 } from '../pty-bridge/protocol.ts';
+import type { StoredSession } from './session-store.ts';
+export declare const toBase64: typeof bytesToBase64;
+export declare const fromBase64: typeof base64ToBytes;
+/**
+ * Build an SSE `ReadableStream` for a session's PTY output.
+ *
+ * Replays any backlog that arrived before this stream attached (so a
+ * slightly-late EventSource connection sees the shell prompt), then streams
+ * live output. A final `exit` event closes the stream.
+ */
+export declare function buildSseStream(stored: StoredSession): ReadableStream<Uint8Array>;
+/** Standard SSE response headers. */
+export declare const SSE_HEADERS: {
+    'content-type': string;
+    'cache-control': string;
+    connection: string;
+};
+//# sourceMappingURL=sse-stream.d.ts.map

package/dist/server/sse-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream.d.ts","sourceRoot":"","sources":["../../src/server/sse-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACN,aAAa,EACb,aAAa,EACb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,eAAO,MAAM,QAAQ,sBAAgB,CAAC;AACtC,eAAO,MAAM,UAAU,sBAAgB,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC,CAwDhF;AAED,qCAAqC;AACrC,eAAO,MAAM,WAAW;;;;CAIU,CAAC"}

package/dist/server/sse-stream.js

@@ -0,0 +1,87 @@
+/**
+ * @vibesdotdev/terminal-client — SSE stream builder for terminal output.
+ *
+ * Builds the `ReadableStream<Uint8Array>` body for `GET /api/session/{id}/output`.
+ * Used by both hq-web (remote PTY) and consumer-hq (local PTY): the wire format is
+ * identical regardless of what backs the session.
+ *
+ * Wire format:
+ *   event: data\ndata: <base64>\n\n   — a chunk of PTY output
+ *   event: exit\ndata: {"exitCode":N|null}\n\n  — session exited (final event)
+ *
+ * SERVER-ONLY.
+ */
+import { CapabilityError, CaughtFailureSchema } from '@vibesdotdev/kernel';
+import { base64ToBytes, bytesToBase64 } from "../pty-bridge/protocol.js";
+// ---------------------------------------------------------------------------
+// Base64 helpers (shared with the client adapter in ../client/http-session.ts)
+// ---------------------------------------------------------------------------
+export const toBase64 = bytesToBase64;
+export const fromBase64 = base64ToBytes;
+/**
+ * Build an SSE `ReadableStream` for a session's PTY output.
+ *
+ * Replays any backlog that arrived before this stream attached (so a
+ * slightly-late EventSource connection sees the shell prompt), then streams
+ * live output. A final `exit` event closes the stream.
+ */
+export function buildSseStream(stored) {
+    const encoder = new TextEncoder();
+    let closed = false;
+    let unsubscribe = () => { };
+    return new ReadableStream({
+        start(controller) {
+            const send = (eventName, data) => {
+                if (closed)
+                    return;
+                controller.enqueue(encoder.encode(`event: ${eventName}\ndata: ${data}\n\n`));
+            };
+            // Flush headers immediately, including for a quiet PTY with no backlog.
+            controller.enqueue(encoder.encode(': connected\n\n'));
+            // Replay backlog captured before this stream attached.
+            for (const chunk of stored.backlog)
+                send('data', toBase64(chunk));
+            unsubscribe = stored.session.onOutput((bytes) => {
+                send('data', toBase64(bytes));
+            });
+            const finish = (exitCode) => {
+                if (closed)
+                    return;
+                send('exit', JSON.stringify({ exitCode }));
+                closed = true;
+                unsubscribe();
+                controller.close();
+            };
+            const fail = (failure) => {
+                if (closed)
+                    return;
+                send('failure', JSON.stringify(failure.toEnvelope().error));
+                closed = true;
+                unsubscribe();
+                controller.close();
+            };
+            void stored.session.exited()
+                .then(({ exitCode }) => ({ kind: 'exit', exitCode }), (cause) => ({
+                kind: 'failure',
+                failure: CapabilityError.from(CaughtFailureSchema.parse(cause))
+            }))
+                .then((outcome) => {
+                if (outcome.kind === 'exit')
+                    finish(outcome.exitCode);
+                else
+                    fail(outcome.failure);
+            });
+        },
+        cancel() {
+            closed = true;
+            unsubscribe();
+        }
+    });
+}
+/** Standard SSE response headers. */
+export const SSE_HEADERS = {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive'
+};
+//# sourceMappingURL=sse-stream.js.map

package/dist/server/sse-stream.js.map

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

package/dist/svelte/HostPicker.svelte

@@ -0,0 +1,263 @@
+<script lang="ts">
+	/**
+	 * <HostPicker> — host + shell picker for the terminal surface.
+	 *
+	 * Presents the list of reachable hosts (consumer: "This machine" always first;
+	 * cloud: fleet hosts). The user picks a host and an optional command, then
+	 * clicks "Open". Deep-linked ?host= preselects a host by id.
+	 *
+	 * When no hosts are available the empty state explains why and offers a
+	 * link to add a machine — it is never a dead end.
+	 *
+	 * Keyboard-first: focus opens the host list; Enter/Space selects; Tab moves
+	 * between host, command, and Open; Escape closes.
+	 */
+
+	import { Button } from '@vibesdotdev/kit/components/ui/button';
+	import { Input } from '@vibesdotdev/kit/components/ui/input';
+	import { cn } from '@vibesdotdev/kit/utils';
+	import type { HostOption } from './types.js';
+
+	interface Props {
+		/**
+		 * Ordered list of available hosts. The first entry with `local: true` is
+		 * "This machine" in consumer-hq; cloud hosts follow in alphabetical order.
+		 */
+		hosts: HostOption[];
+		/** Pre-selected host id (from ?host= deep-link). */
+		preselectedHostId?: string;
+		/** Shown in the command field as placeholder when unset. */
+		defaultCommand?: string;
+		/**
+		 * Pre-fill the command input with this value VERBATIM (from a ?command=
+		 * deep-link). The field stays fully editable and is NEVER auto-run — the
+		 * user must still click "Open terminal". Empty/undefined leaves the field
+		 * blank (placeholder = defaultCommand). Non-breaking: omitting it preserves
+		 * the prior empty-field behavior.
+		 */
+		initialCommand?: string;
+		/** Href of the add-machine flow (shown when hosts array is empty). */
+		addMachineHref?: string;
+		/**
+		 * Allow opening with a blank command. `onOpen` then receives `''`, which
+		 * the caller treats as "the host's default shell". Defaults to false
+		 * (a blank field resolves to `defaultCommand`).
+		 */
+		allowDefaultShell?: boolean;
+		/** Called when the user confirms their selection. */
+		onOpen: (hostId: string, command: string) => void;
+		/** Called when the user presses Escape or dismisses. */
+		onCancel?: () => void;
+	}
+
+	let {
+		hosts,
+		preselectedHostId,
+		defaultCommand = 'sh',
+		initialCommand = '',
+		addMachineHref = '/fleet',
+		allowDefaultShell = false,
+		onOpen,
+		onCancel
+	}: Props = $props();
+
+	// Use a derived to compute the default selection from props, then allow the
+	// user to override it with a local $state. This avoids the Svelte 5 warning
+	// about $state referencing props directly in the initializer.
+	const _defaultSelectedId = $derived(
+		preselectedHostId && hosts.some((h) => h.id === preselectedHostId)
+			? preselectedHostId
+			: (hosts[0]?.id ?? '')
+	);
+	let _manualSelection = $state<string | null>(null);
+	const selectedHostId = $derived(_manualSelection ?? _defaultSelectedId);
+	// Pre-fill verbatim from initialCommand; the field stays editable and is never
+	// auto-run (the user must click Open). The closure marks this as an
+	// intentional one-time capture for Svelte's rune analyzer.
+	const initialCommandValue = (() => initialCommand)();
+	let command = $state(initialCommandValue);
+	let commandEl = $state<HTMLInputElement | null>(null);
+
+	const selectedHost = $derived(hosts.find((h) => h.id === selectedHostId) ?? null);
+	const resolvedCommand = $derived(command.trim() || (allowDefaultShell ? '' : defaultCommand));
+	const canOpen = $derived(selectedHost !== null && (allowDefaultShell || resolvedCommand.length > 0));
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') {
+			e.preventDefault();
+			onCancel?.();
+		}
+	}
+
+	function handleOpen() {
+		if (!canOpen) return;
+		onOpen(selectedHostId, resolvedCommand);
+	}
+
+	function selectHost(id: string) {
+		_manualSelection = id;
+		// Move focus to command field after host selection so the user can
+		// proceed without touching the mouse.
+		commandEl?.focus();
+	}
+
+	function hostLabel(host: HostOption): string {
+		if (host.local) return `This machine — ${host.name}`;
+		return host.name;
+	}
+
+	function hostOptionId(hostId: string): string {
+		return `host-opt-${encodeURIComponent(hostId)}`;
+	}
+
+	function hostStatusLabel(host: HostOption): string {
+		if (host.status === 'online') return 'Online';
+		if (host.status === 'degraded') return 'Limited connection';
+		if (host.status === 'offline') return 'Offline';
+		return 'Status unknown';
+	}
+
+	function hostClass(host: HostOption): string {
+		return cn(
+			'flex cursor-pointer items-center gap-2.5 rounded-md border border-transparent px-3 py-2.5 outline-none transition-colors hover:border-border hover:bg-accent/60 focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50',
+			host.id === selectedHostId && 'border-primary bg-primary/10 text-foreground',
+			host.status === 'offline' && 'opacity-60'
+		);
+	}
+
+	function statusDotClass(status: HostOption['status']): string {
+		return cn(
+			'size-2 shrink-0 rounded-full bg-muted-foreground',
+			status === 'online' && 'bg-success',
+			status === 'degraded' && 'bg-warning',
+			status === 'offline' && 'bg-muted-foreground/70'
+		);
+	}
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+	class="w-full max-w-lg rounded-md border border-border bg-card p-5 text-sm text-card-foreground outline-none"
+	role="dialog"
+	aria-modal="true"
+	aria-label="Open a terminal session"
+	tabindex="-1"
+	onkeydown={handleKeydown}
+>
+	<div class="mb-4 flex items-center justify-between gap-3">
+		<h2 class="m-0 text-base font-semibold text-card-foreground">Open a terminal</h2>
+		{#if onCancel}
+			<Button
+				variant="ghost"
+				size="icon-sm"
+				class="size-6 text-muted-foreground hover:text-foreground"
+				aria-label="Cancel"
+				onclick={onCancel}
+			>×</Button>
+		{/if}
+	</div>
+
+	{#if hosts.length === 0}
+		<!-- Empty state: never a dead end — offer the add-machine flow -->
+		<div class="flex flex-col items-center gap-2 py-6 text-center">
+			<div class="text-muted-foreground" aria-hidden="true">
+				<svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+					<rect x="2" y="3" width="20" height="14" rx="2"/>
+					<path d="M8 21h8M12 17v4"/>
+
+				</svg>
+			</div>
+			<p class="m-0 text-sm font-medium text-foreground">No machines connected</p>
+			<p class="m-0 max-w-sm text-sm leading-normal text-muted-foreground">
+				Add a machine to open a remote terminal. The setup takes under a minute.
+			</p>
+			<Button variant="outline" size="sm" href={addMachineHref} class="mt-2">
+				Add a machine →
+			</Button>
+		</div>
+	{:else}
+		<div class="mb-4">
+			<span class="mb-2 flex items-center gap-1.5 text-xs font-semibold uppercase text-muted-foreground" id="host-list-label">Machine</span>
+			<ul
+				class="flex max-h-44 list-none flex-col gap-1 overflow-y-auto p-0"
+				role="listbox"
+				tabindex="0"
+				aria-labelledby="host-list-label"
+				aria-activedescendant={selectedHost ? hostOptionId(selectedHost.id) : undefined}
+			>
+				{#each hosts as host (host.id)}
+					<li
+						id={hostOptionId(host.id)}
+						class={hostClass(host)}
+						role="option"
+						aria-selected={host.id === selectedHostId}
+						tabindex={host.id === selectedHostId ? 0 : -1}
+						onclick={() => selectHost(host.id)}
+						onkeydown={(e) => {
+							if (e.key === 'Enter' || e.key === ' ') {
+								e.preventDefault();
+								selectHost(host.id);
+							}
+						}}
+					>
+						<span
+							class={statusDotClass(host.status)}
+							aria-label={hostStatusLabel(host)}
+							title={hostStatusLabel(host)}
+						></span>
+						<span class="min-w-0 flex-1 truncate font-medium">{hostLabel(host)}</span>
+						{#if host.id === selectedHostId}
+							<span class="shrink-0 text-primary" aria-hidden="true">✓</span>
+						{/if}
+					</li>
+				{/each}
+			</ul>
+		</div>
+
+		<div class="mb-4">
+			<label class="mb-2 flex items-center gap-1.5 text-xs font-semibold uppercase text-muted-foreground" for="picker-command">
+				Command
+				<span class="font-normal normal-case text-muted-foreground/80">optional — defaults to your shell</span>
+			</label>
+			<Input
+				id="picker-command"
+				bind:ref={commandEl}
+				type="text"
+				bind:value={command}
+				placeholder={defaultCommand}
+				class="font-mono"
+				autocomplete="off"
+				autocorrect="off"
+				autocapitalize="off"
+				spellcheck={false}
+				onkeydown={(e) => {
+					if (e.key === 'Enter') {
+						e.preventDefault();
+						handleOpen();
+					}
+				}}
+			/>
+		</div>
+
+		{#if selectedHost && selectedHost.status === 'offline'}
+			<p class="mb-4 rounded-md border border-warning/40 bg-warning/10 px-3 py-2 text-xs text-warning" role="alert">
+				This machine appears offline. You can still try to connect — it may recover.
+			</p>
+		{/if}
+
+		<div class="flex justify-end gap-2">
+			{#if onCancel}
+				<Button variant="outline" size="sm" onclick={onCancel}>
+					Cancel
+				</Button>
+			{/if}
+			<Button
+				size="sm"
+				disabled={!canOpen}
+				onclick={handleOpen}
+			>
+				Open terminal
+			</Button>
+		</div>
+	{/if}
+</div>

package/dist/svelte/HostPicker.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { HostOption } from './types.ts';
+interface Props {
+    /**
+     * Ordered list of available hosts. The first entry with `local: true` is
+     * "This machine" in consumer-hq; cloud hosts follow in alphabetical order.
+     */
+    hosts: HostOption[];
+    /** Pre-selected host id (from ?host= deep-link). */
+    preselectedHostId?: string;
+    /** Shown in the command field as placeholder when unset. */
+    defaultCommand?: string;
+    /**
+     * Pre-fill the command input with this value VERBATIM (from a ?command=
+     * deep-link). The field stays fully editable and is NEVER auto-run — the
+     * user must still click "Open terminal". Empty/undefined leaves the field
+     * blank (placeholder = defaultCommand). Non-breaking: omitting it preserves
+     * the prior empty-field behavior.
+     */
+    initialCommand?: string;
+    /** Href of the add-machine flow (shown when hosts array is empty). */
+    addMachineHref?: string;
+    /**
+     * Allow opening with a blank command. `onOpen` then receives `''`, which
+     * the caller treats as "the host's default shell". Defaults to false
+     * (a blank field resolves to `defaultCommand`).
+     */
+    allowDefaultShell?: boolean;
+    /** Called when the user confirms their selection. */
+    onOpen: (hostId: string, command: string) => void;
+    /** Called when the user presses Escape or dismisses. */
+    onCancel?: () => void;
+}
+declare const HostPicker: import("svelte").Component<Props, {}, "">;
+type HostPicker = ReturnType<typeof HostPicker>;
+export default HostPicker;
+//# sourceMappingURL=HostPicker.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HostPicker.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/HostPicker.svelte.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG5C,UAAU,KAAK;IACd;;;OAGG;IACH,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qDAAqD;IACrD,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAiLF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/svelte/README.md

@@ -0,0 +1,75 @@
+# @vibesdotdev/terminal-client/svelte
+
+Svelte 5 terminal surfaces over the canonical `runtime/execution` contract.
+
+`Terminal` renders an injected `ExecutionSession`. `TerminalWorkspace` resolves
+an execution provider, creates the real session, and reports its lifecycle.
+
+```svelte
+<script lang="ts">
+	import TerminalWorkspace from '@vibesdotdev/terminal-client/svelte/TerminalWorkspace.svelte';
+</script>
+
+<TerminalWorkspace
+	cwd="/projects/vessel"
+	onLifecycle={(event) => {
+		if (event.phase === 'opened') persistReceipt(event);
+	}}
+/>
+```
+
+`opened` is the success boundary. It is emitted only after `session()` resolves
+and includes the real session id, environment id, execution id, requested `cwd`,
+and timestamp. A Files `onOpenTerminal` callback is only the request that begins
+this flow.
+
+## Host terminal workspace
+
+`TerminalHostWorkspace` is the whole terminal experience — host picker, session
+tabs, reconnect banner, terminal — for any container: a page, a dialog, or a
+panel. The app supplies hosts and an opener; the workspace owns the chrome.
+
+```svelte
+<TerminalHostWorkspace
+	{hosts}
+	layout="dialog"
+	initialHostId={hostId}
+	autoOpen
+	openSession={({ hostId, command, cols, rows, signal, reconnect }) =>
+		openHttpSession(runtime, { command, cols, rows, signal, extra: { host: hostId }, reconnect })}
+/>
+```
+
+Props: `hosts`, `openSession`, `initialHostId`, `initialCommand` (pre-filled,
+never auto-run), `autoOpen`, `readonly` (observe mode), `layout`
+(`page` | `dialog` | `panel`), `defaultCommand`, `addMachineHref`, `hostsError`,
+`hostsRefreshing`, `onRetryHosts`, `empty` and `actions` snippets, `cols`/`rows`
+grid lock, `theme`, `describeError`, `label`, `class`.
+
+## Runtime docs
+
+Register `@vibesdotdev/terminal-client/svelte/plugin` to contribute the canonical
+`terminal-svelte` `docs/topic` and the designed Kit ToolCard for `tools/tool:terminal`
+(cwd, command/session, output excerpt via CodeViewer). The topic documents public
+entrypoints, the execution-backed lifecycle boundary, and the ownership split.
+
+## Vessel surface
+
+Hosts that compose Vessel may register
+`@vibesdotdev/vessel/apps/terminal.vessel.plugin`. It contributes stable surface id
+`terminal.workspace` and a browser-only lazy loader. The descriptor contains no
+component import path; Vessel keeps that product-registration detail while loading
+Terminal's owner component. It consumes the strict runtime-validatable state schema
+from `@vibesdotdev/terminal-client/workspace` (`executionId`, `cwd`, optional
+correlation/source ids) and requires `runtime/execution`, selected exactly by the
+normalized `executionId`. Package presence or a different execution provider does
+not make a saved Terminal anchor available.
+
+A retained Terminal treats `executionId`, command, arguments, and `cwd` as one
+live launch signature. Changing any member cancels the older open generation and
+starts a session through the newly selected exact provider; same-folder provider
+changes never keep the old session by accident.
+
+The xterm attachment has its own generation lease. A transient `session=null` or
+provider swap detaches output immediately, and deferred exit/disconnect callbacks
+from the old session cannot overwrite the new session's visible state.

package/dist/svelte/ReconnectBanner.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+	/**
+	 * <ReconnectBanner> — visible reconnect / error banner.
+	 *
+	 * Renders in three visual states:
+	 *  - 'reconnecting': amber, shows attempt number + "Reconnecting…"
+	 *  - 'reconnected':  green, confirms the session was restored with backlog replay
+	 *  - 'failed':       red, explains the drop + offers "Start new session"
+	 *
+	 * The green 'reconnected' banner auto-dismisses after a short delay
+	 * (the page manages this externally by setting status back to null).
+	 */
+	import { Button } from '@vibesdotdev/kit/components/ui/button';
+	import { cn } from '@vibesdotdev/kit/utils';
+
+	type BannerStatus = 'reconnecting' | 'reconnected' | 'failed' | null;
+
+	interface Props {
+		status: BannerStatus;
+		/** Current attempt number (1-based), shown during 'reconnecting'. */
+		attempt?: number;
+		/** Delay in ms before the next reconnect attempt, shown during 'reconnecting'. */
+		delayMs?: number;
+		/** Human-readable failure reason shown in the 'failed' state. */
+		reason?: string;
+		/** Called when the user clicks "Start new session" in the failed state. */
+		onNewSession?: () => void;
+	}
+
+	let { status, attempt = 0, delayMs = 0, reason = '', onNewSession }: Props = $props();
+
+	const bannerClass = $derived(
+		cn(
+			'flex shrink-0 items-center gap-2 border-t px-3.5 py-2 font-mono text-xs',
+			status === 'reconnecting' &&
+				'border-border bg-warning/10 text-warning',
+			status === 'reconnected' &&
+				'border-border bg-success/10 text-success',
+			status === 'failed' &&
+				'border-border bg-destructive/15 text-destructive'
+		)
+	);
+
+	function formatDelay(ms: number): string {
+		if (ms < 1000) return `${ms} ms`;
+		return `${(ms / 1000).toFixed(1)} s`;
+	}
+</script>
+
+{#if status !== null}
+	<div
+		class={bannerClass}
+		role="status"
+		aria-live="polite"
+		aria-atomic="true"
+	>
+		{#if status === 'reconnecting'}
+			<span class="shrink-0 text-sm" aria-hidden="true">↻</span>
+			<span class="flex-1 leading-normal">
+				Connection lost — reconnecting
+				{#if attempt > 0}(attempt {attempt}){/if}
+				{#if delayMs > 0}
+					<span class="ml-1 opacity-70">next attempt in {formatDelay(delayMs)}</span>
+				{/if}
+			</span>
+		{:else if status === 'reconnected'}
+			<span class="shrink-0 text-sm" aria-hidden="true">✓</span>
+			<span class="flex-1 leading-normal">
+				Reattached — your session kept running
+			</span>
+		{:else if status === 'failed'}
+			<span class="shrink-0 text-sm" aria-hidden="true">⚠</span>
+			<span class="flex-1 leading-normal">
+				{reason || 'Connection lost and could not be restored.'}
+			</span>
+			{#if onNewSession}
+				<Button
+					variant="outline"
+					size="sm"
+					class="h-7 shrink-0 border-current bg-transparent px-2 font-mono text-xs text-inherit hover:bg-background/20 hover:text-inherit"
+					onclick={onNewSession}
+				>
+					Start new session
+				</Button>
+			{/if}
+		{/if}
+	</div>
+{/if}

package/dist/svelte/ReconnectBanner.svelte.d.ts

@@ -0,0 +1,16 @@
+type BannerStatus = 'reconnecting' | 'reconnected' | 'failed' | null;
+interface Props {
+    status: BannerStatus;
+    /** Current attempt number (1-based), shown during 'reconnecting'. */
+    attempt?: number;
+    /** Delay in ms before the next reconnect attempt, shown during 'reconnecting'. */
+    delayMs?: number;
+    /** Human-readable failure reason shown in the 'failed' state. */
+    reason?: string;
+    /** Called when the user clicks "Start new session" in the failed state. */
+    onNewSession?: () => void;
+}
+declare const ReconnectBanner: import("svelte").Component<Props, {}, "">;
+type ReconnectBanner = ReturnType<typeof ReconnectBanner>;
+export default ReconnectBanner;
+//# sourceMappingURL=ReconnectBanner.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReconnectBanner.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/ReconnectBanner.svelte.ts"],"names":[],"mappings":"AAkBC,KAAK,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,IAAI,CAAC;AAErE,UAAU,KAAK;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AA4DF,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}