@antelopejs/dms-ai 0.1.3 → 0.1.5

package/frontend-vue/app/runtime/channel-client.ts

@@ -3,43 +3,45 @@ import {
 	createBackoff,
 	nextDelay,
 	resetBackoff,
-} from './backoff'
+} from "./backoff";
 import {
+	CHANNEL_EVENT_FRAME,
 	CHANNEL_EVENT_READY,
-	CHANNEL_EVENTS_SEGMENT,
-	CHANNEL_LIST_SEPARATOR,
+	CHANNEL_EVENTS_PATH,
 	CHANNEL_MESSAGES_SEGMENT,
+	CHANNEL_PATH,
 	CHANNEL_RECONNECT_DELAYS_MS,
 	CHANNEL_STATUS_CONNECTED,
 	CHANNEL_STATUS_CONNECTING,
 	CHANNEL_STATUS_DISCONNECTED,
 	CHANNEL_STATUS_RECONNECTING,
-	CHANNELS_PATH,
 	EVENT_STREAM_TYPE,
-} from './constants'
-import { readEventStream, type StreamEvent } from './event-stream'
+} from "./constants";
+import { readEventStream, type StreamEvent } from "./event-stream";
 
 export type ChannelStatus =
 	| typeof CHANNEL_STATUS_CONNECTING
 	| typeof CHANNEL_STATUS_CONNECTED
 	| typeof CHANNEL_STATUS_DISCONNECTED
-	| typeof CHANNEL_STATUS_RECONNECTING
+	| typeof CHANNEL_STATUS_RECONNECTING;
 
 /** Posts one message as JSON; `$authFetch` in the dashboard refreshes a stale session. */
-export type PostMessage = (path: string, body: unknown) => Promise<unknown>
+export type PostMessage = (path: string, body: unknown) => Promise<unknown>;
 
-/** Opens the event stream of a set of channels. */
-export type OpenStream = (path: string, signal: AbortSignal) => Promise<Response>
+/** Opens the tab's event stream. */
+export type OpenStream = (
+	path: string,
+	signal: AbortSignal,
+) => Promise<Response>;
 
 export interface ChannelClientOptions {
-	channels: readonly string[]
-	post: PostMessage
-	openStream?: OpenStream
-	/** Every connection is a new sidecar socket per channel: identify on it here. */
-	onReady?: () => void
-	/** Raw sidecar frame, as the socket of that channel delivered it. */
-	onFrame?: (channel: string, raw: string) => void
-	onStatusChange?: (status: ChannelStatus) => void
+	post: PostMessage;
+	openStream?: OpenStream;
+	/** Every connection is a new sidecar socket: identify on it here. */
+	onReady?: () => void;
+	/** Raw sidecar frame, as the socket delivered it. */
+	onFrame?: (raw: string) => void;
+	onStatusChange?: (status: ChannelStatus) => void;
 }
 
 export interface ChannelClient {
@@ -47,219 +49,206 @@ export interface ChannelClient {
 	 * Queued and posted one at a time, in order. False when it was dropped
 	 * because the stream is not connected, so the caller knows nothing left.
 	 */
-	send: (channel: string, msg: unknown) => boolean
-	isConnected: () => boolean
-	getStatus: () => ChannelStatus
+	send: (msg: unknown) => boolean;
+	isConnected: () => boolean;
+	getStatus: () => ChannelStatus;
 	/** Opens the stream if it is not open yet. */
-	start: () => void
+	start: () => void;
 	/** Closes the stream until the next `start`. */
-	stop: () => void
+	stop: () => void;
 	/**
 	 * Drops any pending backoff and replaces the stream at once, if started.
 	 * The status says connecting until the new stream is ready, since nothing
 	 * can be sent in between.
 	 */
-	reconnectNow: () => void
+	reconnectNow: () => void;
 }
 
 interface ReadyPayload {
-	connections?: Record<string, unknown>
-}
-
-interface QueuedMessage {
-	channel: string
-	msg: unknown
+	connectionId?: unknown;
 }
 
 interface ClientState {
-	options: ChannelClientOptions
-	status: ChannelStatus
-	connections: Record<string, string> | null
-	stream: AbortController | null
-	retryTimer: ReturnType<typeof setTimeout> | null
-	queue: QueuedMessage[]
-	isDraining: boolean
-	isStarted: boolean
-	backoff: BackoffState
-}
-
-export function channelEventsPath(channels: readonly string[]): string {
-	return `${CHANNELS_PATH}/${channels.join(CHANNEL_LIST_SEPARATOR)}/${CHANNEL_EVENTS_SEGMENT}`
+	options: ChannelClientOptions;
+	status: ChannelStatus;
+	connectionId: string | null;
+	stream: AbortController | null;
+	retryTimer: ReturnType<typeof setTimeout> | null;
+	queue: unknown[];
+	isDraining: boolean;
+	isStarted: boolean;
+	backoff: BackoffState;
 }
 
 export function channelMessagesPath(connectionId: string): string {
-	return `${CHANNELS_PATH}/${encodeURIComponent(connectionId)}/${CHANNEL_MESSAGES_SEGMENT}`
+	return `${CHANNEL_PATH}/${encodeURIComponent(connectionId)}/${CHANNEL_MESSAGES_SEGMENT}`;
 }
 
 function openEventStream(path: string, signal: AbortSignal): Promise<Response> {
 	return fetch(path, {
 		headers: { accept: EVENT_STREAM_TYPE },
-		credentials: 'same-origin',
-		cache: 'no-store',
+		credentials: "same-origin",
+		cache: "no-store",
 		signal,
-	})
+	});
 }
 
 function setStatus(state: ClientState, next: ChannelStatus): void {
-	if (state.status === next) return
-	state.status = next
-	state.options.onStatusChange?.(next)
+	if (state.status === next) return;
+	state.status = next;
+	state.options.onStatusChange?.(next);
 }
 
-function readConnections(data: string): Record<string, string> | null {
+function readConnectionId(data: string): string | null {
 	try {
-		const { connections } = JSON.parse(data) as ReadyPayload
-		if (connections === undefined || connections === null) return null
-		const entries = Object.entries(connections).filter(
-			(entry): entry is [string, string] => typeof entry[1] === 'string',
-		)
-		return Object.fromEntries(entries)
+		const { connectionId } = JSON.parse(data) as ReadyPayload;
+		return typeof connectionId === "string" ? connectionId : null;
 	} catch {
-		return null
+		return null;
 	}
 }
 
 function handleReady(state: ClientState, event: StreamEvent): void {
-	state.connections = readConnections(event.data)
-	resetBackoff(state.backoff)
-	setStatus(state, CHANNEL_STATUS_CONNECTED)
-	state.options.onReady?.()
+	state.connectionId = readConnectionId(event.data);
+	resetBackoff(state.backoff);
+	setStatus(state, CHANNEL_STATUS_CONNECTED);
+	state.options.onReady?.();
 }
 
 function handleEvent(state: ClientState, event: StreamEvent): void {
-	if (event.name === CHANNEL_EVENT_READY) return handleReady(state, event)
-	if (!state.options.channels.includes(event.name)) return
-	state.options.onFrame?.(event.name, event.data)
+	if (event.name === CHANNEL_EVENT_READY) return handleReady(state, event);
+	if (event.name !== CHANNEL_EVENT_FRAME) return;
+	state.options.onFrame?.(event.data);
 }
 
 function scheduleRetry(state: ClientState): void {
-	if (state.retryTimer !== null) return
-	const delay = nextDelay(state.backoff, CHANNEL_RECONNECT_DELAYS_MS)
+	if (state.retryTimer !== null) return;
+	const delay = nextDelay(state.backoff, CHANNEL_RECONNECT_DELAYS_MS);
 	state.retryTimer = setTimeout(() => {
-		state.retryTimer = null
-		connect(state)
-	}, delay)
+		state.retryTimer = null;
+		connect(state);
+	}, delay);
 }
 
 function lose(state: ClientState): void {
-	state.connections = null
-	state.queue = []
-	if (!state.isStarted) return
-	setStatus(state, CHANNEL_STATUS_RECONNECTING)
-	scheduleRetry(state)
-}
-
-async function run(state: ClientState, controller: AbortController): Promise<void> {
-	const open = state.options.openStream ?? openEventStream
+	state.connectionId = null;
+	state.queue = [];
+	if (!state.isStarted) return;
+	setStatus(state, CHANNEL_STATUS_RECONNECTING);
+	scheduleRetry(state);
+}
+
+async function run(
+	state: ClientState,
+	controller: AbortController,
+): Promise<void> {
+	const open = state.options.openStream ?? openEventStream;
 	try {
-		const response = await open(
-			channelEventsPath(state.options.channels),
-			controller.signal,
-		)
-		if (!response.ok || response.body === null) return
-		await readEventStream(response.body, (event) => handleEvent(state, event))
+		const response = await open(CHANNEL_EVENTS_PATH, controller.signal);
+		if (!response.ok || response.body === null) return;
+		await readEventStream(response.body, (event) => handleEvent(state, event));
 	} catch {
-		return
+		return;
 	} finally {
-		if (!controller.signal.aborted) lose(state)
+		if (!controller.signal.aborted) lose(state);
 	}
 }
 
 function connect(state: ClientState): void {
-	if (!state.isStarted) return
-	state.stream?.abort()
-	state.connections = null
-	const controller = new AbortController()
-	state.stream = controller
-	void run(state, controller)
+	if (!state.isStarted) return;
+	state.stream?.abort();
+	state.connectionId = null;
+	const controller = new AbortController();
+	state.stream = controller;
+	void run(state, controller);
 }
 
 function restart(state: ClientState): void {
-	state.stream?.abort()
-	lose(state)
+	state.stream?.abort();
+	lose(state);
 }
 
 async function drain(state: ClientState): Promise<void> {
-	if (state.isDraining) return
-	state.isDraining = true
-	while (state.queue.length > 0 && state.connections !== null) {
-		const next = state.queue.shift() as QueuedMessage
-		const connectionId = state.connections[next.channel]
-		if (connectionId === undefined) continue
+	if (state.isDraining) return;
+	state.isDraining = true;
+	while (state.queue.length > 0 && state.connectionId !== null) {
+		const next = state.queue.shift();
 		try {
-			await state.options.post(channelMessagesPath(connectionId), next.msg)
+			await state.options.post(channelMessagesPath(state.connectionId), next);
 		} catch {
-			restart(state)
+			restart(state);
 		}
 	}
-	state.isDraining = false
+	state.isDraining = false;
 }
 
-function send(state: ClientState, channel: string, msg: unknown): boolean {
-	if (state.connections?.[channel] === undefined) return false
-	state.queue.push({ channel, msg })
-	void drain(state)
-	return true
+function send(state: ClientState, msg: unknown): boolean {
+	if (state.connectionId === null) return false;
+	state.queue.push(msg);
+	void drain(state);
+	return true;
 }
 
 function clearRetry(state: ClientState): void {
-	if (state.retryTimer !== null) clearTimeout(state.retryTimer)
-	state.retryTimer = null
+	if (state.retryTimer !== null) clearTimeout(state.retryTimer);
+	state.retryTimer = null;
 }
 
 function start(state: ClientState): void {
-	if (state.isStarted) return
-	state.isStarted = true
-	resetBackoff(state.backoff)
-	setStatus(state, CHANNEL_STATUS_CONNECTING)
-	connect(state)
+	if (state.isStarted) return;
+	state.isStarted = true;
+	resetBackoff(state.backoff);
+	setStatus(state, CHANNEL_STATUS_CONNECTING);
+	connect(state);
 }
 
 function stop(state: ClientState): void {
-	if (!state.isStarted) return
-	state.isStarted = false
-	clearRetry(state)
-	state.stream?.abort()
-	state.connections = null
-	state.queue = []
-	setStatus(state, CHANNEL_STATUS_DISCONNECTED)
+	if (!state.isStarted) return;
+	state.isStarted = false;
+	clearRetry(state);
+	state.stream?.abort();
+	state.connectionId = null;
+	state.queue = [];
+	setStatus(state, CHANNEL_STATUS_DISCONNECTED);
 }
 
 function reconnectNow(state: ClientState): void {
-	if (!state.isStarted) return
-	clearRetry(state)
-	resetBackoff(state.backoff)
-	setStatus(state, CHANNEL_STATUS_CONNECTING)
-	connect(state)
+	if (!state.isStarted) return;
+	clearRetry(state);
+	resetBackoff(state.backoff);
+	setStatus(state, CHANNEL_STATUS_CONNECTING);
+	connect(state);
 }
 
 /**
- * One stream to the sidecar through the DMS carrying several channels, and
- * sequential POSTs to send on each. Browsers keep at most six HTTP/1.1
- * connections per origin, so a tab holds one such stream and only while it
- * needs it: the caller starts and stops it. While started, any end of the
- * stream — a sidecar that went down, a hot reload of dms-ai, a network drop —
- * reconnects with backoff, and each new connection is announced through
- * `onReady` so the caller identifies itself again.
+ * The tab's one stream to the sidecar through the DMS, carrying the dashboard's
+ * and the chat's frames alike, and sequential POSTs to send. Browsers keep at
+ * most six HTTP/1.1 connections per origin, so a tab holds one such stream and
+ * only while it needs it: the caller starts and stops it. While started, any
+ * end of the stream — a sidecar that went down, a hot reload of dms-ai, a
+ * network drop — reconnects with backoff, and each new connection is announced
+ * through `onReady` so the caller identifies itself again.
  */
-export function createChannelClient(options: ChannelClientOptions): ChannelClient {
+export function createChannelClient(
+	options: ChannelClientOptions,
+): ChannelClient {
 	const state: ClientState = {
 		options,
 		status: CHANNEL_STATUS_DISCONNECTED,
-		connections: null,
+		connectionId: null,
 		stream: null,
 		retryTimer: null,
 		queue: [],
 		isDraining: false,
 		isStarted: false,
 		backoff: createBackoff(),
-	}
+	};
 	return {
-		send: (channel, msg) => send(state, channel, msg),
-		isConnected: () => state.connections !== null,
+		send: (msg) => send(state, msg),
+		isConnected: () => state.connectionId !== null,
 		getStatus: () => state.status,
 		start: () => start(state),
 		stop: () => stop(state),
 		reconnectNow: () => reconnectNow(state),
-	}
+	};
 }

package/frontend-vue/app/runtime/chat-transport.ts

@@ -1,82 +1,52 @@
-import type { ChannelStatus } from './channel-client'
-import { CHAT_TRANSPORT_KEY, LOG_PREFIX } from './constants'
+import type { ChannelStatus } from "./channel-client";
+import { createListeners } from "./listeners";
 
 /**
- * What the chat document, same-origin with the dashboard, reads on its parent
- * window to reach the sidecar: the dashboard owns the tab's only stream and
- * lends the chat its channel of it.
+ * The chat's side of the tab's stream: the dashboard owns the stream and hands
+ * the chat the sidecar messages that are not host commands.
  */
 export interface ChatTransport {
-	/** Raw sidecar frames of the chat channel, in order. */
-	onFrame: (listener: (raw: string) => void) => () => void
+	/** Sidecar messages for the chat, parsed once by the dashboard, in order. */
+	onMessage: (listener: (msg: object) => void) => () => void;
 	/** Every (re)connection is a new sidecar socket: the chat says hello again. */
-	onReady: (listener: () => void) => () => void
-	onStatus: (listener: (status: ChannelStatus) => void) => () => void
-	getStatus: () => ChannelStatus
-	/** False when the message was dropped because the channel is not connected. */
-	send: (msg: unknown) => boolean
-	reconnect: () => void
+	onReady: (listener: () => void) => () => void;
+	onStatus: (listener: (status: ChannelStatus) => void) => () => void;
+	getStatus: () => ChannelStatus;
+	/** False when the message was dropped because the stream is not connected. */
+	send: (msg: unknown) => boolean;
+	reconnect: () => void;
 }
 
 export interface ChatTransportActions {
-	send: (msg: unknown) => boolean
-	reconnect: () => void
-	getStatus: () => ChannelStatus
+	send: (msg: unknown) => boolean;
+	reconnect: () => void;
+	getStatus: () => ChannelStatus;
 }
 
 export interface ChatTransportHub {
-	transport: ChatTransport
-	deliverFrame: (raw: string) => void
-	announceReady: () => void
-	announceStatus: (status: ChannelStatus) => void
-}
-
-interface Listeners<T> {
-	add: (listener: (value: T) => void) => () => void
-	emit: (value: T) => void
-}
-
-function createListeners<T>(): Listeners<T> {
-	const listeners = new Set<(value: T) => void>()
-	return {
-		add: (listener) => {
-			listeners.add(listener)
-			return () => listeners.delete(listener)
-		},
-		emit: (value) => {
-			for (const listener of listeners) {
-				try {
-					listener(value)
-				} catch (error: unknown) {
-					console.error(`${LOG_PREFIX} chat listener failed`, error)
-				}
-			}
-		},
-	}
+	transport: ChatTransport;
+	deliver: (msg: object) => void;
+	announceReady: () => void;
+	announceStatus: (status: ChannelStatus) => void;
 }
 
 export function createChatTransport(
 	actions: ChatTransportActions,
 ): ChatTransportHub {
-	const frames = createListeners<string>()
-	const ready = createListeners<undefined>()
-	const statuses = createListeners<ChannelStatus>()
+	const messages = createListeners<object>();
+	const ready = createListeners<undefined>();
+	const statuses = createListeners<ChannelStatus>();
 	return {
 		transport: {
-			onFrame: frames.add,
+			onMessage: messages.add,
 			onReady: (listener) => ready.add(() => listener()),
 			onStatus: statuses.add,
 			getStatus: actions.getStatus,
 			send: actions.send,
 			reconnect: actions.reconnect,
 		},
-		deliverFrame: frames.emit,
+		deliver: messages.emit,
 		announceReady: () => ready.emit(undefined),
 		announceStatus: statuses.emit,
-	}
-}
-
-/** Publishes the transport where the chat document looks for it. */
-export function exposeChatTransport(transport: ChatTransport): void {
-	Reflect.set(globalThis, CHAT_TRANSPORT_KEY, transport)
+	};
 }

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

@@ -1,81 +1,91 @@
-export const OVERLAY_DEFAULT_WIDTH_PX = 460
-export const OVERLAY_Z_INDEX = 999_999
-export const OVERLAY_DOM_ID = 'dms-ai-overlay-root'
-export const OVERLAY_IFRAME_ID = 'dms-ai-overlay-iframe'
-export const SIDECAR_INFO_PATH = '/ai/sidecar-info'
-/** The chat document, served through the DMS from the dashboard's own origin. */
-export const CHATBOX_PATH = '/api/ai/chatbox/'
+export const OVERLAY_DEFAULT_WIDTH_PX = 460;
+/**
+ * Above the dashboard's header and the builder's overlay (z-50), below what the
+ * dashboard portals out of the app: the DMS paints its popovers, modals and
+ * toasts in an isolated layer after the app, whatever this value is.
+ */
+export const OVERLAY_Z_INDEX = 55;
+export const OVERLAY_DOM_ID = "dms-ai-overlay-root";
+export const DMS_OVERLAYS_DOM_ID = "dms-overlays";
+export const SIDECAR_INFO_PATH = "/ai/sidecar-info";
 /** Event stream to receive, POST to send: HTTP the DMS frontend server relays. */
-export const CHANNELS_PATH = '/ai/channels'
-export const CHANNEL_EVENTS_SEGMENT = 'events'
-export const CHANNEL_MESSAGES_SEGMENT = 'messages'
-export const CHANNEL_LIST_SEPARATOR = ','
-export const HOST_CHANNEL = 'host'
-export const CHAT_CHANNEL = 'chat'
-export const CHANNEL_EVENT_READY = 'ready'
+export const CHANNEL_PATH = "/ai/channel";
+export const CHANNEL_EVENTS_PATH = `${CHANNEL_PATH}/events`;
+export const CHANNEL_MESSAGES_SEGMENT = "messages";
+export const CHANNEL_EVENT_READY = "ready";
+/** A sidecar frame: the stream's default event name. */
+export const CHANNEL_EVENT_FRAME = "message";
 /**
  * How long the stream outlives a closed panel or a hidden tab, so a quick
  * close and reopen does not reconnect, while a tab left in the background soon
  * gives back its one of the browser's six HTTP/1.1 connections to the dashboard.
  */
-export const CHANNEL_IDLE_STOP_MS = 2_000
-export const VISIBILITY_CHANGE_EVENT = 'visibilitychange'
-/** Where the chat document, same-origin, finds the dashboard's chat transport. */
-export const CHAT_TRANSPORT_KEY = 'dmsAiChatTransport'
-export const OVERLAY_OPEN_CHANGE_EVENT = 'dms-ai:open-change'
-export const EVENT_STREAM_TYPE = 'text/event-stream'
-export const JSON_CONTENT_TYPE = 'application/json'
-export const OVERLAY_BOX_SHADOW = '0 8px 24px rgba(0, 0, 0, 0.18)'
+export const CHANNEL_IDLE_STOP_MS = 2_000;
+export const VISIBILITY_CHANGE_EVENT = "visibilitychange";
+export const EVENT_STREAM_TYPE = "text/event-stream";
+export const JSON_CONTENT_TYPE = "application/json";
 export const CHANNEL_RECONNECT_DELAYS_MS = [
 	1000, 2000, 4000, 8000, 15000, 30000,
-] as const
+] as const;
 // Sidecar reachability, as seen by the host. `reviving` is the self-healing
 // state (idle-exited / crashed-respawning): the probe loop revives the sidecar
 // and the channels reconnect once it answers. `unavailable` is terminal (the
 // crash budget is spent) and needs a reload.
-export const SIDECAR_STATUS_CONNECTING = 'connecting'
-export const SIDECAR_STATUS_CONNECTED = 'connected'
-export const SIDECAR_STATUS_REVIVING = 'reviving'
-export const SIDECAR_STATUS_UNAVAILABLE = 'unavailable'
+export const SIDECAR_STATUS_CONNECTING = "connecting";
+export const SIDECAR_STATUS_CONNECTED = "connected";
+export const SIDECAR_STATUS_REVIVING = "reviving";
+export const SIDECAR_STATUS_UNAVAILABLE = "unavailable";
 // Re-probe cadence while reviving. Each probe also revives the daemon backend
 // side, so this doubles as the respawn heartbeat; capped so a genuinely stuck
 // sidecar is polled sparingly rather than hammered.
-export const SIDECAR_POLL_DELAYS_MS = [
-	500, 1000, 2000, 4000, 8000,
-] as const
-export const OVERLAY_PLACEHOLDER_ID = 'dms-ai-overlay-placeholder'
-export const PLACEHOLDER_CONNECTING_TEXT = 'Connecting the assistant…'
-export const PLACEHOLDER_REVIVING_TEXT = 'Reconnecting the assistant…'
-export const PLACEHOLDER_UNAVAILABLE_TITLE = 'Assistant unavailable'
-export const PLACEHOLDER_UNAVAILABLE_TEXT = 'Reload the page to try again.'
+export const SIDECAR_POLL_DELAYS_MS = [500, 1000, 2000, 4000, 8000] as const;
+export const PLACEHOLDER_CONNECTING_TEXT = "Connecting the assistant…";
+export const PLACEHOLDER_REVIVING_TEXT = "Reconnecting the assistant…";
+export const PLACEHOLDER_UNAVAILABLE_TITLE = "Assistant unavailable";
+export const PLACEHOLDER_UNAVAILABLE_TEXT = "Reload the page to try again.";
 
-export const CHANNEL_STATUS_CONNECTING = 'connecting'
-export const CHANNEL_STATUS_CONNECTED = 'connected'
-export const CHANNEL_STATUS_DISCONNECTED = 'disconnected'
-export const CHANNEL_STATUS_RECONNECTING = 'reconnecting'
-export const HOST_ROLE = 'host'
-export const HELLO_MESSAGE_TYPE = 'hello'
-export const LOG_PREFIX = '[dms-ai]'
-export const HOST_STATE_UPDATE_TYPE = 'host_state_update'
-export const HOST_NAVIGATION_COMPLETE_TYPE = 'host_navigation_complete'
-export const HOST_COMMAND_NAVIGATE_TYPE = 'host_command_navigate'
-export const OVERLAY_RESIZE_HANDLE_SIZE_PX = 6
-export const OVERLAY_MIN_WIDTH_PX = 320
-export const OVERLAY_PREFS_STORAGE_KEY = 'dms-ai:overlay-prefs'
-export const OVERLAY_OUTSIDE_TOGGLE_SUPPRESS_MS = 300
-export const OVERLAY_PREFS_DEBOUNCE_MS = 300
-export const TOGGLE_SHORTCUT_KEY = 'k'
-export const MODAL_OPEN_SELECTOR = '[role="dialog"][aria-modal="true"]'
+export const CHANNEL_STATUS_CONNECTING = "connecting";
+export const CHANNEL_STATUS_CONNECTED = "connected";
+export const CHANNEL_STATUS_DISCONNECTED = "disconnected";
+export const CHANNEL_STATUS_RECONNECTING = "reconnecting";
+export const HOST_ROLE = "host";
+export const HELLO_MESSAGE_TYPE = "hello";
+export const LOG_PREFIX = "[dms-ai]";
+export const HOST_STATE_UPDATE_TYPE = "host_state_update";
+export const HOST_NAVIGATION_COMPLETE_TYPE = "host_navigation_complete";
+export const HOST_COMMAND_NAVIGATE_TYPE = "host_command_navigate";
+/** Frames of the tab's stream meant for the dashboard; every other one is the chat's. */
+export const HOST_COMMAND_TYPES: ReadonlySet<string> = new Set([
+	HOST_COMMAND_NAVIGATE_TYPE,
+]);
+export const OVERLAY_MIN_WIDTH_PX = 320;
+export const OVERLAY_PREFS_STORAGE_KEY = "dms-ai:overlay-prefs";
+export const OVERLAY_OUTSIDE_TOGGLE_SUPPRESS_MS = 300;
+export const OVERLAY_PREFS_DEBOUNCE_MS = 300;
+export const TOGGLE_SHORTCUT_KEY = "k";
+export const MODAL_OPEN_SELECTOR = '[role="dialog"][aria-modal="true"]';
 
 // Generic header-action registry exposed by the DMS core (dms-back). Any module
-// can push a button by writing to this shared Nuxt state key; the core renders
+// can push a button by writing to this shared `useDmsState` key; the core renders
 // it with no knowledge of who registered it.
-export const HEADER_ACTIONS_STATE_KEY = 'dms:header-actions'
-export const LAUNCHER_ACTION_ID = 'dms-ai-launcher'
-export const LAUNCHER_ICON = 'i-ph-robot'
-export const LAUNCHER_LABEL = 'AI assistant'
-export const LAUNCHER_ORDER = 50
+export const HEADER_ACTIONS_STATE_KEY = "dms:header-actions";
+/**
+ * The DMS's persistent overlays: components rendered on every page, inside the
+ * app but outside the routed page, so they live through Inertia navigations.
+ * The state key and the component name are the whole contract.
+ */
+export const APP_OVERLAYS_STATE_KEY = "dms-app-overlays";
+export const CHAT_PANEL_COMPONENT_NAME = "DmsAiChatPanel";
+export const LAUNCHER_ACTION_ID = "dms-ai-launcher";
+/**
+ * The chat panel's header shows the same icon, which is what gets it into the
+ * renderer's icon bundle: it only scans `.vue` files for icon names.
+ */
+export const LAUNCHER_ICON = "i-ph-robot";
+export const LAUNCHER_LABEL = "AI assistant";
+export const PANEL_LABEL = LAUNCHER_LABEL;
+export const LAUNCHER_ORDER = 50;
 // Toggle shortcut, shown in the launcher tooltip. The combo is meta/ctrl + shift
 // + k, so render it the way each platform expects.
-export const TOGGLE_SHORTCUT_LABEL_MAC = '⌘⇧K'
-export const TOGGLE_SHORTCUT_LABEL_OTHER = 'Ctrl+Shift+K'
+export const TOGGLE_SHORTCUT_LABEL_MAC = "⌘⇧K";
+export const TOGGLE_SHORTCUT_LABEL_OTHER = "Ctrl+Shift+K";