@miragon/mcp-toolkit-ui 0.10.1

package/src/app/builder/builder-reducer.ts

@@ -0,0 +1,289 @@
+/**
+ * Pure reducer for the LayoutBuilder draft state.
+ *
+ * Replaces the `setDraft((prev) => …)` closures that previously lived in
+ * `layout-builder.tsx`, plus the `setState`-inside-an-updater anti-pattern
+ * those closures used to keep `activeTabIndex` / `focusedRowIndex` in sync
+ * with structural draft changes. Those index updates are now part of each
+ * action's pure result, so the whole thing is testable without React.
+ */
+import type { RowDef } from "@miragon/mcp-toolkit-core"
+import { emptyRows, type DraftLayout, type DraftTab } from "./builder-model.js"
+
+// -------------------------------------------------------------------------- //
+// State
+// -------------------------------------------------------------------------- //
+
+/**
+ * The draft plus the UI indices that are coupled to draft mutations.
+ * `editingTabIdx` is the inline-rename target; it is cleared whenever a
+ * structural tab change could invalidate it.
+ */
+export interface BuilderDraftState {
+  draft: DraftLayout
+  activeTabIndex: number
+  focusedRowIndex: number
+  editingTabIdx: number | null
+  /**
+   * Monotonic counter bumped whenever a `renameTab` action is rejected
+   * (duplicate label). The UI watches it to surface feedback; a counter
+   * rather than a boolean so two consecutive identical rejections still
+   * register as a change.
+   */
+  renameRejectedAt: number
+}
+
+export function initBuilderState(draft: DraftLayout): BuilderDraftState {
+  return {
+    draft,
+    activeTabIndex: 0,
+    focusedRowIndex: 0,
+    editingTabIdx: null,
+    renameRejectedAt: 0,
+  }
+}
+
+// -------------------------------------------------------------------------- //
+// Actions
+// -------------------------------------------------------------------------- //
+
+export type BuilderAction =
+  | { type: "addWidgetToRow"; widgetId: string; defaultSpan: number; targetRowIdx?: number }
+  | { type: "addRow" }
+  | { type: "removeRow"; rowIdx: number }
+  | { type: "moveRow"; rowIdx: number; direction: -1 | 1 }
+  | { type: "setCellSpan"; rowIdx: number; cellIdx: number; span: number }
+  | { type: "removeCell"; rowIdx: number; cellIdx: number }
+  | {
+      type: "setCellProps"
+      rowIdx: number
+      cellIdx: number
+      next: Record<string, unknown> | undefined
+    }
+  | { type: "setFocusedRow"; rowIdx: number }
+  | { type: "selectTab"; tabIdx: number }
+  | { type: "startEditingTab"; tabIdx: number }
+  | { type: "stopEditingTab" }
+  | { type: "addTab" }
+  | { type: "renameTab"; tabIdx: number; label: string }
+  | { type: "removeTab"; tabIdx: number }
+
+// -------------------------------------------------------------------------- //
+// Helpers
+// -------------------------------------------------------------------------- //
+
+/** The rows surface the active tab (or the flat draft) currently exposes. */
+function activeRowsOf(draft: DraftLayout, activeTabIndex: number): RowDef[] {
+  return draft.kind === "tabs" ? (draft.tabs[activeTabIndex]?.rows ?? []) : draft.rows
+}
+
+/** Clamp a focused-row index into the bounds of `rows`, never below 0. */
+function clampRowIndex(rowIndex: number, rowCount: number): number {
+  return Math.max(0, Math.min(rowIndex, rowCount - 1))
+}
+
+/**
+ * Applies a pure rows-transform to whichever surface is active (the flat
+ * rows or the active tab's rows) and returns the new draft.
+ */
+function mapActiveRows(
+  draft: DraftLayout,
+  activeTabIndex: number,
+  fn: (rows: RowDef[]) => RowDef[],
+): DraftLayout {
+  if (draft.kind === "rows") return { kind: "rows", rows: fn(draft.rows) }
+  const tabs = draft.tabs.map((t, idx) => (idx === activeTabIndex ? { ...t, rows: fn(t.rows) } : t))
+  return { kind: "tabs", tabs }
+}
+
+// -------------------------------------------------------------------------- //
+// Reducer
+// -------------------------------------------------------------------------- //
+
+export function draftReducer(state: BuilderDraftState, action: BuilderAction): BuilderDraftState {
+  switch (action.type) {
+    case "addWidgetToRow": {
+      const rows = activeRowsOf(state.draft, state.activeTabIndex)
+      const safeLen = rows.length > 0 ? rows.length : 1
+      const idx = Math.min(Math.max(action.targetRowIdx ?? state.focusedRowIndex, 0), safeLen - 1)
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
+        const safeRows = rs.length > 0 ? rs : emptyRows()
+        return safeRows.map((r, i) =>
+          i === idx
+            ? { row: [...r.row, { widget: action.widgetId, span: action.defaultSpan }] }
+            : r,
+        )
+      })
+      return { ...state, draft, focusedRowIndex: idx }
+    }
+
+    case "addRow": {
+      let newIndex = state.focusedRowIndex
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
+        const next = [...rows, { row: [] }]
+        newIndex = next.length - 1
+        return next
+      })
+      return { ...state, draft, focusedRowIndex: newIndex }
+    }
+
+    case "removeRow": {
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
+        const next = rows.filter((_, i) => i !== action.rowIdx)
+        return next.length > 0 ? next : emptyRows()
+      })
+      // Matches the previous behaviour: decrement, floored at 0. Finding [9]
+      // clamping is scoped to tab switch / removeTab, so this stays as-is.
+      return { ...state, draft, focusedRowIndex: Math.max(0, state.focusedRowIndex - 1) }
+    }
+
+    case "moveRow": {
+      const target = action.rowIdx + action.direction
+      const rows = activeRowsOf(state.draft, state.activeTabIndex)
+      if (target < 0 || target >= rows.length) return state
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
+        const next = [...rs]
+        const [moved] = next.splice(action.rowIdx, 1)
+        if (!moved) return rs
+        next.splice(target, 0, moved)
+        return next
+      })
+      return { ...state, draft, focusedRowIndex: target }
+    }
+
+    case "setCellSpan": {
+      const clamped = Math.max(1, Math.min(12, action.span))
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+        rows.map((r, i) =>
+          i === action.rowIdx
+            ? { row: r.row.map((c, j) => (j === action.cellIdx ? { ...c, span: clamped } : c)) }
+            : r,
+        ),
+      )
+      return { ...state, draft }
+    }
+
+    case "removeCell": {
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+        rows.map((r, i) =>
+          i === action.rowIdx ? { row: r.row.filter((_, j) => j !== action.cellIdx) } : r,
+        ),
+      )
+      return { ...state, draft }
+    }
+
+    case "setCellProps": {
+      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+        rows.map((r, i) =>
+          i === action.rowIdx
+            ? {
+                row: r.row.map((c, j) => {
+                  if (j !== action.cellIdx) return c
+                  if (action.next === undefined) {
+                    const rest: typeof c = { widget: c.widget }
+                    if (c.span !== undefined) rest.span = c.span
+                    return rest
+                  }
+                  return { ...c, props: action.next }
+                }),
+              }
+            : r,
+        ),
+      )
+      return { ...state, draft }
+    }
+
+    case "setFocusedRow":
+      return { ...state, focusedRowIndex: Math.max(0, action.rowIdx) }
+
+    case "selectTab": {
+      if (state.draft.kind !== "tabs") return state
+      if (action.tabIdx < 0 || action.tabIdx >= state.draft.tabs.length) return state
+      const rows = state.draft.tabs[action.tabIdx]?.rows ?? []
+      return {
+        ...state,
+        activeTabIndex: action.tabIdx,
+        focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
+      }
+    }
+
+    case "startEditingTab":
+      return { ...state, editingTabIdx: action.tabIdx }
+
+    case "stopEditingTab":
+      return { ...state, editingTabIdx: null }
+
+    case "addTab": {
+      if (state.draft.kind === "tabs") {
+        const label = `Tab ${state.draft.tabs.length + 1}`
+        const nextTabs: DraftTab[] = [...state.draft.tabs, { label, rows: emptyRows() }]
+        return {
+          ...state,
+          draft: { kind: "tabs", tabs: nextTabs },
+          activeTabIndex: nextTabs.length - 1,
+        }
+      }
+      const seededTabs: DraftTab[] = [
+        { label: "Tab 1", rows: state.draft.rows },
+        { label: "Tab 2", rows: emptyRows() },
+      ]
+      return { ...state, draft: { kind: "tabs", tabs: seededTabs }, activeTabIndex: 1 }
+    }
+
+    case "renameTab": {
+      const trimmed = action.label.trim()
+      if (!trimmed) return state
+      if (state.draft.kind !== "tabs") return state
+      // Reject duplicates — Tabs keys by label, collisions break the
+      // component. Signal the rejection so the UI can give feedback; the
+      // old label stays put.
+      if (state.draft.tabs.some((t, i) => i !== action.tabIdx && t.label === trimmed)) {
+        return { ...state, renameRejectedAt: state.renameRejectedAt + 1 }
+      }
+      const tabs = state.draft.tabs.map((t, i) =>
+        i === action.tabIdx ? { ...t, label: trimmed } : t,
+      )
+      return { ...state, draft: { kind: "tabs", tabs } }
+    }
+
+    case "removeTab": {
+      if (state.draft.kind !== "tabs") return state
+      const tabs = state.draft.tabs.filter((_, i) => i !== action.tabIdx)
+      const activeTabIndex = clampRowIndex(state.activeTabIndex, tabs.length)
+      if (tabs.length === 0) {
+        const draft: DraftLayout = { kind: "rows", rows: emptyRows() }
+        return {
+          ...state,
+          draft,
+          activeTabIndex: 0,
+          editingTabIdx: null,
+          focusedRowIndex: clampRowIndex(state.focusedRowIndex, draft.rows.length),
+        }
+      }
+      if (tabs.length === 1 && tabs[0]) {
+        const draft: DraftLayout = { kind: "rows", rows: tabs[0].rows }
+        return {
+          ...state,
+          draft,
+          activeTabIndex: 0,
+          editingTabIdx: null,
+          focusedRowIndex: clampRowIndex(state.focusedRowIndex, draft.rows.length),
+        }
+      }
+      const rows = tabs[activeTabIndex]?.rows ?? []
+      return {
+        ...state,
+        draft: { kind: "tabs", tabs },
+        activeTabIndex,
+        editingTabIdx: null,
+        focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
+      }
+    }
+
+    default: {
+      // Exhaustiveness guard: a new action type without a case is a type error.
+      const _never: never = action
+      return _never
+    }
+  }
+}

package/src/app/builder/labels.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared label contract for the visual LayoutBuilder.
+ *
+ * Extracted from `layout-builder.tsx` so the presentational sub-components
+ * (Toolbar, PipelineStrip, Workspace, CatalogueSheet, SaveDialog, PreviewPane)
+ * can depend on the labels without importing the orchestrating container —
+ * which would create an import cycle. React-free and `mcp-use`-free.
+ */
+
+export interface LayoutBuilderLabels {
+  title?: string
+  builderBadge?: string
+  previewBadge?: string
+  catalogue?: string
+  save?: string
+  done?: string
+  viewLayoutTab?: string
+  viewPipelineTab?: string
+  viewPreviewTab?: string
+  saveDialogTitle?: string
+  saveDialogDescription?: string
+  saveNameLabel?: string
+  saveDescriptionLabel?: string
+  saveConfirm?: string
+  cancel?: string
+  pipelineHeader?: string
+  keysHeader?: string
+  stepsHeader?: string
+  keyName?: string
+  keyValue?: string
+  stepContextId?: string
+  stepPickerLabel?: string
+  addKey?: string
+  addStep?: string
+  emptyKeys?: string
+  emptySteps?: string
+  statusUpToDate?: string
+  statusPending?: string
+  statusRefreshing?: string
+  paletteHeader?: string
+  paletteEmpty?: string
+  canvasEmpty?: string
+  canvasDropHint?: string
+  addRow?: string
+  addTab?: string
+  removeRow?: string
+  renameTab?: string
+  removeTab?: string
+  tabsLabel?: string
+  catalogueDescription?: string
+  catalogueKeys?: string
+  catalogueSteps?: string
+  catalogueUnreachable?: string
+  catalogueUnreachableEmpty?: string
+  catalogueProducedBy?: string
+  catalogueConsumedBy?: string
+  catalogueNeedsKeys?: string
+  cataloguePickKey?: string
+  catalogueAddProducingStep?: string
+  catalogueLive?: string
+  catalogueMissing?: string
+  /** Banner shown when the catalogue fetch fails (prefixes the reason). */
+  catalogueError?: string
+  /** Heading for the pipeline-validation warning banner. */
+  validationWarning?: string
+  /** Inline message when a save fails (prefixes the reason). */
+  saveError?: string
+  /** Inline message when a tab rename is rejected (duplicate label). */
+  renameDuplicate?: string
+}
+
+export const DEFAULT_LABELS: Required<LayoutBuilderLabels> = {
+  title: "View Builder",
+  builderBadge: "Builder",
+  previewBadge: "Preview",
+  catalogue: "Catalogue",
+  save: "Save",
+  done: "Done",
+  viewLayoutTab: "Layout",
+  viewPipelineTab: "Pipeline",
+  viewPreviewTab: "Preview",
+  saveDialogTitle: "Save dashboard",
+  saveDialogDescription:
+    "Persists the current layout along with the keys and steps that populate it.",
+  saveNameLabel: "Name",
+  saveDescriptionLabel: "Description",
+  saveConfirm: "Save dashboard",
+  cancel: "Cancel",
+  pipelineHeader: "Pipeline",
+  keysHeader: "Keys",
+  stepsHeader: "Steps",
+  keyName: "key",
+  keyValue: 'value, "literal", true, {…}',
+  stepContextId: "ctx id",
+  stepPickerLabel: "pick a step",
+  addKey: "Add key",
+  addStep: "Add step",
+  emptyKeys: "No keys seeded.",
+  emptySteps: "No steps configured.",
+  statusUpToDate: "Up to date",
+  statusPending: "Applying soon…",
+  statusRefreshing: "Applying…",
+  paletteHeader: "Palette",
+  paletteEmpty: "No widgets reachable yet — seed a key or add a step.",
+  canvasEmpty: "Drag a widget here, or click one in the palette.",
+  canvasDropHint: "Drop to add",
+  addRow: "Add row",
+  addTab: "Add tab",
+  removeRow: "Remove row",
+  renameTab: "Rename tab",
+  removeTab: "Remove tab",
+  tabsLabel: "Tabs",
+  catalogueDescription:
+    "Every key and widget the framework knows about, whether or not it's reachable right now.",
+  catalogueKeys: "Keys",
+  catalogueSteps: "Steps",
+  catalogueUnreachable: "Unreachable widgets",
+  catalogueUnreachableEmpty: "Every registered widget is reachable.",
+  catalogueProducedBy: "produced by",
+  catalogueConsumedBy: "consumed by",
+  catalogueNeedsKeys: "needs",
+  cataloguePickKey: "Add as key",
+  catalogueAddProducingStep: "Add producing step",
+  catalogueLive: "live",
+  catalogueMissing: "missing",
+  catalogueError: "Couldn't refresh the builder catalogue",
+  validationWarning: "This pipeline won't render as configured",
+  saveError: "Couldn't save",
+  renameDuplicate: "A tab with that name already exists.",
+}
+
+/**
+ * MIME type used to carry a widget id across the palette → canvas drag.
+ * Shared between the palette items and the canvas drop targets.
+ */
+export const WIDGET_DRAG_MIME = "application/x-mcp-widget-id"
+
+/** Refresh status for the auto-apply chip and the pipeline strip. */
+export type RefreshStatus = "idle" | "pending" | "refreshing"

package/src/app/builder/status-chip.tsx

@@ -0,0 +1,37 @@
+import { CircleDot, Loader2 } from "lucide-react"
+import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js"
+
+/**
+ * Compact auto-apply status chip. Shared by the Toolbar and the
+ * PipelineStrip so both surfaces show the same refresh state.
+ */
+export function StatusChip({
+  status,
+  L,
+}: {
+  status: RefreshStatus
+  L: Required<LayoutBuilderLabels>
+}) {
+  if (status === "idle") {
+    return (
+      <span className="text-muted-foreground inline-flex items-center gap-1.5">
+        <CircleDot className="size-3" />
+        {L.statusUpToDate}
+      </span>
+    )
+  }
+  if (status === "pending") {
+    return (
+      <span className="inline-flex items-center gap-1.5 text-amber-600 dark:text-amber-400">
+        <span className="size-1.5 animate-pulse rounded-full bg-amber-500" />
+        {L.statusPending}
+      </span>
+    )
+  }
+  return (
+    <span className="text-primary inline-flex items-center gap-1.5">
+      <Loader2 className="size-3 animate-spin" />
+      {L.statusRefreshing}
+    </span>
+  )
+}

package/src/app/host-bridge.test.ts

@@ -0,0 +1,206 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+import {
+  createChatGptHostBridge,
+  createStandaloneHostBridge,
+  type OpenAiAppsSdk,
+} from "./host-bridge.js"
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe("createChatGptHostBridge — no window.openai (defensive guards)", () => {
+  // Passing `null` exercises the fully-absent SDK path without touching window.
+  it("rejects callTool with a clear error instead of throwing synchronously", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const bridge = createChatGptHostBridge(null)
+
+    await expect(bridge.callTool("do_thing", {})).rejects.toThrow(
+      /OpenAI Apps SDK callTool is unavailable.*do_thing/,
+    )
+    expect(warn).toHaveBeenCalled()
+  })
+
+  it("sendFollowup is a logged no-op (no throw) when the SDK is absent", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const bridge = createChatGptHostBridge(null)
+
+    expect(() => bridge.sendFollowup("hello")).not.toThrow()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("sendFollowUpMessage unavailable"))
+  })
+
+  it("setModelContext is a logged no-op (no throw) when the SDK is absent", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const bridge = createChatGptHostBridge(null)
+
+    expect(() => bridge.setModelContext?.("ctx")).not.toThrow()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("setWidgetState unavailable"))
+  })
+
+  it("getWidgetData returns null when the SDK is absent", () => {
+    const bridge = createChatGptHostBridge(null)
+    expect(bridge.getWidgetData()).toBeNull()
+  })
+
+  it("leaves theme undefined when the SDK reports none", () => {
+    const bridge = createChatGptHostBridge(null)
+    expect(bridge.theme).toBeUndefined()
+  })
+})
+
+describe("createChatGptHostBridge — with a stubbed SDK", () => {
+  it("routes callTool through window.openai.callTool", async () => {
+    const sdk: OpenAiAppsSdk = {
+      callTool: vi.fn().mockResolvedValue({ structuredContent: { ok: true } }),
+    }
+    const bridge = createChatGptHostBridge(sdk)
+
+    const res = await bridge.callTool("get_thing", { id: 1 })
+
+    expect(sdk.callTool).toHaveBeenCalledWith("get_thing", { id: 1 })
+    expect(res).toEqual({ structuredContent: { ok: true } })
+  })
+
+  it("calls sendFollowUpMessage with the { prompt } shape", () => {
+    const sendFollowUpMessage = vi.fn().mockReturnValue(undefined)
+    const bridge = createChatGptHostBridge({ sendFollowUpMessage })
+
+    bridge.sendFollowup("show details")
+
+    expect(sendFollowUpMessage).toHaveBeenCalledWith({ prompt: "show details" })
+  })
+
+  it("falls back to the bare-string signature when { prompt } throws", () => {
+    const calls: unknown[] = []
+    const sendFollowUpMessage = vi.fn((arg: { prompt: string } | string) => {
+      calls.push(arg)
+      // Reject the object form to force the string fallback.
+      if (typeof arg !== "string") throw new Error("object form unsupported")
+    })
+    const bridge = createChatGptHostBridge({ sendFollowUpMessage })
+
+    bridge.sendFollowup("hi")
+
+    expect(calls).toEqual([{ prompt: "hi" }, "hi"])
+  })
+
+  it("accepts the alternate sendFollowupMessage spelling", () => {
+    const sendFollowupMessage = vi.fn()
+    const bridge = createChatGptHostBridge({ sendFollowupMessage })
+
+    bridge.sendFollowup("hi")
+
+    expect(sendFollowupMessage).toHaveBeenCalledWith({ prompt: "hi" })
+  })
+
+  it("opens external links via openExternal with the { href } shape", () => {
+    const openExternal = vi.fn()
+    const bridge = createChatGptHostBridge({ openExternal })
+
+    bridge.openExternal("https://example.com")
+
+    expect(openExternal).toHaveBeenCalledWith({ href: "https://example.com" })
+  })
+
+  it("prefers toolOutput over toolResponseMetadata for widget data", () => {
+    const bridge = createChatGptHostBridge({
+      toolOutput: { a: 1 },
+      toolResponseMetadata: { b: 2 },
+    })
+    expect(bridge.getWidgetData()).toEqual({ a: 1 })
+  })
+
+  it("falls back to toolResponseMetadata when toolOutput is absent", () => {
+    const bridge = createChatGptHostBridge({ toolResponseMetadata: { b: 2 } })
+    expect(bridge.getWidgetData()).toEqual({ b: 2 })
+  })
+
+  it("normalizes the theme to light | dark | undefined", () => {
+    expect(createChatGptHostBridge({ theme: "dark" }).theme).toBe("dark")
+    expect(createChatGptHostBridge({ theme: "light" }).theme).toBe("light")
+    expect(createChatGptHostBridge({ theme: "sepia" }).theme).toBeUndefined()
+  })
+})
+
+describe("createStandaloneHostBridge", () => {
+  it("routes callTool through the injected function", async () => {
+    const callTool = vi.fn().mockResolvedValue({ structuredContent: { id: "x" } })
+    const bridge = createStandaloneHostBridge({ callTool })
+
+    const res = await bridge.callTool("find", { q: "a" })
+
+    expect(callTool).toHaveBeenCalledWith("find", { q: "a" })
+    expect(res).toEqual({ structuredContent: { id: "x" } })
+  })
+
+  it("reads static getData", () => {
+    const bridge = createStandaloneHostBridge({
+      callTool: vi.fn(),
+      getData: { name: "Acme" },
+    })
+    expect(bridge.getWidgetData()).toEqual({ name: "Acme" })
+  })
+
+  it("re-reads getData when it is a getter", () => {
+    let n = 0
+    const bridge = createStandaloneHostBridge({
+      callTool: vi.fn(),
+      getData: () => ({ n: ++n }),
+    })
+    expect(bridge.getWidgetData()).toEqual({ n: 1 })
+    expect(bridge.getWidgetData()).toEqual({ n: 2 })
+  })
+
+  it("returns null from getWidgetData when no getData is supplied", () => {
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn() })
+    expect(bridge.getWidgetData()).toBeNull()
+  })
+
+  it("invokes onFollowup when supplied", () => {
+    const onFollowup = vi.fn()
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn(), onFollowup })
+
+    bridge.sendFollowup("analyse this")
+
+    expect(onFollowup).toHaveBeenCalledWith("analyse this")
+  })
+
+  it("logs and drops the prompt when no onFollowup is supplied", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn() })
+
+    expect(() => bridge.sendFollowup("dropped")).not.toThrow()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("no onFollowup handler"))
+  })
+
+  it("invokes onOpenExternal when supplied", () => {
+    const onOpenExternal = vi.fn()
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn(), onOpenExternal })
+
+    bridge.openExternal("https://x.test")
+
+    expect(onOpenExternal).toHaveBeenCalledWith("https://x.test")
+  })
+
+  it("routes setModelContext to onModelContext when supplied", () => {
+    const onModelContext = vi.fn()
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn(), onModelContext })
+
+    bridge.setModelContext?.("selected row 3")
+
+    expect(onModelContext).toHaveBeenCalledWith("selected row 3")
+  })
+
+  it("logs and drops model context when no onModelContext is supplied", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    const bridge = createStandaloneHostBridge({ callTool: vi.fn() })
+
+    expect(() => bridge.setModelContext?.("ctx")).not.toThrow()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("no onModelContext handler"))
+  })
+
+  it("passes through the configured theme", () => {
+    expect(createStandaloneHostBridge({ callTool: vi.fn(), theme: "dark" }).theme).toBe("dark")
+    expect(createStandaloneHostBridge({ callTool: vi.fn() }).theme).toBeUndefined()
+  })
+})