@vibesdotdev/terminal-client 1.0.0-rc.2 → 1.0.0-rc.3

package/dist/svelte/HostPicker.svelte

@@ -38,6 +38,12 @@
 		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. */
@@ -50,6 +56,7 @@
 		defaultCommand = 'sh',
 		initialCommand = '',
 		addMachineHref = '/fleet',
+		allowDefaultShell = false,
 		onOpen,
 		onCancel
 	}: Props = $props();
@@ -72,8 +79,8 @@
 	let commandEl = $state<HTMLInputElement | null>(null);
 
 	const selectedHost = $derived(hosts.find((h) => h.id === selectedHostId) ?? null);
-	const resolvedCommand = $derived(command.trim() || defaultCommand);
-	const canOpen = $derived(selectedHost !== null && resolvedCommand.length > 0);
+	const resolvedCommand = $derived(command.trim() || (allowDefaultShell ? '' : defaultCommand));
+	const canOpen = $derived(selectedHost !== null && (allowDefaultShell || resolvedCommand.length > 0));
 
 	function handleKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape') {

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

@@ -19,6 +19,12 @@ interface Props {
     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. */

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

@@ -1 +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,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;AAgLF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"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

@@ -23,6 +23,29 @@ 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

package/dist/svelte/TerminalHostWorkspace.svelte

@@ -0,0 +1,264 @@
+<script lang="ts">
+	/**
+	 * <TerminalHostWorkspace> — the embeddable terminal experience.
+	 *
+	 * Host picker, session tabs, reconnect banner and the terminal itself, as
+	 * one component that fills whatever container it is given: a full page, a
+	 * dialog, or a side panel. The host app supplies the reachable hosts and a
+	 * session opener (dependency-injected transport); the workspace owns every
+	 * piece of terminal chrome so each surface looks and behaves the same.
+	 *
+	 * State lives in the rune-free `TerminalHostWorkspaceController`
+	 * (`./terminal-host-workspace.ts`); this file renders its snapshot.
+	 *
+	 * Styling is kit theme tokens only (`bg-background`, `border-border`, …), so
+	 * the workspace matches the surrounding app shell and theme.
+	 */
+	import { onDestroy, untrack, type Snippet } from 'svelte';
+	import { Button } from '@vibesdotdev/kit/components/ui/button';
+	import { Alert, AlertDescription } from '@vibesdotdev/kit/components/ui/alert';
+	import { cn } from '@vibesdotdev/kit/utils';
+	import Terminal from './Terminal.svelte';
+	import HostPicker from './HostPicker.svelte';
+	import SessionTabs from './SessionTabs.svelte';
+	import ReconnectBanner from './ReconnectBanner.svelte';
+	import {
+		TerminalHostWorkspaceController,
+		terminalHostTabBanner,
+		type TerminalHostErrorDescriber,
+		type TerminalHostSessionOpener,
+		type TerminalHostWorkspaceLayout
+	} from './terminal-host-workspace.js';
+	import type { HostOption, TabSession, TerminalTheme } from './types.js';
+
+	interface Props {
+		/** Reachable hosts, in display order. */
+		hosts: HostOption[];
+		/** Opens a session on a host. The workspace never owns a transport. */
+		openSession: TerminalHostSessionOpener;
+		/** Deep-linked host id; an unknown id shows a "not reachable" notice and the picker. */
+		initialHostId?: string;
+		/** Deep-linked command: pre-filled in the picker, never run without an explicit click. */
+		initialCommand?: string;
+		/** Open on the initial host straight away (no picker) when no command is pre-filled. */
+		autoOpen?: boolean;
+		/** Observe mode for every session: output renders, keystrokes never reach the host. */
+		readonly?: boolean;
+		/** Density only — the workspace always fills its container. */
+		layout?: TerminalHostWorkspaceLayout;
+		/** Placeholder in the picker's command field. Blank opens the host's default shell. */
+		defaultCommand?: string;
+		/** Where "Add a machine" goes in the empty picker. */
+		addMachineHref?: string;
+		/** Host discovery failure copy; shown above the workspace. */
+		hostsError?: string;
+		hostsRefreshing?: boolean;
+		/** Retry host discovery. Shows a retry button next to `hostsError`. */
+		onRetryHosts?: () => void;
+		/** Replaces the picker when `hosts` is empty (e.g. a sign-in prompt). */
+		empty?: Snippet;
+		/** Extra toolbar actions (rendered at the end of the tab strip). */
+		actions?: Snippet;
+		/** Lock the grid (both required). */
+		cols?: number;
+		rows?: number;
+		theme?: TerminalTheme;
+		describeError?: TerminalHostErrorDescriber;
+		/** Accessible name of the workspace region. */
+		label?: string;
+		class?: string;
+	}
+
+	let {
+		hosts,
+		openSession,
+		initialHostId,
+		initialCommand,
+		autoOpen = false,
+		readonly = false,
+		layout = 'page',
+		defaultCommand = 'your shell',
+		addMachineHref,
+		hostsError = '',
+		hostsRefreshing = false,
+		onRetryHosts,
+		empty,
+		actions,
+		cols,
+		rows,
+		theme,
+		describeError,
+		label = 'Terminal',
+		class: className = ''
+	}: Props = $props();
+
+	const controller = untrack(
+		() =>
+			new TerminalHostWorkspaceController({
+				openSession: (request) => openSession(request),
+				readonly,
+				describeError: describeError ? (failure, host) => describeError(failure, host) : undefined
+			})
+	);
+	let view = $state(controller.snapshot);
+	const unsubscribe = controller.subscribe((next) => {
+		view = next;
+	});
+	untrack(() => controller.start({ hosts, initialHostId, initialCommand, autoOpen }));
+	$effect(() => controller.setHosts(hosts));
+	onDestroy(() => {
+		unsubscribe();
+		controller.dispose();
+	});
+
+	const lockedGrid = $derived(
+		cols !== undefined && rows !== undefined && cols > 0 && rows > 0 ? { cols, rows } : null
+	);
+	const activeTab = $derived(view.tabs.find((tab) => tab.key === view.activeKey));
+	const banner = $derived(terminalHostTabBanner(activeTab));
+	const stripTabs = $derived<TabSession[]>(
+		view.tabs.map((tab) => ({
+			id: tab.key,
+			command: tab.command ?? 'shell',
+			hostLabel: tab.hostLabel,
+			startedAt: 0,
+			detached: tab.status === 'reconnecting' || tab.status === 'failed',
+			exited: tab.status === 'exited'
+		}))
+	);
+	const lastGrid = new Map<string, { cols: number; rows: number }>();
+	const padding = $derived(layout === 'page' ? 'p-2 sm:p-3' : layout === 'dialog' ? 'p-2' : 'p-1');
+
+	function ready(key: string, dims: { cols: number; rows: number }): void {
+		const grid = lockedGrid ?? dims;
+		lastGrid.set(key, grid);
+		controller.terminalReady(key, grid);
+	}
+
+	function startOver(): void {
+		if (activeTab?.status === 'failed' && activeTab.session === null) {
+			controller.retry(activeTab.key, lastGrid.get(activeTab.key) ?? lockedGrid ?? { cols: 80, rows: 24 });
+			return;
+		}
+		controller.showPicker();
+	}
+</script>
+
+<section
+	class={cn('flex h-full min-h-0 w-full min-w-0 flex-col overflow-hidden bg-background text-foreground', className)}
+	aria-label={label}
+	data-terminal-host-workspace
+	data-layout={layout}
+	data-picker-open={view.pickerOpen ? 'true' : 'false'}
+	data-active-status={activeTab?.status ?? 'none'}
+	data-banner-status={banner.status ?? 'none'}
+>
+	{#if view.tabs.length > 0 || actions}
+		<header class="flex shrink-0 items-stretch border-b border-border">
+			{#if view.tabs.length > 0}
+				<div class="-mb-px min-w-0 flex-1">
+					<SessionTabs
+						tabs={stripTabs}
+						activeId={view.activeKey}
+						onSelect={(key) => controller.select(key)}
+						onClose={(key) => controller.close(key)}
+						onNewTab={() => controller.showPicker()}
+					/>
+				</div>
+			{:else}
+				<div class="flex-1"></div>
+			{/if}
+			{#if actions}
+				<div class="flex shrink-0 items-center gap-2 px-2 py-1">{@render actions()}</div>
+			{/if}
+		</header>
+	{/if}
+
+	{#if hostsError}
+		<Alert class="shrink-0 rounded-none border-x-0 border-t-0" data-host-discovery-error>
+			<AlertDescription class="flex flex-wrap items-center justify-between gap-2">
+				<span>{hostsError}</span>
+				{#if onRetryHosts}
+					<Button variant="outline" size="sm" onclick={onRetryHosts} disabled={hostsRefreshing}>
+						{hostsRefreshing ? 'Refreshing…' : 'Retry'}
+					</Button>
+				{/if}
+			</AlertDescription>
+		</Alert>
+	{/if}
+
+	<div class="relative min-h-0 min-w-0 flex-1">
+		{#each view.tabs as tab (tab.key)}
+			{@const active = tab.key === view.activeKey}
+			<div
+				class={cn('absolute inset-0 flex min-h-0 flex-col', padding, !active && 'invisible')}
+				aria-hidden={!active}
+				data-terminal-tab={tab.key}
+				data-terminal-tab-status={tab.status}
+				data-terminal-tab-host={tab.hostId}
+			>
+				{#if tab.readonly}
+					<p class="mb-2 shrink-0 rounded-md border border-warning/40 bg-warning/10 px-3 py-1.5 text-xs text-warning" role="status">
+						Observe mode — input is disabled.
+					</p>
+				{/if}
+				<div class="min-h-0 flex-1">
+					<Terminal
+						session={tab.session}
+						{theme}
+						cols={lockedGrid?.cols}
+						rows={lockedGrid?.rows}
+						connectionState={tab.session ? 'live' : 'connecting'}
+						readonly={tab.readonly || tab.status !== 'live' || !tab.inputReady}
+						onReady={(dims) => ready(tab.key, dims)}
+						onInputReady={() => controller.inputReady(tab.key)}
+						onExit={(result) => controller.exited(tab.key, result.exitCode)}
+						onDisconnect={(reason) => controller.disconnected(tab.key, reason)}
+					/>
+				</div>
+				{#if active}
+					<ReconnectBanner
+						status={banner.status}
+						attempt={banner.attempt}
+						delayMs={banner.delayMs}
+						reason={banner.reason}
+						onNewSession={startOver}
+					/>
+				{/if}
+			</div>
+		{/each}
+
+		{#if view.pickerOpen}
+			<div
+				class={cn(
+					'absolute inset-0 z-10 flex items-center justify-center overflow-auto',
+					layout === 'panel' ? 'p-2' : 'p-4',
+					view.tabs.length > 0 && 'bg-background/80 backdrop-blur-sm'
+				)}
+				data-terminal-picker
+			>
+				<div class="flex w-full max-w-lg flex-col gap-3">
+					{#if view.requestedHostUnavailable}
+						<Alert variant="destructive" data-requested-host-unavailable>
+							<AlertDescription>The requested machine is not reachable. Pick another machine below.</AlertDescription>
+						</Alert>
+					{/if}
+					{#if hosts.length === 0 && empty}
+						{@render empty()}
+					{:else}
+						<HostPicker
+							{hosts}
+							preselectedHostId={view.pickerHostId}
+							initialCommand={view.pickerCommand}
+							{defaultCommand}
+							{addMachineHref}
+							allowDefaultShell
+							onOpen={(hostId, command) => controller.open(hostId, command)}
+							onCancel={view.tabs.length > 0 ? () => controller.hidePicker() : undefined}
+						/>
+					{/if}
+				</div>
+			</div>
+		{/if}
+	</div>
+</section>

package/dist/svelte/TerminalHostWorkspace.svelte.d.ts

@@ -0,0 +1,59 @@
+/**
+     * <TerminalHostWorkspace> — the embeddable terminal experience.
+     *
+     * Host picker, session tabs, reconnect banner and the terminal itself, as
+     * one component that fills whatever container it is given: a full page, a
+     * dialog, or a side panel. The host app supplies the reachable hosts and a
+     * session opener (dependency-injected transport); the workspace owns every
+     * piece of terminal chrome so each surface looks and behaves the same.
+     *
+     * State lives in the rune-free `TerminalHostWorkspaceController`
+     * (`./terminal-host-workspace.ts`); this file renders its snapshot.
+     *
+     * Styling is kit theme tokens only (`bg-background`, `border-border`, …), so
+     * the workspace matches the surrounding app shell and theme.
+     */
+import { type Snippet } from 'svelte';
+import { type TerminalHostErrorDescriber, type TerminalHostSessionOpener, type TerminalHostWorkspaceLayout } from './terminal-host-workspace.ts';
+import type { HostOption, TerminalTheme } from './types.ts';
+interface Props {
+    /** Reachable hosts, in display order. */
+    hosts: HostOption[];
+    /** Opens a session on a host. The workspace never owns a transport. */
+    openSession: TerminalHostSessionOpener;
+    /** Deep-linked host id; an unknown id shows a "not reachable" notice and the picker. */
+    initialHostId?: string;
+    /** Deep-linked command: pre-filled in the picker, never run without an explicit click. */
+    initialCommand?: string;
+    /** Open on the initial host straight away (no picker) when no command is pre-filled. */
+    autoOpen?: boolean;
+    /** Observe mode for every session: output renders, keystrokes never reach the host. */
+    readonly?: boolean;
+    /** Density only — the workspace always fills its container. */
+    layout?: TerminalHostWorkspaceLayout;
+    /** Placeholder in the picker's command field. Blank opens the host's default shell. */
+    defaultCommand?: string;
+    /** Where "Add a machine" goes in the empty picker. */
+    addMachineHref?: string;
+    /** Host discovery failure copy; shown above the workspace. */
+    hostsError?: string;
+    hostsRefreshing?: boolean;
+    /** Retry host discovery. Shows a retry button next to `hostsError`. */
+    onRetryHosts?: () => void;
+    /** Replaces the picker when `hosts` is empty (e.g. a sign-in prompt). */
+    empty?: Snippet;
+    /** Extra toolbar actions (rendered at the end of the tab strip). */
+    actions?: Snippet;
+    /** Lock the grid (both required). */
+    cols?: number;
+    rows?: number;
+    theme?: TerminalTheme;
+    describeError?: TerminalHostErrorDescriber;
+    /** Accessible name of the workspace region. */
+    label?: string;
+    class?: string;
+}
+declare const TerminalHostWorkspace: import("svelte").Component<Props, {}, "">;
+type TerminalHostWorkspace = ReturnType<typeof TerminalHostWorkspace>;
+export default TerminalHostWorkspace;
+//# sourceMappingURL=TerminalHostWorkspace.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TerminalHostWorkspace.svelte.d.ts","sourceRoot":"","sources":["../../src/svelte/TerminalHostWorkspace.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;OAcI;AACJ,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAQ1D,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,MAAM,8BAA8B,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAc,aAAa,EAAE,MAAM,YAAY,CAAC;AAGvE,UAAU,KAAK;IACd,yCAAyC;IACzC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,uEAAuE;IACvE,WAAW,EAAE,yBAAyB,CAAC;IACvC,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,2BAA2B,CAAC;IACrC,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,aAAa,CAAC,EAAE,0BAA0B,CAAC;IAC3C,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAkKF,QAAA,MAAM,qBAAqB,2CAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}

package/dist/svelte/index.d.ts

@@ -16,11 +16,13 @@
  */
 export { default as Terminal } from './Terminal.svelte';
 export { default as TerminalWorkspace } from './TerminalWorkspace.svelte';
+export { default as TerminalHostWorkspace } from './TerminalHostWorkspace.svelte';
 export { default as TerminalMobileToolbar } from './TerminalMobileToolbar.svelte';
 export { default as HostPicker } from './HostPicker.svelte';
 export { default as SessionTabs } from './SessionTabs.svelte';
 export { default as ReconnectBanner } from './ReconnectBanner.svelte';
 export { default as TerminalToolCard } from './tool-widgets/TerminalToolCard.svelte';
+export { TerminalHostWorkspaceController, describeTerminalHostFailure, terminalHostLabel, terminalHostTabBanner, type TerminalHostBanner, type TerminalHostBannerStatus, type TerminalHostErrorDescriber, type TerminalHostOpenedSession, type TerminalHostSessionOpener, type TerminalHostSessionRequest, type TerminalHostTab, type TerminalHostTabStatus, type TerminalHostWorkspaceLayout, type TerminalHostWorkspaceOptions, type TerminalHostWorkspaceSnapshot, type TerminalHostWorkspaceStart } from './terminal-host-workspace.ts';
 export { registerTerminalSvelteToolWidget, terminalSveltePlugin, terminalSvelteWidgetDescriptor, default } from './terminal-svelte.plugin.ts';
 export { openTerminalWorkspaceSession, openTerminalWorkspaceTargetSession, terminalWorkspaceCapabilityBanner, terminalWorkspaceError, terminalWorkspaceExitedEvent, terminalWorkspacePlaceDefaultCapabilities, terminalWorkspacePlaceLabel, terminalWorkspaceStatusLabel, terminalWorkspaceVesselStateSchema, type OpenTerminalWorkspaceSessionInput, type OpenTerminalWorkspaceSessionResult, type OpenTerminalWorkspaceTargetSessionInput, type OpenTerminalWorkspaceTargetSessionResult, type TerminalWorkspaceExitedEvent, type TerminalWorkspaceLifecycleEvent, type TerminalWorkspaceOpenedReceipt, type TerminalWorkspaceRuntimePlaceOption, type TerminalWorkspaceSessionMode, type TerminalWorkspaceStatus } from '../workspace.ts';
 export { DEFAULT_FONT, DEFAULT_TERMINAL_THEME, VIBES_TERMINAL_THEME, type ExecutionSession, type TerminalProps, type TerminalTheme, type HostOption, type TabSession } from './types.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AACrF,OAAO,EACN,gCAAgC,EAChC,oBAAoB,EACpB,8BAA8B,EAC9B,OAAO,EACP,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,4BAA4B,EAC5B,kCAAkC,EAClC,iCAAiC,EACjC,sBAAsB,EACtB,4BAA4B,EAC5B,yCAAyC,EACzC,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,EAClC,KAAK,iCAAiC,EACtC,KAAK,kCAAkC,EACvC,KAAK,uCAAuC,EAC5C,KAAK,wCAAwC,EAC7C,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,KAAK,mCAAmC,EACxC,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/svelte/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AACrF,OAAO,EACN,+BAA+B,EAC/B,2BAA2B,EAC3B,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACN,gCAAgC,EAChC,oBAAoB,EACpB,8BAA8B,EAC9B,OAAO,EACP,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,4BAA4B,EAC5B,kCAAkC,EAClC,iCAAiC,EACjC,sBAAsB,EACtB,4BAA4B,EAC5B,yCAAyC,EACzC,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,EAClC,KAAK,iCAAiC,EACtC,KAAK,kCAAkC,EACvC,KAAK,uCAAuC,EAC5C,KAAK,wCAAwC,EAC7C,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACnC,KAAK,mCAAmC,EACxC,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,MAAM,YAAY,CAAC"}

package/dist/svelte/index.js

@@ -16,11 +16,13 @@
  */
 export { default as Terminal } from './Terminal.svelte';
 export { default as TerminalWorkspace } from './TerminalWorkspace.svelte';
+export { default as TerminalHostWorkspace } from './TerminalHostWorkspace.svelte';
 export { default as TerminalMobileToolbar } from './TerminalMobileToolbar.svelte';
 export { default as HostPicker } from './HostPicker.svelte';
 export { default as SessionTabs } from './SessionTabs.svelte';
 export { default as ReconnectBanner } from './ReconnectBanner.svelte';
 export { default as TerminalToolCard } from './tool-widgets/TerminalToolCard.svelte';
+export { TerminalHostWorkspaceController, describeTerminalHostFailure, terminalHostLabel, terminalHostTabBanner } from "./terminal-host-workspace.js";
 export { registerTerminalSvelteToolWidget, terminalSveltePlugin, terminalSvelteWidgetDescriptor, default } from "./terminal-svelte.plugin.js";
 export { openTerminalWorkspaceSession, openTerminalWorkspaceTargetSession, terminalWorkspaceCapabilityBanner, terminalWorkspaceError, terminalWorkspaceExitedEvent, terminalWorkspacePlaceDefaultCapabilities, terminalWorkspacePlaceLabel, terminalWorkspaceStatusLabel, terminalWorkspaceVesselStateSchema } from "../workspace.js";
 export { DEFAULT_FONT, DEFAULT_TERMINAL_THEME, VIBES_TERMINAL_THEME } from "./types.js";

package/dist/svelte/terminal-host-workspace.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Rune-free state owner for `<TerminalHostWorkspace>`.
+ *
+ * The workspace is the embeddable terminal experience: pick a host, open
+ * sessions in tabs, see reconnect state, close sessions. This controller owns
+ * that state machine so it is the same in a full page, a dialog, or a panel,
+ * and so it is testable without a DOM. The component renders a snapshot and
+ * forwards user and `<Terminal>` events here.
+ *
+ * Transport is injected: the host app supplies a `TerminalHostSessionOpener`
+ * (typically a closure over `openHttpSession`). The controller never imports
+ * an HTTP client and never invents a session — a tab is `live` only after the
+ * opener resolves with a real `ExecutionSession`.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import type { ExecutionSession } from '@vibesdotdev/kernel/execution';
+import type { HostOption } from './types.ts';
+/** What the workspace asks the host app's opener for. */
+export interface TerminalHostSessionRequest {
+    /** The selected `HostOption.id`. */
+    hostId: string;
+    /** Command to run; `undefined` means the host's default shell. */
+    command?: string;
+    /** Fitted (or locked) grid the session must start at. */
+    cols: number;
+    rows: number;
+    /** Aborted when the user closes the tab or the workspace unmounts mid-open. */
+    signal: AbortSignal;
+    /**
+     * Transport reconnect hooks. Forward these to the transport (for
+     * `openHttpSession`, as `reconnect.onReconnecting` / `reconnect.onReconnected`)
+     * so the workspace can show the reconnect banner.
+     */
+    reconnect: {
+        onReconnecting: (attempt: number, delayMs: number) => void;
+        onReconnected: (attempt: number) => void;
+    };
+}
+/** A session the opener created. */
+export interface TerminalHostOpenedSession {
+    /** Stable session id (shown nowhere; used for tab identity and app hooks). */
+    id: string;
+    session: ExecutionSession;
+}
+/** Dependency-injected session opener; the workspace owns no transport. */
+export type TerminalHostSessionOpener = (request: TerminalHostSessionRequest) => Promise<TerminalHostOpenedSession>;
+/** Turns an open failure into user-facing copy. */
+export type TerminalHostErrorDescriber = (failure: CapabilityError, hostLabel: string) => string;
+/** Where the workspace is mounted. Only density changes; it always fills its container. */
+export type TerminalHostWorkspaceLayout = 'page' | 'dialog' | 'panel';
+export type TerminalHostTabStatus = 'opening' | 'live' | 'reconnecting' | 'failed' | 'exited';
+export type TerminalHostBannerStatus = 'reconnecting' | 'reconnected' | 'failed' | null;
+export interface TerminalHostTab {
+    /** Workspace-local identity (stable before the session id exists). */
+    readonly key: string;
+    /** Session id once opened. */
+    readonly sessionId: string | null;
+    readonly hostId: string;
+    readonly hostLabel: string;
+    /** Requested command; `undefined` = host default shell. */
+    readonly command: string | undefined;
+    /** Observe mode: keystrokes never reach the session. */
+    readonly readonly: boolean;
+    readonly status: TerminalHostTabStatus;
+    readonly session: ExecutionSession | null;
+    readonly inputReady: boolean;
+    readonly exitCode: number | null;
+    /** User-facing failure copy for `failed`. */
+    readonly error: string;
+    /** The typed failure behind `failed`, for hosts that log or report it. */
+    readonly failure: CapabilityError | null;
+    readonly reconnectAttempt: number;
+    readonly reconnectDelayMs: number;
+    /** True for a short moment after a successful reconnect. */
+    readonly reattached: boolean;
+}
+export interface TerminalHostBanner {
+    status: TerminalHostBannerStatus;
+    attempt: number;
+    delayMs: number;
+    reason: string;
+}
+export interface TerminalHostWorkspaceSnapshot {
+    readonly tabs: readonly TerminalHostTab[];
+    readonly activeKey: string;
+    readonly pickerOpen: boolean;
+    /** The deep-linked host is not in the reachable host list. */
+    readonly requestedHostUnavailable: boolean;
+    /** Host the picker preselects. */
+    readonly pickerHostId: string;
+    /** Command the picker pre-fills (never auto-run). */
+    readonly pickerCommand: string;
+}
+export interface TerminalHostWorkspaceStart {
+    hosts: readonly HostOption[];
+    /** Deep-linked host id. Absent → the first host. */
+    initialHostId?: string;
+    /** Deep-linked command: pre-filled in the picker, never run without a click. */
+    initialCommand?: string;
+    /** Open a session on the initial host immediately (no picker) when no command is pre-filled. */
+    autoOpen?: boolean;
+}
+export interface TerminalHostWorkspaceOptions {
+    openSession: TerminalHostSessionOpener;
+    /** Observe mode for every session this workspace opens. */
+    readonly?: boolean;
+    describeError?: TerminalHostErrorDescriber;
+    /** How long the "Reattached" banner stays (ms). */
+    reattachedNoticeMs?: number;
+}
+/** Product copy for an open failure. Never names transports, kinds, or descriptors. */
+export declare function describeTerminalHostFailure(failure: CapabilityError, hostLabel: string): string;
+/** The banner the active tab shows. Exited and failed tabs offer a new session. */
+export declare function terminalHostTabBanner(tab: TerminalHostTab | undefined): TerminalHostBanner;
+/** Tab label host suffix and picker label for a host. */
+export declare function terminalHostLabel(host: HostOption | undefined, hostId: string): string;
+type Listener = (snapshot: TerminalHostWorkspaceSnapshot) => void;
+export declare class TerminalHostWorkspaceController {
+    #private;
+    constructor(options: TerminalHostWorkspaceOptions);
+    get snapshot(): TerminalHostWorkspaceSnapshot;
+    subscribe(listener: Listener): () => void;
+    /** The latest reachable hosts (labels for new tabs). */
+    setHosts(hosts: readonly HostOption[]): void;
+    /** Resolve the deep link once: open on the initial host, or show the picker. */
+    start(input: TerminalHostWorkspaceStart): void;
+    /** Create a tab on `hostId`. The session opens once its terminal reports a grid. */
+    open(hostId: string, command?: string): string;
+    /** `<Terminal onReady>` for a tab: start the session at the fitted grid. */
+    terminalReady(key: string, dims: {
+        cols: number;
+        rows: number;
+    }): void;
+    /** Retry a failed tab in place (same host + command, new session). */
+    retry(key: string, dims: {
+        cols: number;
+        rows: number;
+    }): void;
+    inputReady(key: string): void;
+    exited(key: string, exitCode: number | null): void;
+    disconnected(key: string, reason: string): void;
+    select(key: string): void;
+    /** Close a tab: abort an in-flight open, end a live session. */
+    close(key: string): void;
+    showPicker(): void;
+    /** Dismiss the picker (only when a tab can be shown behind it). */
+    hidePicker(): void;
+    /** Unmount: abort opens and end every session this workspace started. */
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=terminal-host-workspace.d.ts.map

package/dist/svelte/terminal-host-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-host-workspace.d.ts","sourceRoot":"","sources":["../../src/svelte/terminal-host-workspace.ts"],"names":[],"mappings":"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"}

package/dist/svelte/terminal-host-workspace.js

@@ -0,0 +1,335 @@
+/**
+ * Rune-free state owner for `<TerminalHostWorkspace>`.
+ *
+ * The workspace is the embeddable terminal experience: pick a host, open
+ * sessions in tabs, see reconnect state, close sessions. This controller owns
+ * that state machine so it is the same in a full page, a dialog, or a panel,
+ * and so it is testable without a DOM. The component renders a snapshot and
+ * forwards user and `<Terminal>` events here.
+ *
+ * Transport is injected: the host app supplies a `TerminalHostSessionOpener`
+ * (typically a closure over `openHttpSession`). The controller never imports
+ * an HTTP client and never invents a session — a tab is `live` only after the
+ * opener resolves with a real `ExecutionSession`.
+ */
+import * as z from 'zod/v4';
+import { CapabilityError, CaughtFailureSchema } from '@vibesdotdev/kernel';
+const HttpStatusSchema = z.number().int();
+/** Product copy for an open failure. Never names transports, kinds, or descriptors. */
+export function describeTerminalHostFailure(failure, hostLabel) {
+    const parsedStatus = HttpStatusSchema.safeParse(failure.details?.status);
+    const status = parsedStatus.success ? parsedStatus.data : undefined;
+    const text = `${failure.message} ${failure.reason}`.toLowerCase();
+    const machine = hostLabel || 'this machine';
+    if (status === 401)
+        return 'Sign in to open a terminal session.';
+    if (status === 403 || failure.code === 'PERMISSION_DENIED') {
+        return "Access denied — you don't have permission to open a terminal on this machine.";
+    }
+    if (status === 429 || /max[_\s-]?sessions|too many sessions/.test(text)) {
+        return `Too many sessions are open on ${machine} — close one to start another.`;
+    }
+    if (status === 503 || status === 502 || /unreachable|unavailable|offline/.test(text)) {
+        return `${machine} is not reachable right now. Make sure it is online, then try again.`;
+    }
+    return `Unable to open a terminal on ${machine}. Check that it is online, then try again.`;
+}
+/** The banner the active tab shows. Exited and failed tabs offer a new session. */
+export function terminalHostTabBanner(tab) {
+    const none = { status: null, attempt: 0, delayMs: 0, reason: '' };
+    if (!tab)
+        return none;
+    switch (tab.status) {
+        case 'reconnecting':
+            return { status: 'reconnecting', attempt: tab.reconnectAttempt, delayMs: tab.reconnectDelayMs, reason: '' };
+        case 'failed':
+            return { ...none, status: 'failed', reason: tab.error || 'Connection lost and could not be restored.' };
+        case 'exited':
+            return {
+                ...none,
+                status: 'failed',
+                reason: tab.exitCode === null ? 'Session ended.' : `Session ended — exit code ${tab.exitCode}.`
+            };
+        case 'live':
+            return tab.reattached ? { ...none, status: 'reconnected' } : none;
+        default:
+            return none;
+    }
+}
+/** Tab label host suffix and picker label for a host. */
+export function terminalHostLabel(host, hostId) {
+    if (!host)
+        return hostId;
+    return host.local ? `This machine — ${host.name}` : host.name;
+}
+export class TerminalHostWorkspaceController {
+    #options;
+    #hosts = [];
+    #tabs = [];
+    #runtime = new Map();
+    #activeKey = '';
+    #pickerOpen = true;
+    #requestedHostUnavailable = false;
+    #pickerHostId = '';
+    #pickerCommand = '';
+    #nextKey = 0;
+    #disposed = false;
+    #listeners = new Set();
+    #snapshot;
+    constructor(options) {
+        this.#options = options;
+        this.#snapshot = this.#build();
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** The latest reachable hosts (labels for new tabs). */
+    setHosts(hosts) {
+        this.#hosts = hosts;
+    }
+    /** Resolve the deep link once: open on the initial host, or show the picker. */
+    start(input) {
+        this.#hosts = input.hosts;
+        const requested = input.initialHostId?.trim() ?? '';
+        const known = requested ? input.hosts.some((host) => host.id === requested) : false;
+        this.#requestedHostUnavailable = Boolean(requested) && !known;
+        this.#pickerHostId = known ? requested : (input.hosts[0]?.id ?? '');
+        this.#pickerCommand = input.initialCommand ?? '';
+        const canAutoOpen = input.autoOpen === true &&
+            !this.#requestedHostUnavailable &&
+            !this.#pickerCommand &&
+            this.#pickerHostId !== '';
+        if (canAutoOpen)
+            this.open(this.#pickerHostId);
+        else
+            this.#emit();
+    }
+    /** Create a tab on `hostId`. The session opens once its terminal reports a grid. */
+    open(hostId, command) {
+        const key = `tab-${++this.#nextKey}`;
+        const host = this.#hosts.find((candidate) => candidate.id === hostId);
+        this.#tabs = [
+            ...this.#tabs,
+            {
+                key,
+                sessionId: null,
+                hostId,
+                hostLabel: terminalHostLabel(host, hostId),
+                command: command?.trim() ? command.trim() : undefined,
+                readonly: this.#options.readonly === true,
+                status: 'opening',
+                session: null,
+                inputReady: false,
+                exitCode: null,
+                error: '',
+                failure: null,
+                reconnectAttempt: 0,
+                reconnectDelayMs: 0,
+                reattached: false
+            }
+        ];
+        this.#runtime.set(key, { controller: null, requested: false, reattachTimer: null });
+        this.#activeKey = key;
+        this.#pickerOpen = false;
+        this.#requestedHostUnavailable = false;
+        this.#emit();
+        return key;
+    }
+    /** `<Terminal onReady>` for a tab: start the session at the fitted grid. */
+    terminalReady(key, dims) {
+        const tab = this.#tab(key);
+        const runtime = this.#runtime.get(key);
+        if (!tab || !runtime || runtime.requested || tab.status !== 'opening')
+            return;
+        runtime.requested = true;
+        void this.#openSession(key, tab, runtime, dims);
+    }
+    /** Retry a failed tab in place (same host + command, new session). */
+    retry(key, dims) {
+        const tab = this.#tab(key);
+        const runtime = this.#runtime.get(key);
+        if (!tab || !runtime || tab.status !== 'failed')
+            return;
+        tab.session?.kill();
+        this.#patch(key, { status: 'opening', session: null, sessionId: null, error: '', inputReady: false });
+        runtime.requested = false;
+        this.terminalReady(key, dims);
+    }
+    inputReady(key) {
+        const tab = this.#tab(key);
+        if (tab && !tab.inputReady && tab.session)
+            this.#patch(key, { inputReady: true });
+    }
+    exited(key, exitCode) {
+        const tab = this.#tab(key);
+        if (!tab || tab.status === 'exited')
+            return;
+        this.#patch(key, { status: 'exited', exitCode, inputReady: false, reattached: false });
+    }
+    disconnected(key, reason) {
+        const tab = this.#tab(key);
+        if (!tab || tab.status === 'exited')
+            return;
+        this.#patch(key, {
+            status: 'failed',
+            inputReady: false,
+            reattached: false,
+            error: reason ? `Connection lost — ${reason}` : 'Connection lost and could not be restored.'
+        });
+    }
+    select(key) {
+        if (!this.#tab(key))
+            return;
+        this.#activeKey = key;
+        this.#pickerOpen = false;
+        this.#emit();
+    }
+    /** Close a tab: abort an in-flight open, end a live session. */
+    close(key) {
+        const tab = this.#tab(key);
+        if (!tab)
+            return;
+        this.#release(key, tab);
+        const index = this.#tabs.findIndex((candidate) => candidate.key === key);
+        this.#tabs = this.#tabs.filter((candidate) => candidate.key !== key);
+        if (this.#activeKey === key) {
+            this.#activeKey = this.#tabs[Math.min(index, this.#tabs.length - 1)]?.key ?? '';
+        }
+        if (this.#tabs.length === 0)
+            this.#pickerOpen = true;
+        this.#emit();
+    }
+    showPicker() {
+        this.#pickerOpen = true;
+        this.#emit();
+    }
+    /** Dismiss the picker (only when a tab can be shown behind it). */
+    hidePicker() {
+        if (this.#tabs.length === 0)
+            return;
+        this.#pickerOpen = false;
+        this.#emit();
+    }
+    /** Unmount: abort opens and end every session this workspace started. */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const tab of this.#tabs)
+            this.#release(tab.key, tab);
+        this.#listeners.clear();
+    }
+    async #openSession(key, tab, runtime, dims) {
+        const controller = new AbortController();
+        runtime.controller = controller;
+        const live = () => !this.#disposed && !controller.signal.aborted && this.#tab(key) !== undefined;
+        const outcome = await this.#options
+            .openSession({
+            hostId: tab.hostId,
+            command: tab.command,
+            cols: dims.cols,
+            rows: dims.rows,
+            signal: controller.signal,
+            reconnect: {
+                onReconnecting: (attempt, delayMs) => {
+                    if (!live())
+                        return;
+                    this.#clearReattached(runtime);
+                    this.#patch(key, {
+                        status: 'reconnecting',
+                        reconnectAttempt: attempt,
+                        reconnectDelayMs: delayMs,
+                        reattached: false
+                    });
+                },
+                onReconnected: () => {
+                    if (!live())
+                        return;
+                    this.#patch(key, { status: 'live', reconnectAttempt: 0, reconnectDelayMs: 0, reattached: true });
+                    this.#clearReattached(runtime);
+                    runtime.reattachTimer = setTimeout(() => {
+                        runtime.reattachTimer = null;
+                        if (this.#tab(key))
+                            this.#patch(key, { reattached: false });
+                    }, this.#options.reattachedNoticeMs ?? 3000);
+                }
+            }
+        })
+            .then((opened) => ({ kind: 'opened', opened }), (cause) => ({ kind: 'failure', failure: CapabilityError.from(CaughtFailureSchema.parse(cause)) }));
+        if (runtime.controller === controller)
+            runtime.controller = null;
+        if (outcome.kind === 'opened' && !live()) {
+            outcome.opened.session.kill();
+            return;
+        }
+        if (!live())
+            return;
+        if (outcome.kind === 'failure') {
+            const describe = this.#options.describeError ?? describeTerminalHostFailure;
+            this.#patch(key, { status: 'failed', failure: outcome.failure, error: describe(outcome.failure, tab.hostLabel) });
+            return;
+        }
+        this.#patch(key, { status: 'live', session: outcome.opened.session, sessionId: outcome.opened.id });
+        void outcome.opened.session.exited().then((result) => this.exited(key, result.exitCode), (cause) => this.#lost(key, CapabilityError.from(CaughtFailureSchema.parse(cause))));
+    }
+    /** The session's exit wait failed: the transport is gone and could not reconnect. */
+    #lost(key, failure) {
+        const tab = this.#tab(key);
+        if (!tab || tab.status === 'exited')
+            return;
+        this.#patch(key, {
+            status: 'failed',
+            inputReady: false,
+            reattached: false,
+            failure,
+            error: 'Connection lost and could not be restored.'
+        });
+    }
+    #release(key, tab) {
+        const runtime = this.#runtime.get(key);
+        if (runtime) {
+            runtime.controller?.abort();
+            runtime.controller = null;
+            this.#clearReattached(runtime);
+        }
+        this.#runtime.delete(key);
+        if (tab.session && tab.status !== 'exited')
+            tab.session.kill();
+    }
+    #clearReattached(runtime) {
+        if (runtime.reattachTimer !== null) {
+            clearTimeout(runtime.reattachTimer);
+            runtime.reattachTimer = null;
+        }
+    }
+    #tab(key) {
+        return this.#tabs.find((tab) => tab.key === key);
+    }
+    #patch(key, patch) {
+        if (this.#disposed)
+            return;
+        this.#tabs = this.#tabs.map((tab) => (tab.key === key ? { ...tab, ...patch } : tab));
+        this.#emit();
+    }
+    #build() {
+        return {
+            tabs: this.#tabs,
+            activeKey: this.#activeKey,
+            pickerOpen: this.#pickerOpen,
+            requestedHostUnavailable: this.#requestedHostUnavailable,
+            pickerHostId: this.#pickerHostId,
+            pickerCommand: this.#pickerCommand
+        };
+    }
+    #emit() {
+        if (this.#disposed)
+            return;
+        this.#snapshot = this.#build();
+        for (const listener of this.#listeners)
+            listener(this.#snapshot);
+    }
+}

package/dist/svelte/terminal-svelte.plugin.d.ts

@@ -1,3 +1,5 @@
+/** Settles after every widget registration this module queued so far (none when Kit is absent). */
+export declare function toolWidgetsRegistered(): Promise<void>;
 /**
  * Designed Kit card for `tools/tool:terminal`. Queued as `tools/ui` when the
  * kind is not yet registered so docs-only hosts can still load this plugin.

package/dist/svelte/terminal-svelte.plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-svelte.plugin.d.ts","sourceRoot":"","sources":["../../src/svelte/terminal-svelte.plugin.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;CAU1C,CAAC;AAEF,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAID,eAAO,MAAM,oBAAoB,6CAiB/B,CAAC;AAEH,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"terminal-svelte.plugin.d.ts","sourceRoot":"","sources":["../../src/svelte/terminal-svelte.plugin.ts"],"names":[],"mappings":"AAcA,mGAAmG;AACnG,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;CAU1C,CAAC;AAEF,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAID,eAAO,MAAM,oBAAoB,6CAiB/B,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/dist/svelte/terminal-svelte.plugin.js

@@ -1,8 +1,19 @@
 import { createRuntimeImplementation, createRuntimePlugin, loader, settle } from '@vibesdotdev/kernel';
 import terminalSvelteDocsDescriptor from "./docs/terminal-svelte.docs.descriptor.js";
 const loadTerminalToolCard = () => import('./tool-widgets/TerminalToolCard.svelte');
-const kitToolWidgets = await settle(() => import('@vibesdotdev/kit/components/tool-widgets'));
-const registerKitToolWidget = kitToolWidgets.ok ? kitToolWidgets.value.registerToolWidget : undefined;
+// Kit's widget registry loads lazily: a top-level await here would suspend every importer and,
+// inside a module cycle, let WebKit run a dependent before this module's bindings exist.
+const kitToolWidgets = settle(() => import('@vibesdotdev/kit/components/tool-widgets'));
+function registerKitToolWidget(...args) {
+    void kitToolWidgets.then((kit) => {
+        if (kit.ok)
+            kit.value.registerToolWidget(...args);
+    });
+}
+/** Settles after every widget registration this module queued so far (none when Kit is absent). */
+export function toolWidgetsRegistered() {
+    return kitToolWidgets.then(() => undefined);
+}
 /**
  * Designed Kit card for `tools/tool:terminal`. Queued as `tools/ui` when the
  * kind is not yet registered so docs-only hosts can still load this plugin.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@vibesdotdev/terminal-client",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "dependencies": {
     "@opentui/react": "^0.5.17",
     "@vibesdotdev/docs-contracts": "^1.0.0-rc.4",
-    "@vibesdotdev/logging": "^1.0.0-rc.3",
-    "@vibesdotdev/kernel-rpc": "^1.0.0-rc.2",
-    "@vibesdotdev/host-bun": "^1.0.0-rc.2",
+    "@vibesdotdev/logging": "^1.0.0-rc.5",
+    "@vibesdotdev/kernel-rpc": "^1.0.0-rc.4",
+    "@vibesdotdev/host-bun": "^1.0.0-rc.3",
     "@vibesdotdev/tui": "^1.0.0-rc.2",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
@@ -15,11 +15,11 @@
   },
   "peerDependencies": {
     "@lucide/svelte": "^1.59.0",
-    "@vibesdotdev/kernel": "^1.0.0-rc.5",
-    "@vibesdotdev/kit": "^1.0.0-rc.2",
-    "@vibesdotdev/execution-local": "^1.0.0-rc.3",
+    "@vibesdotdev/kernel": "^1.0.0-rc.0",
+    "@vibesdotdev/kit": "^1.0.0-rc.0",
+    "@vibesdotdev/execution-local": "^1.0.0-rc.0",
     "svelte": "^5.57.2",
-    "@vibesdotdev/surface-sveltekit": "^1.0.0-rc.2"
+    "@vibesdotdev/surface-sveltekit": "^1.0.0-rc.0"
   },
   "optionalDependencies": {
     "@xterm/addon-webgl": "^0.19.0"
@@ -221,10 +221,10 @@
       "optional": true
     }
   },
-  "gitHead": "51230ebdad54bc405014633f435b499fa2a06b89",
+  "gitHead": "f1ff526c235b10c970497738beb16b0651c428c8",
   "_vibes_source": {
     "repo": "ssh://git@git.vibes.dev/vibesdotdev/framework.git",
-    "sha": "51230ebdad54bc405014633f435b499fa2a06b89",
-    "workspaceDigest": "sha256:ad943c70c92aa7226c82519c5853f5ea66f36aaa9c0515a093d9bba8c189272a"
+    "sha": "f1ff526c235b10c970497738beb16b0651c428c8",
+    "workspaceDigest": "sha256:05ad771f6531189784ed3a20b0c2018f7e69e557018ae5a578a8f03b194190cc"
   }
 }