@antelopejs/dms-ai 0.0.1

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

@@ -0,0 +1,177 @@
+// 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.
+//
+// Protocol:
+//   iframe → host : { type: "dms-ai:ready" }            (chatbox announces mount)
+//   host → iframe : { type: "dms-ai:theme", mode, primary }
+// See sidecar/chatbox/src/composables/useHostTheme.ts for the receiver.
+
+const THEME_MESSAGE_TYPE = 'dms-ai:theme'
+const READY_MESSAGE_TYPE = 'dms-ai:ready'
+
+const PRIMARY_STEPS = [
+	'50',
+	'100',
+	'200',
+	'300',
+	'400',
+	'500',
+	'600',
+	'700',
+	'800',
+	'900',
+	'950',
+] as const
+
+// Nuxt UI semantic surface/text/border tokens. The host DMS may override these
+// with bespoke values (e.g. the DMS dark canvas is #0a0b12, not the default
+// neutral-900), so the chatbox can't just rely on the default neutral palette —
+// it has to mirror the host's resolved values for a faithful match in both modes.
+const SEMANTIC_TOKENS = [
+	'--ui-bg',
+	'--ui-bg-muted',
+	'--ui-bg-elevated',
+	'--ui-bg-accented',
+	'--ui-bg-inverted',
+	'--ui-text-dimmed',
+	'--ui-text-muted',
+	'--ui-text-toned',
+	'--ui-text',
+	'--ui-text-highlighted',
+	'--ui-text-inverted',
+	'--ui-border',
+	'--ui-border-muted',
+	'--ui-border-accented',
+	'--ui-border-inverted',
+] as const
+
+export interface HostTheme {
+	mode: 'dark' | 'light'
+	primary: Record<string, string>
+	tokens: Record<string, string>
+}
+
+export function readHostMode(): 'dark' | 'light' {
+	return document.documentElement.classList.contains('dark') ? 'dark' : 'light'
+}
+
+interface ResolvedColors {
+	primary: Record<string, string>
+	tokens: Record<string, string>
+}
+
+// Resolve CSS custom properties to concrete color strings. They are authored as
+// `var(--color-…)` chains, so we read them through a throwaway probe whose
+// computed `color` forces full var() resolution (getComputedStyle on the custom
+// property itself may return the unresolved `var(...)` token in some browsers).
+// A variable the host does not define is skipped entirely: `color: var(--undef)`
+// falls back to the *inherited* color, so the probe would otherwise report a
+// bogus concrete value (e.g. black) instead of "missing" — leaving downstream
+// guards/fallbacks ineffective.
+function readResolvedColors(): ResolvedColors {
+	const rootStyle = getComputedStyle(document.documentElement)
+	const probe = document.createElement('span')
+	probe.style.cssText =
+		'position:absolute;width:0;height:0;overflow:hidden;visibility:hidden;pointer-events:none;'
+	document.body.appendChild(probe)
+	const probeStyle = getComputedStyle(probe)
+	const resolve = (name: string): string => {
+		if (rootStyle.getPropertyValue(name).trim() === '') return ''
+		probe.style.color = `var(${name})`
+		return probeStyle.color
+	}
+	const primary: Record<string, string> = {}
+	for (const step of PRIMARY_STEPS) {
+		const value = resolve(`--ui-color-primary-${step}`)
+		if (value !== '') primary[step] = value
+	}
+	const tokens: Record<string, string> = {}
+	for (const name of SEMANTIC_TOKENS) {
+		const value = resolve(name)
+		if (value !== '') tokens[name] = value
+	}
+	probe.remove()
+	return { primary, tokens }
+}
+
+export function readHostTheme(): HostTheme {
+	const { primary, tokens } = readResolvedColors()
+	return { mode: readHostMode(), primary, tokens }
+}
+
+function themeSignature(theme: HostTheme): string {
+	const primary = PRIMARY_STEPS.map((s) => theme.primary[s]).join(',')
+	const tokens = SEMANTIC_TOKENS.map((t) => theme.tokens[t]).join(',')
+	return `${theme.mode}|${primary}|${tokens}`
+}
+
+interface MessageData {
+	type?: unknown
+}
+
+type ThemePush = (force: boolean) => void
+
+// Only answer the handshake from our own iframe, never an arbitrary frame.
+function answerReadyHandshake(
+	iframe: HTMLIFrameElement,
+	post: ThemePush,
+): void {
+	globalThis.addEventListener('message', (event: MessageEvent) => {
+		const type = (event.data as MessageData)?.type
+		if (type === READY_MESSAGE_TYPE && event.source === iframe.contentWindow) {
+			post(true)
+		}
+	})
+}
+
+// @nuxtjs/color-mode toggles `.dark` on <html>; mirror those changes live.
+function watchHostModeChanges(post: ThemePush): void {
+	const observer = new MutationObserver(() => post(false))
+	observer.observe(document.documentElement, {
+		attributes: true,
+		attributeFilter: ['class'],
+	})
+}
+
+// Wire the bridge to a chatbox iframe: reply to its `ready` handshake and
+// re-push the theme whenever the host flips light/dark. Primary/token swaps
+// alone are not mirrored live — they only reach the iframe on the forced
+// pushes (`ready` handshake and iframe `load`).
+// `onTheme` fires on every (re)push so the caller can keep host-side chrome
+// (the overlay backdrop / iframe color-scheme) in sync with live mode changes —
+// without it, an OS-driven dark switch leaves the panel edge on its old shade
+// until the page is reloaded.
+export function installThemeBridge(
+	iframe: HTMLIFrameElement,
+	onTheme?: (theme: HostTheme) => void,
+): void {
+	let lastMode: 'dark' | 'light' | '' = ''
+	let lastSignature = ''
+
+	const post: ThemePush = (force) => {
+		// The observer fires on any <html> class mutation (scroll locks, modal or
+		// route classes…). Gate the expensive probe resolution behind a cheap mode
+		// check: only a light/dark flip changes what this bridge mirrors live, and
+		// primary/token swaps are re-pushed on the `force` paths (ready/load).
+		const mode = readHostMode()
+		if (!force && mode === lastMode) return
+		lastMode = mode
+		const theme = readHostTheme()
+		const signature = themeSignature(theme)
+		if (!force && signature === lastSignature) return
+		lastSignature = signature
+		onTheme?.(theme)
+		iframe.contentWindow?.postMessage(
+			{ type: THEME_MESSAGE_TYPE, ...theme },
+			'*',
+		)
+	}
+
+	answerReadyHandshake(iframe, post)
+	watchHostModeChanges(post)
+	// Belt and suspenders for the case where the iframe loaded before its
+	// message listener was ready and the `ready` handshake was missed.
+	iframe.addEventListener('load', () => post(true))
+}

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

@@ -0,0 +1,196 @@
+import { createBackoff, nextDelay, resetBackoff } from './backoff'
+import {
+	HELLO_MESSAGE_TYPE,
+	HOST_ROLE,
+	LOG_PREFIX,
+	PAGE_PROTOCOL_SECURE,
+	WS_HOST_PATH,
+	WS_PROTOCOL_INSECURE,
+	WS_PROTOCOL_SECURE,
+	WS_RECONNECT_DELAYS_MS,
+	WS_STATUS_CONNECTED,
+	WS_STATUS_CONNECTING,
+	WS_STATUS_DISCONNECTED,
+	WS_STATUS_RECONNECTING,
+} from './constants'
+
+export type ConnectionStatus =
+	| typeof WS_STATUS_CONNECTING
+	| typeof WS_STATUS_CONNECTED
+	| typeof WS_STATUS_DISCONNECTED
+	| typeof WS_STATUS_RECONNECTING
+
+interface CreateHostWsClientOptions {
+	sidecarHost: string
+	// The sidecar's port is read fresh on every (re)connect: an idle-exit + respawn
+	// lands on a new random port, so a fixed port could never reconnect. Returns
+	// null while no port is known yet, in which case connecting is deferred.
+	getPort: () => number | null
+	getClientToken: () => string | null
+	onMessage?: (raw: unknown) => void
+	onStatusChange?: (status: ConnectionStatus) => void
+}
+
+interface HostWsClient {
+	close: () => void
+	isConnected: () => boolean
+	send: (msg: unknown) => void
+	getStatus: () => ConnectionStatus
+	// Drop any pending backoff and reconnect immediately against the current port.
+	// Called when the status controller has relearned a fresh port.
+	reconnectNow: () => void
+}
+
+export function buildWsUrl(host: string, port: number): string {
+	const isSecure = window.location.protocol === PAGE_PROTOCOL_SECURE
+	const scheme = isSecure ? WS_PROTOCOL_SECURE : WS_PROTOCOL_INSECURE
+	return `${scheme}//${host}:${port}${WS_HOST_PATH}`
+}
+
+interface ConnectHandlers {
+	onOpen: (socket: WebSocket) => void
+	onClose: () => void
+	onError: (event: Event) => void
+	onMessage: (raw: unknown) => void
+}
+
+export function connect(
+	url: string,
+	handlers: ConnectHandlers,
+	token: string,
+): WebSocket {
+	const socket = new WebSocket(url, `dms-ai.${token}`)
+	socket.addEventListener('open', () => handlers.onOpen(socket))
+	socket.addEventListener('close', () => handlers.onClose())
+	socket.addEventListener('error', (event) => handlers.onError(event))
+	socket.addEventListener('message', (event) => handlers.onMessage(event.data))
+	return socket
+}
+
+function sendHello(socket: WebSocket): void {
+	const payload = { type: HELLO_MESSAGE_TYPE, role: HOST_ROLE }
+	socket.send(JSON.stringify(payload))
+}
+
+function logError(event: Event): void {
+	console.error(`${LOG_PREFIX} ws error`, event)
+}
+
+function buildOnMessage(
+	options: CreateHostWsClientOptions,
+): (raw: unknown) => void {
+	const handler = options.onMessage
+	if (handler === undefined) return () => {}
+	return handler
+}
+
+interface StatusController {
+	get: () => ConnectionStatus
+	set: (next: ConnectionStatus) => void
+}
+
+function createStatusController(
+	notify: (status: ConnectionStatus) => void,
+): StatusController {
+	let current: ConnectionStatus = WS_STATUS_CONNECTING
+	return {
+		get: () => current,
+		set: (next) => {
+			if (current === next) return
+			current = next
+			notify(next)
+		},
+	}
+}
+
+function buildStatusNotifier(
+	options: CreateHostWsClientOptions,
+): (status: ConnectionStatus) => void {
+	const handler = options.onStatusChange
+	if (handler === undefined) return () => {}
+	return handler
+}
+
+export function createHostWsClient(
+	options: CreateHostWsClientOptions,
+): HostWsClient {
+	const onMessage = buildOnMessage(options)
+	const status = createStatusController(buildStatusNotifier(options))
+	const backoff = createBackoff()
+	let socket: WebSocket | null = null
+	let retryTimer: ReturnType<typeof setTimeout> | null = null
+	let isIntentionallyClosed = false
+	const open = () => {
+		if (isIntentionallyClosed) return
+		const port = options.getPort()
+		const token = options.getClientToken()
+		// No port yet (sidecar reviving): stay in reconnecting and wait — the
+		// controller calls reconnectNow() once it relearns one.
+		if (port === null || !token) {
+			status.set(WS_STATUS_RECONNECTING)
+			scheduleRetry()
+			return
+		}
+		socket = connect(
+			buildWsUrl(options.sidecarHost, port),
+			{
+				onOpen: (s) => {
+					resetBackoff(backoff)
+					status.set(WS_STATUS_CONNECTED)
+					sendHello(s)
+				},
+				onClose: () => handleClose(),
+				onError: logError,
+				onMessage,
+			},
+			token,
+		)
+	}
+	const scheduleRetry = () => {
+		if (retryTimer !== null) return
+		const delay = nextDelay(backoff, WS_RECONNECT_DELAYS_MS)
+		retryTimer = setTimeout(() => {
+			retryTimer = null
+			open()
+		}, delay)
+	}
+	const handleClose = () => {
+		socket = null
+		if (isIntentionallyClosed) {
+			status.set(WS_STATUS_DISCONNECTED)
+			return
+		}
+		status.set(WS_STATUS_RECONNECTING)
+		scheduleRetry()
+	}
+	status.set(WS_STATUS_CONNECTING)
+	open()
+	return {
+		close: () => {
+			isIntentionallyClosed = true
+			if (retryTimer !== null) {
+				clearTimeout(retryTimer)
+				retryTimer = null
+			}
+			socket?.close()
+		},
+		isConnected: () => socket?.readyState === WebSocket.OPEN,
+		send: (msg: unknown) => socket?.send(JSON.stringify(msg)),
+		getStatus: () => status.get(),
+		reconnectNow: () => {
+			if (isIntentionallyClosed) return
+			if (retryTimer !== null) {
+				clearTimeout(retryTimer)
+				retryTimer = null
+			}
+			resetBackoff(backoff)
+			// A live socket on the old port is stale after a port change; drop it and
+			// reopen. If it was already open on the right port, onClose reopens too.
+			if (socket !== null) {
+				socket.close()
+				return
+			}
+			open()
+		},
+	}
+}

package/frontend-vue/dms.frontend.ts

@@ -0,0 +1,26 @@
+import { defineAsyncComponent, type Component } from 'vue'
+import type { DmsFrontendModule } from '#dms-inertia/frontend-module'
+import aiPlugin from './app/plugins/ai.client'
+
+interface VueModule {
+	default: Component
+}
+
+const components = import.meta.glob<VueModule>('./app/components/**/*.vue')
+
+const frontendModule: DmsFrontendModule = {
+	setup(sdk) {
+		Object.entries(components)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.forEach(([path, loader]) => {
+				const name = `DmsAi${path
+					.split('/')
+					.at(-1)!
+					.replace(/\.vue$/, '')}`
+				sdk.registerComponent(name, defineAsyncComponent(loader))
+			})
+		sdk.registerPlugin(aiPlugin, { clientOnly: true })
+	},
+}
+
+export default frontendModule

package/frontend-vue/eslint.config.mjs

@@ -0,0 +1,24 @@
+import eslint from '@eslint/js'
+import ts from 'typescript-eslint'
+import vue from 'eslint-plugin-vue'
+import globals from 'globals'
+
+export default ts.config(
+	{ ignores: ['dist/**', 'node_modules/**'] },
+	eslint.configs.recommended,
+	...vue.configs['flat/essential'],
+	{
+		files: ['**/*.{ts,vue}'],
+		languageOptions: {
+			parserOptions: { parser: ts.parser },
+			globals: { ...globals.browser, ...globals.node },
+		},
+		rules: {
+			'no-undef': 'off',
+			'no-unused-vars': 'off',
+			'no-redeclare': 'off',
+			'vue/multi-word-component-names': 'off',
+		},
+	},
+	{ files: ['**/*.ts'], languageOptions: { parser: ts.parser } },
+)

package/frontend-vue/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@antelopejs/dms-ai-frontend-vue",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"license": "Apache-2.0",
+	"packageManager": "pnpm@10.6.5",
+	"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",
+		"format": "prettier --write .",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"test": "vitest run --passWithNoTests"
+	},
+	"dependencies": {
+		"@inertiajs/vue3": "^3.7.0",
+		"vue": "^3.5.18"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.0.0",
+		"typescript-eslint": "^8.0.0",
+		"eslint": "^9.0.0",
+		"eslint-plugin-vue": "^10.0.0",
+		"globals": "^16.0.0",
+		"@vitest/runner": "^4.1.5",
+		"jsdom": "^29.1.1",
+		"prettier": "^3.5.3",
+		"typescript": "^5.8.2",
+		"vitest": "^4.1.5",
+		"vue-tsc": "^3.1.1"
+	}
+}