@antelopejs/dms-ai 0.1.2 → 0.1.4

package/frontend-vue/app/runtime/event-stream.ts

@@ -0,0 +1,75 @@
+export interface StreamEvent {
+	name: string
+	data: string
+}
+
+const DEFAULT_EVENT_NAME = 'message'
+const FRAME_SEPARATOR = /\r?\n\r?\n/
+const LINE_SEPARATOR = /\r?\n/
+const FIELD_SEPARATOR = ':'
+const EVENT_FIELD = 'event'
+const DATA_FIELD = 'data'
+
+interface Field {
+	name: string
+	value: string
+}
+
+function parseField(line: string): Field {
+	const boundary = line.indexOf(FIELD_SEPARATOR)
+	if (boundary === -1) return { name: line, value: '' }
+	const raw = line.slice(boundary + FIELD_SEPARATOR.length)
+	return {
+		name: line.slice(0, boundary),
+		value: raw.startsWith(' ') ? raw.slice(1) : raw,
+	}
+}
+
+function parseFrame(frame: string): StreamEvent | null {
+	let name = DEFAULT_EVENT_NAME
+	const data: string[] = []
+	for (const line of frame.split(LINE_SEPARATOR)) {
+		const field = parseField(line)
+		if (field.name === EVENT_FIELD) name = field.value
+		if (field.name === DATA_FIELD) data.push(field.value)
+	}
+	if (data.length === 0) return null
+	return { name, data: data.join('\n') }
+}
+
+function dispatchFrames(
+	buffer: string,
+	onEvent: (event: StreamEvent) => void,
+): string {
+	const frames = buffer.split(FRAME_SEPARATOR)
+	const rest = frames.pop() ?? ''
+	for (const frame of frames) {
+		const event = parseFrame(frame)
+		if (event !== null) onEvent(event)
+	}
+	return rest
+}
+
+/**
+ * Delivers every event of a text/event-stream body until it ends. Read over
+ * fetch rather than EventSource, like the DMS realtime stream, so a failed
+ * request surfaces its status and nothing reconnects behind the caller's back.
+ */
+export async function readEventStream(
+	body: ReadableStream<Uint8Array>,
+	onEvent: (event: StreamEvent) => void,
+): Promise<void> {
+	const reader = body.getReader()
+	const decoder = new TextDecoder()
+	let buffer = ''
+	try {
+		while (true) {
+			const chunk = await reader.read()
+			if (chunk.done) return
+			buffer += decoder.decode(chunk.value, { stream: true })
+			buffer = dispatchFrames(buffer, onEvent)
+		}
+	} finally {
+		reader.releaseLock()
+	}
+}

package/frontend-vue/app/runtime/overlay.ts

@@ -4,6 +4,7 @@ import {
 	OVERLAY_DOM_ID,
 	OVERLAY_IFRAME_ID,
 	OVERLAY_MIN_WIDTH_PX,
+	OVERLAY_OPEN_CHANGE_EVENT,
 	OVERLAY_OUTSIDE_TOGGLE_SUPPRESS_MS,
 	OVERLAY_PLACEHOLDER_ID,
 	OVERLAY_RESIZE_HANDLE_SIZE_PX,
@@ -21,6 +22,7 @@ import {
 import {
 	type HostTheme,
 	installThemeBridge,
+	isFromFrame,
 	readHostMode,
 } from './theme-bridge'
 
@@ -37,7 +39,9 @@ export interface OverlayHandle {
 	// use `toggleOpen` so it is never suppressed.
 	toggleFromLauncher: () => void
 	isOpen: () => boolean
-	// Point the frame at a (possibly new) sidecar URL. A no-op when the URL is
+	/** Called on every open or close, however the panel was toggled. */
+	onOpenChange: (listener: (isOpen: boolean) => void) => () => void
+	// Point the frame at the chat document. A no-op when the URL is
 	// unchanged and already loaded, so a redundant `connected` notify won't reload
 	// the chatbox; otherwise it reloads and shows a connecting placeholder until
 	// the frame paints.
@@ -106,9 +110,9 @@ function buildContainer(): HTMLDivElement {
 	return container
 }
 
-// Built with no `src`: the frame is only pointed at the sidecar via `repoint`
-// once the status controller confirms a reachable port, so the browser never
-// renders its native "can't reach" page for a dead port.
+// Built with no `src`: the frame is only pointed at the chat via `repoint` once
+// the status controller confirms the sidecar runs, so it never renders the
+// error page of a sidecar that is down.
 function buildIframe(): HTMLIFrameElement {
 	const iframe = document.createElement('iframe')
 	iframe.id = OVERLAY_IFRAME_ID
@@ -291,8 +295,8 @@ function createPlaceholderController(
 }
 
 // Repoint the frame at `url`, deferring the placeholder-hide until it paints so a
-// port change reloads the chatbox without flashing the previous dead frame. A
-// no-op reload when the URL is already loaded.
+// reload of the chatbox never flashes the previous frame. A no-op reload when
+// the URL is already loaded.
 function createRepointer(
 	iframe: HTMLIFrameElement,
 	placeholder: PlaceholderController,
@@ -321,9 +325,14 @@ function setOpen(
 	stateRef: OverlayPrefsRef,
 	isOpen: boolean,
 ): void {
+	const hasChanged = stateRef.value.isOpen !== isOpen
 	stateRef.value = { ...stateRef.value, isOpen }
 	applyPrefs(elements, stateRef.value)
 	writePrefsDebounced(stateRef.value)
+	if (!hasChanged) return
+	elements.container.dispatchEvent(
+		new CustomEvent(OVERLAY_OPEN_CHANGE_EVENT, { detail: isOpen }),
+	)
 }
 
 export function injectOverlay(): OverlayHandle | null {
@@ -360,6 +369,7 @@ export function injectOverlay(): OverlayHandle | null {
 	// The chatbox header's close button lives inside the iframe; it asks the
 	// host to slide the panel away via postMessage.
 	globalThis.addEventListener('message', (event: MessageEvent) => {
+		if (!isFromFrame(event, elements.iframe)) return
 		const type = (event.data as MessageData)?.type
 		if (typeof type === 'string' && CLOSE_MESSAGE_TYPES.has(type)) {
 			setOpen(elements, stateRef, false)
@@ -377,6 +387,13 @@ export function injectOverlay(): OverlayHandle | null {
 			toggle()
 		},
 		isOpen: (): boolean => stateRef.value.isOpen,
+		onOpenChange: (listener) => {
+			const onChange = (event: Event): void =>
+				listener((event as CustomEvent<boolean>).detail)
+			elements.container.addEventListener(OVERLAY_OPEN_CHANGE_EVENT, onChange)
+			return () =>
+				elements.container.removeEventListener(OVERLAY_OPEN_CHANGE_EVENT, onChange)
+		},
 		repoint,
 		showPlaceholder: (kind) => placeholder.show(kind),
 	}

package/frontend-vue/app/runtime/sidecar-status.ts

@@ -14,8 +14,6 @@ export type SidecarStatus =
 	| typeof SIDECAR_STATUS_UNAVAILABLE
 
 interface SidecarInfo {
-	port: number | null
-	clientToken: string | null
 	isRunning: boolean
 	hasGivenUp: boolean
 	disabled: boolean
@@ -27,14 +25,14 @@ export interface SidecarStatusController {
 	// is disabled for this process — so the caller skips injection entirely.
 	init: () => Promise<boolean>
 	getStatus: () => SidecarStatus
-	getPort: () => number | null
-	getClientToken: () => string | null
 	// Subscribe to status changes; fires immediately with the current status so a
 	// late subscriber (overlay/icon injected after init) reflects it right away.
 	subscribe: (cb: (status: SidecarStatus) => void) => () => void
-	// The host WebSocket dropped: re-probe now to relearn a possibly-new port
-	// rather than let the socket keep retrying the dead one.
-	reportWsDown: () => void
+	/**
+	 * The host channel dropped: re-probe now, which also revives an idle-exited
+	 * sidecar, and report `connected` again once it answers.
+	 */
+	reportChannelDown: () => void
 	dispose: () => void
 }
 
@@ -46,9 +44,6 @@ async function fetchInfo(
 	try {
 		const body = await fetchDetails()
 		return {
-			port: typeof body.port === 'number' ? body.port : null,
-			clientToken:
-				typeof body.clientToken === 'string' ? body.clientToken : null,
 			isRunning: body.isRunning === true,
 			hasGivenUp: body.hasGivenUp === true,
 			disabled: body.disabled === true,
@@ -64,8 +59,6 @@ export function createSidecarStatusController(
 	const backoff = createBackoff()
 	const subscribers = new Set<(status: SidecarStatus) => void>()
 	let status: SidecarStatus = SIDECAR_STATUS_CONNECTING
-	let port: number | null = null
-	let clientToken: string | null = null
 	let pollTimer: ReturnType<typeof setTimeout> | null = null
 	let disposed = false
 
@@ -105,19 +98,13 @@ export function createSidecarStatusController(
 			setStatus(SIDECAR_STATUS_UNAVAILABLE)
 			return
 		}
-		if (info.isRunning && info.port !== null && info.clientToken) {
-			port = info.port
-			clientToken = info.clientToken
+		if (info.isRunning) {
 			resetBackoff(backoff)
-			// A reviving→connected transition notifies via setStatus; a port change
-			// while already connected leaves the status word unchanged, so force a
-			// notify there too to drive the overlay/WS onto the new port.
-			if (status === SIDECAR_STATUS_CONNECTED) notify()
-			else setStatus(SIDECAR_STATUS_CONNECTED)
+			setStatus(SIDECAR_STATUS_CONNECTED)
 			return
 		}
 		// Down but not terminal — the probe already asked the backend to respawn;
-		// keep polling until it reports a port.
+		// keep polling until it reports the sidecar running.
 		setStatus(SIDECAR_STATUS_REVIVING)
 		schedulePoll()
 	}
@@ -131,8 +118,6 @@ export function createSidecarStatusController(
 			return true
 		},
 		getStatus: () => status,
-		getPort: () => port,
-		getClientToken: () => clientToken,
 		subscribe: (cb) => {
 			subscribers.add(cb)
 			cb(status)
@@ -140,13 +125,13 @@ export function createSidecarStatusController(
 				subscribers.delete(cb)
 			}
 		},
-		reportWsDown: () => {
+		reportChannelDown: () => {
 			if (disposed) return
 			if (status !== SIDECAR_STATUS_CONNECTED) return
 			// Surface the drop right away (amber dot + spinner) instead of waiting on
 			// the re-probe: that probe awaits a respawn and can take a second or two,
 			// during which the icon would otherwise look healthy. poll() flips back
-			// to connected once the new port is live.
+			// to connected once the sidecar answers again.
 			resetBackoff(backoff)
 			setStatus(SIDECAR_STATUS_REVIVING)
 			void poll()

package/frontend-vue/app/runtime/theme-bridge.ts

@@ -1,7 +1,8 @@
 // Theme bridge (host → chatbox iframe). The host DMS is the source of truth for
 // the active Nuxt UI primary palette and the light/dark mode; the chatbox iframe
-// is a separate document (different origin) so it cannot inherit them through
-// CSS — we forward them explicitly here.
+// is a separate document, so it cannot inherit them through CSS — we forward
+// them explicitly here. Both documents share the dashboard's origin, which is
+// the only one either side posts to or accepts messages from.
 //
 // Protocol:
 //   iframe → host : { type: "dms-ai:ready" }            (chatbox announces mount)
@@ -113,6 +114,17 @@ interface MessageData {
 
 type ThemePush = (force: boolean) => void
 
+/** True for a message the chatbox frame itself posted, from our own origin. */
+export function isFromFrame(
+	event: MessageEvent,
+	iframe: HTMLIFrameElement,
+): boolean {
+	return (
+		event.source === iframe.contentWindow &&
+		event.origin === globalThis.location.origin
+	)
+}
+
 // Only answer the handshake from our own iframe, never an arbitrary frame.
 function answerReadyHandshake(
 	iframe: HTMLIFrameElement,
@@ -120,7 +132,7 @@ function answerReadyHandshake(
 ): void {
 	globalThis.addEventListener('message', (event: MessageEvent) => {
 		const type = (event.data as MessageData)?.type
-		if (type === READY_MESSAGE_TYPE && event.source === iframe.contentWindow) {
+		if (type === READY_MESSAGE_TYPE && isFromFrame(event, iframe)) {
 			post(true)
 		}
 	})
@@ -165,7 +177,7 @@ export function installThemeBridge(
 		onTheme?.(theme)
 		iframe.contentWindow?.postMessage(
 			{ type: THEME_MESSAGE_TYPE, ...theme },
-			'*',
+			globalThis.location.origin,
 		)
 	}
 

package/frontend-vue/package.json

@@ -5,6 +5,9 @@
 	"type": "module",
 	"license": "Apache-2.0",
 	"packageManager": "pnpm@10.6.5",
+	"engines": {
+		"@antelopejs/dms-frontend": ">=0.2.8 <0.4.0"
+	},
 	"scripts": {
 		"build": "pnpm --dir \"${DMS_FRONTEND_WORKSPACE:?Set DMS_FRONTEND_WORKSPACE to the generated Inertia workspace}\" build",
 		"typecheck": "pnpm --dir \"${DMS_FRONTEND_WORKSPACE:?Set DMS_FRONTEND_WORKSPACE to the generated Inertia workspace}\" typecheck",

package/frontend-vue/tests/backoff.test.ts

@@ -4,41 +4,41 @@ import {
 	nextDelay,
 	resetBackoff,
 } from '../app/runtime/backoff'
-import { WS_RECONNECT_DELAYS_MS } from '../app/runtime/constants'
+import { CHANNEL_RECONNECT_DELAYS_MS } from '../app/runtime/constants'
 
 describe('backoff helper', () => {
 	it('returns each schedule entry in order then caps at the last value', () => {
 		const state = createBackoff()
 		const observed: number[] = []
-		for (let i = 0; i < WS_RECONNECT_DELAYS_MS.length + 3; i += 1) {
-			observed.push(nextDelay(state, WS_RECONNECT_DELAYS_MS))
+		for (let i = 0; i < CHANNEL_RECONNECT_DELAYS_MS.length + 3; i += 1) {
+			observed.push(nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS))
 		}
 		const expected = [
-			...WS_RECONNECT_DELAYS_MS,
-			WS_RECONNECT_DELAYS_MS[WS_RECONNECT_DELAYS_MS.length - 1],
-			WS_RECONNECT_DELAYS_MS[WS_RECONNECT_DELAYS_MS.length - 1],
-			WS_RECONNECT_DELAYS_MS[WS_RECONNECT_DELAYS_MS.length - 1],
+			...CHANNEL_RECONNECT_DELAYS_MS,
+			CHANNEL_RECONNECT_DELAYS_MS[CHANNEL_RECONNECT_DELAYS_MS.length - 1],
+			CHANNEL_RECONNECT_DELAYS_MS[CHANNEL_RECONNECT_DELAYS_MS.length - 1],
+			CHANNEL_RECONNECT_DELAYS_MS[CHANNEL_RECONNECT_DELAYS_MS.length - 1],
 		]
 		expect(observed).toEqual(expected)
 	})
 
 	it('resetBackoff returns the schedule to schedule[0]', () => {
 		const state = createBackoff()
-		nextDelay(state, WS_RECONNECT_DELAYS_MS)
-		nextDelay(state, WS_RECONNECT_DELAYS_MS)
+		nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)
+		nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)
 		resetBackoff(state)
-		expect(nextDelay(state, WS_RECONNECT_DELAYS_MS)).toBe(
-			WS_RECONNECT_DELAYS_MS[0],
+		expect(nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)).toBe(
+			CHANNEL_RECONNECT_DELAYS_MS[0],
 		)
 	})
 
 	it('uses the configured 30s ceiling on the last delay', () => {
 		const state = createBackoff()
-		const lastIndex = WS_RECONNECT_DELAYS_MS.length - 1
+		const lastIndex = CHANNEL_RECONNECT_DELAYS_MS.length - 1
 		for (let i = 0; i < lastIndex; i += 1) {
-			nextDelay(state, WS_RECONNECT_DELAYS_MS)
+			nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)
 		}
-		expect(nextDelay(state, WS_RECONNECT_DELAYS_MS)).toBe(30_000)
-		expect(nextDelay(state, WS_RECONNECT_DELAYS_MS)).toBe(30_000)
+		expect(nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)).toBe(30_000)
+		expect(nextDelay(state, CHANNEL_RECONNECT_DELAYS_MS)).toBe(30_000)
 	})
 })

package/frontend-vue/tests/channel-client.test.ts

@@ -0,0 +1,247 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+	type ChannelStatus,
+	createChannelClient,
+} from '../app/runtime/channel-client'
+import { CHANNEL_RECONNECT_DELAYS_MS } from '../app/runtime/constants'
+
+interface FakeStream {
+	path: string
+	emit: (name: string, data: string) => void
+	end: () => void
+}
+
+interface Harness {
+	streams: FakeStream[]
+	posts: Array<{ path: string; body: unknown }>
+	statuses: ChannelStatus[]
+	ready: ReturnType<typeof vi.fn>
+	frames: string[]
+}
+
+const encoder = new TextEncoder()
+const READY = '{"connections":{"host":"h-1","chat":"c 1"}}'
+
+function openFakeStream(
+	streams: FakeStream[],
+	path: string,
+	signal: AbortSignal,
+): Promise<Response> {
+	let controller!: ReadableStreamDefaultController<Uint8Array>
+	const body = new ReadableStream<Uint8Array>({
+		start: (c) => {
+			controller = c
+		},
+	})
+	signal.addEventListener('abort', () =>
+		controller.error(new DOMException('aborted', 'AbortError')),
+	)
+	streams.push({
+		path,
+		emit: (name, data) =>
+			controller.enqueue(encoder.encode(`event: ${name}\ndata: ${data}\n\n`)),
+		end: () => controller.close(),
+	})
+	return Promise.resolve(new Response(body, { status: 200 }))
+}
+
+function startClient(post = vi.fn(async () => undefined)) {
+	const harness: Harness = {
+		streams: [],
+		posts: [],
+		statuses: [],
+		ready: vi.fn(),
+		frames: [],
+	}
+	const client = createChannelClient({
+		channels: ['host', 'chat'],
+		post: async (path, body) => {
+			harness.posts.push({ path, body })
+			return post(path, body)
+		},
+		openStream: (path, signal) => openFakeStream(harness.streams, path, signal),
+		onReady: harness.ready,
+		onFrame: (channel, raw) => harness.frames.push(`${channel} ${raw}`),
+		onStatusChange: (status) => harness.statuses.push(status),
+	})
+	client.start()
+	return { client, harness }
+}
+
+async function flush(): Promise<void> {
+	for (let i = 0; i < 10; i += 1) await Promise.resolve()
+	await new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+afterEach(() => {
+	vi.useRealTimers()
+})
+
+describe('channel client', () => {
+	it('stays closed until started', async () => {
+		const streams: FakeStream[] = []
+		const client = createChannelClient({
+			channels: ['host', 'chat'],
+			post: vi.fn(),
+			openStream: (path, signal) => openFakeStream(streams, path, signal),
+		})
+		await flush()
+		expect(streams).toEqual([])
+		expect(client.getStatus()).toBe('disconnected')
+	})
+
+	it('opens one stream for every channel, on the dashboard origin, with no credential', async () => {
+		const { client, harness } = startClient()
+		await flush()
+		expect(harness.streams.map((stream) => stream.path)).toEqual([
+			'/ai/channels/host,chat/events',
+		])
+		client.stop()
+	})
+
+	it('announces the connection, then routes each frame by channel, raw', async () => {
+		const { client, harness } = startClient()
+		await flush()
+		harness.streams[0]?.emit('ready', READY)
+		harness.streams[0]?.emit('host', '{"type":"host_command_navigate","path":"/x"}')
+		harness.streams[0]?.emit('chat', '{"type":"run_done"}')
+		harness.streams[0]?.emit('unknown', '{}')
+		await flush()
+		expect(harness.ready).toHaveBeenCalledTimes(1)
+		expect(client.isConnected()).toBe(true)
+		expect(harness.frames).toEqual([
+			'host {"type":"host_command_navigate","path":"/x"}',
+			'chat {"type":"run_done"}',
+		])
+		client.stop()
+	})
+
+	it('posts one message at a time, in order, to the connection of its channel', async () => {
+		const pending: Array<() => void> = []
+		const post = vi.fn(
+			() => new Promise<void>((resolve) => pending.push(() => resolve())),
+		)
+		const { client, harness } = startClient(post)
+		await flush()
+		harness.streams[0]?.emit('ready', READY)
+		await flush()
+		client.send('chat', { n: 1 })
+		client.send('host', { n: 2 })
+		await flush()
+		expect(harness.posts).toEqual([
+			{ path: '/ai/channels/c%201/messages', body: { n: 1 } },
+		])
+		pending.shift()?.()
+		await flush()
+		expect(harness.posts.at(-1)).toEqual({
+			path: '/ai/channels/h-1/messages',
+			body: { n: 2 },
+		})
+		client.stop()
+	})
+
+	it('drops a message sent before the connection is ready, and says so', async () => {
+		const { client, harness } = startClient()
+		expect(client.send('chat', { n: 1 })).toBe(false)
+		await flush()
+		expect(harness.posts).toEqual([])
+		harness.streams[0]?.emit('ready', READY)
+		await flush()
+		expect(client.send('chat', { n: 2 })).toBe(true)
+		client.stop()
+	})
+
+	it('refuses a message for a channel the stream does not carry', async () => {
+		const { client, harness } = startClient()
+		await flush()
+		harness.streams[0]?.emit('ready', READY)
+		await flush()
+		expect(client.send('unknown', { n: 1 })).toBe(false)
+		await flush()
+		expect(harness.posts).toEqual([])
+		client.stop()
+	})
+
+	it('reconnects with backoff when the stream ends, and announces the new connection', async () => {
+		vi.useFakeTimers()
+		const { client, harness } = startClient()
+		await vi.advanceTimersByTimeAsync(0)
+		harness.streams[0]?.emit('ready', READY)
+		await vi.advanceTimersByTimeAsync(0)
+		harness.streams[0]?.end()
+		await vi.advanceTimersByTimeAsync(0)
+		expect(client.isConnected()).toBe(false)
+		expect(harness.statuses).toEqual(['connecting', 'connected', 'reconnecting'])
+		await vi.advanceTimersByTimeAsync(CHANNEL_RECONNECT_DELAYS_MS[0])
+		harness.streams[1]?.emit('ready', READY)
+		await vi.advanceTimersByTimeAsync(0)
+		expect(harness.streams).toHaveLength(2)
+		expect(harness.ready).toHaveBeenCalledTimes(2)
+		expect(harness.statuses.at(-1)).toBe('connected')
+		client.stop()
+	})
+
+	it('drops the connection and reconnects when a post fails', async () => {
+		vi.useFakeTimers()
+		const post = vi.fn(async () => {
+			throw new Error('404')
+		})
+		const { client, harness } = startClient(post)
+		await vi.advanceTimersByTimeAsync(0)
+		harness.streams[0]?.emit('ready', READY)
+		await vi.advanceTimersByTimeAsync(0)
+		client.send('chat', { n: 1 })
+		await vi.advanceTimersByTimeAsync(0)
+		expect(client.getStatus()).toBe('reconnecting')
+		await vi.advanceTimersByTimeAsync(CHANNEL_RECONNECT_DELAYS_MS[0])
+		expect(harness.streams).toHaveLength(2)
+		client.stop()
+	})
+
+	it('says connecting while reconnectNow replaces a live stream, until the new one is ready', async () => {
+		const { client, harness } = startClient()
+		await flush()
+		harness.streams[0]?.emit('ready', READY)
+		await flush()
+		client.reconnectNow()
+		await flush()
+		expect(client.getStatus()).toBe('connecting')
+		expect(client.send('chat', { n: 1 })).toBe(false)
+		harness.streams[1]?.emit('ready', READY)
+		await flush()
+		expect(harness.statuses).toEqual(['connecting', 'connected', 'connecting', 'connected'])
+		expect(harness.ready).toHaveBeenCalledTimes(2)
+		client.stop()
+	})
+
+	it('skips the backoff on reconnectNow', async () => {
+		vi.useFakeTimers()
+		const { client, harness } = startClient()
+		await vi.advanceTimersByTimeAsync(0)
+		harness.streams[0]?.end()
+		await vi.advanceTimersByTimeAsync(0)
+		client.reconnectNow()
+		await vi.advanceTimersByTimeAsync(0)
+		expect(harness.streams).toHaveLength(2)
+		client.stop()
+	})
+
+	it('stops reconnecting once stopped, and opens again on start', async () => {
+		vi.useFakeTimers()
+		const { client, harness } = startClient()
+		await vi.advanceTimersByTimeAsync(0)
+		client.stop()
+		await vi.advanceTimersByTimeAsync(
+			CHANNEL_RECONNECT_DELAYS_MS[CHANNEL_RECONNECT_DELAYS_MS.length - 1] * 2,
+		)
+		expect(harness.streams).toHaveLength(1)
+		expect(client.getStatus()).toBe('disconnected')
+		client.reconnectNow()
+		await vi.advanceTimersByTimeAsync(0)
+		expect(harness.streams).toHaveLength(1)
+		client.start()
+		await vi.advanceTimersByTimeAsync(0)
+		expect(harness.streams).toHaveLength(2)
+		client.stop()
+	})
+})

package/frontend-vue/tests/chat-transport.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+	createChatTransport,
+	exposeChatTransport,
+} from '../app/runtime/chat-transport'
+import { CHAT_TRANSPORT_KEY } from '../app/runtime/constants'
+
+function hub() {
+	const actions = {
+		send: vi.fn(() => true),
+		reconnect: vi.fn(),
+		getStatus: vi.fn(() => 'connected' as const),
+	}
+	return { actions, chat: createChatTransport(actions) }
+}
+
+describe('chat transport', () => {
+	it('lends the chat its channel: frames, readiness and status in, messages out', () => {
+		const { actions, chat } = hub()
+		const frames: string[] = []
+		const statuses: string[] = []
+		const ready = vi.fn()
+		chat.transport.onFrame((raw) => frames.push(raw))
+		chat.transport.onStatus((status) => statuses.push(status))
+		chat.transport.onReady(ready)
+		chat.deliverFrame('{"type":"run_done"}')
+		chat.announceStatus('reconnecting')
+		chat.announceReady()
+		expect(chat.transport.send({ type: 'hello' })).toBe(true)
+		chat.transport.reconnect()
+		expect(frames).toEqual(['{"type":"run_done"}'])
+		expect(statuses).toEqual(['reconnecting'])
+		expect(ready).toHaveBeenCalledTimes(1)
+		expect(actions.send).toHaveBeenCalledWith({ type: 'hello' })
+		expect(actions.reconnect).toHaveBeenCalledTimes(1)
+		expect(chat.transport.getStatus()).toBe('connected')
+	})
+
+	it('stops delivering to a listener once it unsubscribed', () => {
+		const { chat } = hub()
+		const frames: string[] = []
+		const unsubscribe = chat.transport.onFrame((raw) => frames.push(raw))
+		unsubscribe()
+		chat.deliverFrame('{}')
+		expect(frames).toEqual([])
+	})
+
+	it('keeps delivering when one listener throws, as a gone chat document would', () => {
+		const { chat } = hub()
+		const frames: string[] = []
+		const error = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+		chat.transport.onFrame(() => {
+			throw new Error('dead document')
+		})
+		chat.transport.onFrame((raw) => frames.push(raw))
+		chat.deliverFrame('{}')
+		expect(frames).toEqual(['{}'])
+		error.mockRestore()
+	})
+
+	it('publishes itself where the same-origin chat document looks', () => {
+		const { chat } = hub()
+		exposeChatTransport(chat.transport)
+		expect(Reflect.get(globalThis, CHAT_TRANSPORT_KEY)).toBe(chat.transport)
+		Reflect.deleteProperty(globalThis, CHAT_TRANSPORT_KEY)
+	})
+})