@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/lib/tool-result-observer.ts

@@ -0,0 +1,211 @@
+/**
+ * A passive observer of the MCP Apps (SEP-1865) host → view lifecycle
+ * notifications, read straight off the postMessage channel the view runtime
+ * itself listens on (toolkit#176 K13, N21).
+ *
+ * mcp-use 2.x latches only a result WITH `structuredContent` (or an
+ * `isError`); a content-only result, which claude.ai and Claude Desktop send,
+ * leaves its status `"pending"` forever, and its tool input merges partial and
+ * complete arguments into one field. Watching the notifications themselves
+ * tells the three cases apart that the latch cannot:
+ *
+ * - the host delivered a STRIPPED result (re-run the tool now, with the
+ *   complete arguments it was called with),
+ * - the host delivered a structured result (the latch follows; never re-run),
+ * - nothing arrived yet (a slow tool on a compliant host: keep waiting).
+ *
+ * The last case is only certain when the observer was listening before the
+ * host answered `ui/initialize` ({@link ToolObservation.sawHandshake}): hosts
+ * send the lifecycle notifications after the handshake, so an observer that
+ * saw it has seen everything sent so far. `mountMcpToolkitApp` installs it
+ * ahead of `bootstrapView` for exactly that reason.
+ *
+ * Read-only: it never sends, never answers and never stops a message.
+ */
+
+/** What the host's `ui/notifications/tool-result` carried. */
+export type ObservedToolResult = "none" | "structured" | "stripped" | "error"
+
+/** Everything the observer learned about the rendering call so far. */
+export interface ToolObservation {
+  /**
+   * The observer saw the host answer `ui/initialize`, so it was listening
+   * before any lifecycle notification could be sent: a result it has not
+   * seen has not been delivered yet.
+   */
+  sawHandshake: boolean
+  /**
+   * The arguments of the complete `ui/notifications/tool-input` — never a
+   * partial stream (`tool-input-partial` is ignored). `undefined` until it
+   * arrived.
+   */
+  completeInput: Record<string, unknown> | undefined
+  /** What the first `ui/notifications/tool-result` carried. */
+  result: ObservedToolResult
+  /** The host sent `ui/notifications/tool-cancelled`. */
+  cancelled: boolean
+}
+
+export const EMPTY_TOOL_OBSERVATION: ToolObservation = Object.freeze({
+  sawHandshake: false,
+  completeInput: undefined,
+  result: "none",
+  cancelled: false,
+})
+
+/** A host → view message the observer acts on. */
+export type HostLifecycleMessage =
+  | { kind: "handshake" }
+  | { kind: "tool-input"; arguments: Record<string, unknown> }
+  | { kind: "tool-result"; result: Exclude<ObservedToolResult, "none"> }
+  | { kind: "tool-cancelled" }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Classify a tool-result notification the way mcp-use 2.x's latch does: an
+ * `isError` result is an error, a result with `structuredContent` (even
+ * `null`) latches as ready, and anything else is the stripped, content-only
+ * result the latch ignores.
+ */
+export function classifyToolResult(
+  params: Record<string, unknown>,
+): Exclude<ObservedToolResult, "none"> {
+  if (params.isError === true) return "error"
+  return params.structuredContent === undefined ? "stripped" : "structured"
+}
+
+/** The host's answer to `ui/initialize`: a response carrying its capabilities or protocol version. */
+function isHandshakeResponse(message: Record<string, unknown>): boolean {
+  if (!("id" in message) || !isRecord(message.result)) return false
+  return (
+    isRecord(message.result.hostCapabilities) || typeof message.result.protocolVersion === "string"
+  )
+}
+
+/**
+ * Decode one postMessage payload into the lifecycle message it is, or `null`
+ * for anything else (other methods, requests, responses, foreign traffic).
+ */
+export function classifyHostMessage(data: unknown): HostLifecycleMessage | null {
+  if (!isRecord(data) || data.jsonrpc !== "2.0") return null
+  if (typeof data.method !== "string") {
+    return isHandshakeResponse(data) ? { kind: "handshake" } : null
+  }
+  const params = isRecord(data.params) ? data.params : {}
+  switch (data.method) {
+    case "ui/notifications/tool-input":
+      return {
+        kind: "tool-input",
+        arguments: isRecord(params.arguments) ? params.arguments : {},
+      }
+    case "ui/notifications/tool-result":
+      return { kind: "tool-result", result: classifyToolResult(params) }
+    case "ui/notifications/tool-cancelled":
+      return { kind: "tool-cancelled" }
+    default:
+      return null
+  }
+}
+
+/**
+ * Fold one message into the observation. Like the mcp-use latch, the call
+ * settles once: after its result or cancellation, later inputs, results and
+ * cancellations change nothing.
+ */
+export function reduceToolObservation(
+  state: ToolObservation,
+  message: HostLifecycleMessage,
+): ToolObservation {
+  if (message.kind === "handshake") {
+    return state.sawHandshake ? state : { ...state, sawHandshake: true }
+  }
+  if (state.result !== "none" || state.cancelled) return state
+  switch (message.kind) {
+    case "tool-input":
+      return { ...state, completeInput: message.arguments }
+    case "tool-result":
+      return { ...state, result: message.result }
+    case "tool-cancelled":
+      return { ...state, cancelled: true }
+  }
+}
+
+/** The `window` slice the observer listens on (any `EventTarget`, e.g. in tests). */
+export interface MessageEventSource {
+  addEventListener(type: "message", listener: (event: Event) => void): void
+  removeEventListener(type: "message", listener: (event: Event) => void): void
+}
+
+/** A subscribable observation, shaped for `useSyncExternalStore`. */
+export interface ToolResultObserver {
+  subscribe: (listener: () => void) => () => void
+  getSnapshot: () => ToolObservation
+  /** Stop listening; the last observation stays readable. */
+  dispose: () => void
+}
+
+/**
+ * Observe the lifecycle notifications arriving on `source`. `accept` filters
+ * the events (the view accepts only its host: `event.source === window.parent`,
+ * the same check the ext-apps transport makes).
+ */
+export function createToolResultObserver(
+  source: MessageEventSource,
+  accept: (event: MessageEvent) => boolean = () => true,
+): ToolResultObserver {
+  let snapshot: ToolObservation = EMPTY_TOOL_OBSERVATION
+  const listeners = new Set<() => void>()
+  const onMessage = (received: Event) => {
+    // Only `message` events are subscribed: each one is a MessageEvent.
+    const event = received as MessageEvent
+    if (!accept(event)) return
+    const message = classifyHostMessage(event.data)
+    if (!message) return
+    const next = reduceToolObservation(snapshot, message)
+    if (next === snapshot) return
+    snapshot = next
+    for (const listener of [...listeners]) listener()
+  }
+  source.addEventListener("message", onMessage)
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    getSnapshot: () => snapshot,
+    dispose: () => {
+      source.removeEventListener("message", onMessage)
+    },
+  }
+}
+
+let documentObserver: ToolResultObserver | null = null
+
+/**
+ * The view document's observer: installed once and kept for the document's
+ * lifetime (one document renders one view). `null` outside a browser and in
+ * a top-level window, where no host frames the view.
+ *
+ * It must listen before the view runtime connects, so it sees the
+ * handshake. This module therefore installs it as the bundle evaluates
+ * (below), ahead of any `bootstrapView` call in the entry module, whatever
+ * the mount; `mountMcpToolkitApp` calls it again (idempotent). Installed any
+ * later, it still sees what arrives afterwards, and the recovery falls back
+ * to its grace timer for the rest.
+ */
+export function installToolResultObserver(): ToolResultObserver | null {
+  if (documentObserver) return documentObserver
+  if (typeof window === "undefined" || window.parent === window) return null
+  const host = window.parent
+  documentObserver = createToolResultObserver(window, (event) => event.source === host)
+  return documentObserver
+}
+
+// Listen from the moment the view bundle evaluates (a passive listener; a
+// no-op outside a framed browser document).
+installToolResultObserver()

package/src/lib/typography.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest"
+import { MICRO_LABEL, TYPE_FLOOR_PX, TYPE_SCALE, TYPE_STEPS } from "./typography.js"
+import { cn } from "./utils.js"
+
+describe("the type scale (CI §4)", () => {
+  it("has five steps, each its own self-named utility", () => {
+    expect(TYPE_STEPS).toEqual(["title", "section", "body", "dense", "small"])
+    expect(TYPE_SCALE).toEqual({
+      title: "text-title",
+      section: "text-section",
+      body: "text-body",
+      dense: "text-dense",
+      small: "text-small",
+    })
+  })
+
+  it("puts the floor at the CI's smallest size and micro-labels on it, in normal case", () => {
+    expect(TYPE_FLOOR_PX).toBe(13)
+    expect(MICRO_LABEL).toBe("text-small font-semibold")
+    expect(MICRO_LABEL).not.toMatch(/uppercase|text-xs|text-\[/)
+  })
+})
+
+describe("cn knows the type scale (tailwind-merge would drop it as a colour)", () => {
+  it("keeps a scale size next to a text colour, in either order", () => {
+    for (const size of Object.values(TYPE_SCALE)) {
+      expect(cn(size, "text-muted-foreground")).toBe(`${size} text-muted-foreground`)
+      expect(cn("text-danger-ink", size)).toBe(`text-danger-ink ${size}`)
+    }
+  })
+
+  it("lets a later size win over an earlier one, scale or Tailwind", () => {
+    expect(cn("text-sm", "text-small")).toBe("text-small")
+    expect(cn("text-small", "text-xs")).toBe("text-xs")
+    expect(cn("text-dense", "text-title")).toBe("text-title")
+    expect(cn("md:text-sm", "md:text-dense")).toBe("md:text-dense")
+  })
+
+  it("keeps a leading set after the size (a size resets the line height before it)", () => {
+    expect(cn("text-small", "leading-4")).toBe("text-small leading-4")
+    expect(cn(MICRO_LABEL, "text-muted-foreground")).toBe(
+      "text-small font-semibold text-muted-foreground",
+    )
+  })
+})

package/src/lib/typography.ts

@@ -0,0 +1,47 @@
+/**
+ * The type scale of the kit (modeler-tool-design §4, adapted for embedded
+ * widgets): five steps, each a role in `theme.css` (`--text-<step>` with its
+ * line height and weight) and a Tailwind utility of the same name.
+ *
+ * | Step      | Utility        | Size / weight / line height | Use                                        |
+ * | --------- | -------------- | --------------------------- | ------------------------------------------ |
+ * | `title`   | `text-title`   | 28 px / 700 / 1.2           | page title (the CI h2; a widget has no h1 40 px) |
+ * | `section` | `text-section` | 21 px / 600 / 1.3           | section title (CI h3)                      |
+ * | `body`    | `text-body`    | 16 px / 400 / 1.6           | running text: state and toast descriptions |
+ * | `dense`   | `text-dense`   | 14 px / 400 / 1.5           | dense tables and controls (inputs, chips, count pills, the inline alert box): the documented product exception, never running text |
+ * | `small`   | `text-small`   | 13 px / 400 / 1.5           | captions, labels, hints, meta rows: the FLOOR |
+ *
+ * Nothing renders below 13 px — no `text-xs` (12 px), no `text-[10px]`
+ * micro-labels (`examples/test/design-system.test.ts` enforces it). A label
+ * that used to be a 10–11 px uppercase caption is {@link MICRO_LABEL}: 13 px,
+ * semibold, normal case.
+ *
+ * Combine the utilities through the kit's `cn`: plain tailwind-merge does not
+ * know these sizes and would drop `text-small` next to a text colour.
+ */
+
+/** The five steps, smallest last. */
+export const TYPE_STEPS = ["title", "section", "body", "dense", "small"] as const
+
+/** One step of the type scale. */
+export type TypeStep = (typeof TYPE_STEPS)[number]
+
+/** The utility class per step (`TYPE_SCALE.small` → `"text-small"`). */
+export const TYPE_SCALE: Readonly<Record<TypeStep, `text-${TypeStep}`>> = {
+  title: "text-title",
+  section: "text-section",
+  body: "text-body",
+  dense: "text-dense",
+  small: "text-small",
+}
+
+/** The smallest text the kit renders, in CSS px (CI §4 "klein"). */
+export const TYPE_FLOOR_PX = 13
+
+/**
+ * A caption above a value or a column: table heads, KPI labels, group
+ * labels. 13 px semibold in normal case — the CI floor, where these used to
+ * be 10–11 px uppercase. Typography only: add the colour
+ * (`text-muted-foreground`) at the call site.
+ */
+export const MICRO_LABEL = "text-small font-semibold"

package/src/lib/utils.ts

@@ -1,5 +1,16 @@
 import { type ClassValue, clsx } from "clsx"
-import { twMerge } from "tailwind-merge"
+import { extendTailwindMerge } from "tailwind-merge"
+import { TYPE_STEPS } from "./typography.js"
+
+/**
+ * tailwind-merge that knows the kit's type scale. Out of the box it reads
+ * an unknown `text-small` as a text COLOUR and drops it next to
+ * `text-muted-foreground`; registered as font sizes, `text-small` conflicts
+ * only with other sizes (`text-sm`, `text-xs`), as it should.
+ */
+const twMerge = extendTailwindMerge({
+  extend: { theme: { text: [...TYPE_STEPS] } },
+})
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))

package/src/locale/index.ts

@@ -3,5 +3,18 @@
 // <LocaleProvider> and reads the active locale with useLocale/useTranslate,
 // without pulling in the host runtime. Pairs with `createTranslator` from
 // `@miragon/mcp-toolkit-core`.
-export { LocaleProvider, useLocale, useTranslate } from "./locale-provider.js"
+export { LocaleProvider, useLocale, useTranslate, useToolkitMessages } from "./locale-provider.js"
 export type { LocaleContextValue, LocaleProviderProps, BoundTranslate } from "./locale-provider.js"
+export { TOOLKIT_MESSAGES, formatCount, resolveToolkitMessages } from "./toolkit-messages.js"
+export type {
+  BuilderMessages,
+  CommonMessages,
+  FilterBarMessages,
+  ListFooterMessages,
+  PropsSheetMessages,
+  RendererMessages,
+  ToolkitLocale,
+  ToolkitMessages,
+  ToolkitMessagesOverride,
+  ViewMessages,
+} from "./toolkit-messages.js"

package/src/locale/locale-provider.test.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { ListFooter } from "../components/ListFooter.js"
+import {
+  LocaleProvider,
+  ToolkitLocaleFallback,
+  useLocale,
+  useToolkitLocale,
+  useToolkitMessages,
+  useTranslate,
+  type LocaleContextValue,
+} from "./locale-provider.js"
+import { TOOLKIT_MESSAGES } from "./toolkit-messages.js"
+
+/**
+ * The locale contract: `LocaleProvider` sets the locale for everyone; the
+ * `ToolkitLocaleFallback` McpAppView mounts with the host's locale binds ONLY
+ * the toolkit's own strings and number format, so a consumer widget's
+ * `useLocale()`/`useTranslate()` keep their outside-a-provider behaviour.
+ */
+
+function Probe() {
+  const messages = useToolkitMessages()
+  return (
+    <p>
+      {`locale=${useLocale()} toolkit=${useToolkitLocale()} t=${useTranslate()("k")} close=${messages.common.close}`}
+    </p>
+  )
+}
+
+const render = (node: ReactNode) => renderToStaticMarkup(node)
+
+describe("ToolkitLocaleFallback", () => {
+  it("binds the toolkit's strings and number locale, not useLocale/useTranslate", () => {
+    expect(
+      render(
+        <ToolkitLocaleFallback locale="de-DE">
+          <Probe />
+        </ToolkitLocaleFallback>,
+      ),
+    ).toContain(`locale=en toolkit=de-DE t=k close=${TOOLKIT_MESSAGES.de.common.close}`)
+  })
+
+  it("yields to a LocaleProvider above or below it", () => {
+    const below = render(
+      <ToolkitLocaleFallback locale="de-DE">
+        <LocaleProvider locale="en-GB">
+          <Probe />
+        </LocaleProvider>
+      </ToolkitLocaleFallback>,
+    )
+    expect(below).toContain(
+      `locale=en-GB toolkit=en-GB t=k close=${TOOLKIT_MESSAGES.en.common.close}`,
+    )
+    const above = render(
+      <LocaleProvider locale="en">
+        <ToolkitLocaleFallback locale="de-DE">
+          <Probe />
+        </ToolkitLocaleFallback>
+      </LocaleProvider>,
+    )
+    expect(above).toContain(`locale=en toolkit=en t=k close=${TOOLKIT_MESSAGES.en.common.close}`)
+  })
+
+  it("keeps the defaults outside any provider", () => {
+    expect(render(<Probe />)).toContain(
+      `locale=en toolkit=en t=k close=${TOOLKIT_MESSAGES.en.common.close}`,
+    )
+  })
+
+  it("formats toolkit counts in the language of the sentence around them", () => {
+    const html = render(
+      <ToolkitLocaleFallback locale="de-DE">
+        <ListFooter shown={1200} total={4500} hasMore={false} onLoadMore={() => {}} />
+      </ToolkitLocaleFallback>,
+    )
+    expect(html).toContain("Zeigt 1.200 von 4.500 Zeilen")
+  })
+})
+
+describe("LocaleContextValue", () => {
+  it("accepts a hand-built value without messages (the field is optional)", () => {
+    const value: LocaleContextValue = { locale: "en", t: (key) => key }
+    expect(value.messages).toBeUndefined()
+  })
+})

package/src/locale/locale-provider.tsx

@@ -1,5 +1,10 @@
 import { createContext, useContext, useMemo, type ReactNode } from "react"
 import type { Translate } from "@miragon/mcp-toolkit-core"
+import {
+  resolveToolkitMessages,
+  type ToolkitMessages,
+  type ToolkitMessagesOverride,
+} from "./toolkit-messages.js"
 
 /**
  * A locale-bound translate: the active locale is already applied, so call sites
@@ -13,6 +18,14 @@ export interface LocaleContextValue {
   locale: string
   /** Translate a key in the active locale. */
   t: BoundTranslate
+  /**
+   * The toolkit's own strings for the active locale (its shipped `en`/`de`
+   * catalog, English for any other locale) with the provider's
+   * `toolkitMessages` override applied. Read it with {@link useToolkitMessages}.
+   * Optional on the type (a hand-built value may omit it); `LocaleProvider`
+   * always sets it.
+   */
+  messages?: ToolkitMessages
 }
 
 const DEFAULT_LOCALE = "en"
@@ -24,10 +37,22 @@ const DEFAULT_LOCALE = "en"
  * missing wrapper echoes the key (visible + greppable) instead of crashing a
  * widget that is perfectly renderable in English.
  */
-const DEFAULT_VALUE: LocaleContextValue = { locale: DEFAULT_LOCALE, t: (key) => key }
+const DEFAULT_VALUE = {
+  locale: DEFAULT_LOCALE,
+  t: (key) => key,
+  messages: resolveToolkitMessages(DEFAULT_LOCALE),
+} satisfies Required<LocaleContextValue>
 
 const LocaleContext = createContext<LocaleContextValue | null>(null)
 
+/** The toolkit-only locale a {@link ToolkitLocaleFallback} binds (no `t`). */
+interface ToolkitLocaleScope {
+  locale: string
+  messages: ToolkitMessages
+}
+
+const ToolkitLocaleFallbackContext = createContext<ToolkitLocaleScope | null>(null)
+
 /** Read the active locale tag from the nearest {@link LocaleProvider}. */
 export function useLocale(): string {
   return useContext(LocaleContext)?.locale ?? DEFAULT_VALUE.locale
@@ -42,6 +67,56 @@ export function useTranslate(): BoundTranslate {
   return useContext(LocaleContext)?.t ?? DEFAULT_VALUE.t
 }
 
+/**
+ * The toolkit's own UI strings for the nearest {@link LocaleProvider}'s locale
+ * (English outside a provider). Every toolkit component reads its captions,
+ * labels and accessible names here, so a German locale renders no English
+ * toolkit chrome.
+ */
+export function useToolkitMessages(): ToolkitMessages {
+  const provided = useContext(LocaleContext)
+  const fallback = useContext(ToolkitLocaleFallbackContext)
+  return provided?.messages ?? fallback?.messages ?? DEFAULT_VALUE.messages
+}
+
+/**
+ * The locale the toolkit's own text is in: the nearest {@link LocaleProvider}'s,
+ * else a {@link ToolkitLocaleFallback}'s (the host's, inside `McpAppView`),
+ * else `"en"`. Toolkit components format their numbers with it, so a count
+ * always matches the language of the sentence around it. Internal: consumer
+ * widgets read {@link useLocale}.
+ */
+export function useToolkitLocale(): string {
+  const provided = useContext(LocaleContext)
+  const fallback = useContext(ToolkitLocaleFallbackContext)
+  return provided?.locale ?? fallback?.locale ?? DEFAULT_VALUE.locale
+}
+
+/**
+ * Binds ONLY the toolkit's own strings and number format to `locale` for a
+ * subtree — the fallback `McpAppView` mounts with the host's locale. It is not
+ * a {@link LocaleProvider}: {@link useLocale} and {@link useTranslate} keep
+ * their outside-a-provider behaviour (`"en"`, echoed keys) for consumer
+ * widgets, and any `LocaleProvider` above or below wins over it.
+ */
+export function ToolkitLocaleFallback({
+  locale,
+  children,
+}: {
+  locale: string
+  children: ReactNode
+}): ReactNode {
+  const value = useMemo<ToolkitLocaleScope>(
+    () => ({ locale, messages: resolveToolkitMessages(locale) }),
+    [locale],
+  )
+  return (
+    <ToolkitLocaleFallbackContext.Provider value={value}>
+      {children}
+    </ToolkitLocaleFallbackContext.Provider>
+  )
+}
+
 export interface LocaleProviderProps {
   /** The active locale tag (e.g. `"en"`, `"de"`). */
   locale: string
@@ -51,6 +126,12 @@ export interface LocaleProviderProps {
    * consumer wires the locale before any catalog exists.
    */
   translator?: Translate
+  /**
+   * Override individual toolkit strings for this subtree, per catalog section
+   * (e.g. `{ listFooter: { loadMore: "Show more" } }`). Omitted entries keep the
+   * shipped `en`/`de` catalog of `locale`.
+   */
+  toolkitMessages?: ToolkitMessagesOverride
   children: ReactNode
 }
 
@@ -69,13 +150,19 @@ export interface LocaleProviderProps {
  *   <YourWidget />
  * </LocaleProvider>
  */
-export function LocaleProvider({ locale, translator, children }: LocaleProviderProps): ReactNode {
+export function LocaleProvider({
+  locale,
+  translator,
+  toolkitMessages,
+  children,
+}: LocaleProviderProps): ReactNode {
   const value = useMemo<LocaleContextValue>(
     () => ({
       locale,
       t: translator ? (key, params) => translator(locale, key, params) : (key) => key,
+      messages: resolveToolkitMessages(locale, toolkitMessages),
     }),
-    [locale, translator],
+    [locale, translator, toolkitMessages],
   )
   return <LocaleContext.Provider value={value}>{children}</LocaleContext.Provider>
 }