@miragon/mcp-toolkit-ui 0.10.1

package/src/hooks/use-tool-result-recovery.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest"
+import { decodeRecoveredResult, resolveRecoveryToolName } from "./use-tool-result-recovery.js"
+
+// The hook's effect wiring (single-flight, StrictMode re-run, host-payload
+// precedence) is exercised end-to-end by the consumer's Playwright host
+// simulation (structuredContent keep/strip scenarios); these tests pin the
+// pure decision logic.
+
+describe("resolveRecoveryToolName", () => {
+  it("reads the SEP-1865 shape toolInfo.tool.name first", () => {
+    expect(
+      resolveRecoveryToolName({
+        toolInfo: { tool: { name: "render-view" }, name: "ignored" },
+      }),
+    ).toBe("render-view")
+  })
+
+  it("falls back to the flattened variants some hosts send", () => {
+    expect(resolveRecoveryToolName({ toolInfo: { name: "show_cockpit" } })).toBe("show_cockpit")
+    expect(resolveRecoveryToolName({ toolInfo: { toolName: "show_cockpit" } })).toBe("show_cockpit")
+  })
+
+  it("returns undefined when the tool name is missing or unusable", () => {
+    expect(resolveRecoveryToolName(undefined)).toBeUndefined()
+    expect(resolveRecoveryToolName({})).toBeUndefined()
+    expect(resolveRecoveryToolName({ toolInfo: null })).toBeUndefined()
+    expect(resolveRecoveryToolName({ toolInfo: { name: "" } })).toBeUndefined()
+    expect(resolveRecoveryToolName({ toolInfo: { name: 42 } })).toBeUndefined()
+  })
+})
+
+describe("decodeRecoveredResult", () => {
+  const isView = (v: unknown): boolean =>
+    Boolean((v as { context?: unknown; layout?: unknown } | null)?.context) &&
+    Boolean((v as { layout?: unknown } | null)?.layout)
+
+  it("decodes structuredContent-first and validates it", () => {
+    const result = {
+      content: [{ type: "text", text: "Cockpit rendered" }],
+      structuredContent: { context: { keys: {} }, layout: { rows: [] } },
+    }
+    expect(decodeRecoveredResult(result, isView)).toEqual({
+      context: { keys: {} },
+      layout: { rows: [] },
+    })
+  })
+
+  it("rejects payloads the validator refuses", () => {
+    const result = {
+      content: [{ type: "text", text: "just a summary" }],
+      structuredContent: { unrelated: true },
+    }
+    expect(decodeRecoveredResult(result, isView)).toBeNull()
+  })
+
+  it("returns null for error results instead of throwing", () => {
+    const result = { isError: true, content: [{ type: "text", text: "[503] engine down" }] }
+    expect(decodeRecoveredResult(result, isView)).toBeNull()
+  })
+
+  it("returns null for empty results", () => {
+    expect(decodeRecoveredResult(undefined, isView)).toBeNull()
+    expect(decodeRecoveredResult({ content: [] }, isView)).toBeNull()
+  })
+})

package/src/hooks/use-tool-result-recovery.ts

@@ -0,0 +1,144 @@
+import { useEffect, useRef, useState } from "react"
+import { parseToolResult } from "../lib/parse-tool-result.js"
+
+/**
+ * Recovery for hosts that deliver the `ui/notifications/tool-result`
+ * notification without `structuredContent` (observed on claude.ai and Claude
+ * Desktop, which forward only the model-facing `content` blocks). The
+ * mcp-use bridge then hands the widget an empty props object and the shell
+ * would idle on its loading skeleton forever.
+ *
+ * When the result is ready but the payload is invalid, the hook re-executes
+ * the originating tool once via the host bridge's official `callTool` —
+ * tool-call RESPONSES carry `structuredContent` intact on those hosts — and
+ * exposes the decoded payload. Spec-conforming hosts (e.g. the mcp-use
+ * inspector) deliver a valid payload up front, so the recovery never fires
+ * there.
+ *
+ * Assumes the originating tool is a read-only render pipeline (true for all
+ * toolkit `render-view`/`show_*` tools) — the re-execution must be safe to
+ * repeat.
+ */
+
+export interface ToolResultRecoveryOptions {
+  /** `!isPending` from `useWidget` — the host reported a finished tool call. */
+  resultReady: boolean
+  /** The props the host delivered (`useWidget().props`). */
+  props: unknown
+  /**
+   * Validates a candidate payload. MUST be referentially stable (module-level
+   * function or memoised) — it is an effect dependency.
+   */
+  isValid: (value: unknown) => boolean
+  /** The tool arguments from `ui/notifications/tool-input` (`useWidget().toolInput`). */
+  toolInput: Record<string, unknown> | null | undefined
+  /** Raw host context (`useWidget().hostContext`); `toolInfo` names the originating tool. */
+  hostContext: Record<string, unknown> | null | undefined
+  /** The bridge's `callTool` (`useWidget().callTool`). */
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+}
+
+export interface ToolResultRecoveryState<T> {
+  /** The recovered payload, `null` until the re-execution resolved (or when it failed). */
+  data: T | null
+  /** `true` when the single recovery attempt failed — the shell keeps its skeleton, no retry loop. */
+  failed: boolean
+}
+
+const IDLE: ToolResultRecoveryState<never> = { data: null, failed: false }
+
+/**
+ * Resolves the originating tool name from the host context's `toolInfo`.
+ * Reads the SEP-1865 shape first (`toolInfo.tool.name`), then the flattened
+ * variants some hosts send (`toolInfo.name`, `toolInfo.toolName`).
+ */
+export function resolveRecoveryToolName(hostContext: unknown): string | undefined {
+  if (!hostContext || typeof hostContext !== "object") return undefined
+  const info = (hostContext as Record<string, unknown>).toolInfo
+  if (!info || typeof info !== "object") return undefined
+  const rec = info as Record<string, unknown>
+  const tool = rec.tool
+  const candidates = [
+    tool && typeof tool === "object" ? (tool as Record<string, unknown>).name : undefined,
+    rec.name,
+    rec.toolName,
+  ]
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.length > 0) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Decodes a re-executed tool result and validates it. Exposed for tests;
+ * the hook uses it on the `callTool` response.
+ */
+export function decodeRecoveredResult<T>(
+  result: unknown,
+  isValid: (value: unknown) => boolean,
+): T | null {
+  let decoded: unknown
+  try {
+    decoded = parseToolResult<unknown>(result)
+  } catch {
+    return null
+  }
+  return decoded !== null && isValid(decoded) ? (decoded as T) : null
+}
+
+export function useToolResultRecovery<T>(
+  options: ToolResultRecoveryOptions,
+): ToolResultRecoveryState<T> {
+  const { resultReady, props, isValid, toolInput, hostContext, callTool } = options
+  const [state, setState] = useState<ToolResultRecoveryState<T>>(IDLE)
+  // Single-flight: the promise ref survives StrictMode's dev-mode
+  // effect re-run (cleanup + setup on the same instance), so the re-run
+  // re-subscribes to the SAME in-flight call instead of firing a second one.
+  const flightRef = useRef<Promise<ToolResultRecoveryState<T>> | null>(null)
+  const flightInputRef = useRef<unknown>(null)
+
+  const toolName = resolveRecoveryToolName(hostContext)
+
+  useEffect(() => {
+    // A new tool run (result no longer ready, or fresh tool-input identity)
+    // invalidates any previous recovery attempt and re-arms the single-flight.
+    if (flightRef.current && (!resultReady || flightInputRef.current !== toolInput)) {
+      flightRef.current = null
+      setState((prev) => (prev.data === null && !prev.failed ? prev : IDLE))
+    }
+    // Never fire on conforming hosts (valid payload) or before the
+    // originating tool is known.
+    if (!resultReady || isValid(props) || toolName === undefined) return
+
+    if (!flightRef.current) {
+      flightInputRef.current = toolInput
+      flightRef.current = (async (): Promise<ToolResultRecoveryState<T>> => {
+        try {
+          const result = await callTool(toolName, toolInput ?? {})
+          const data = decodeRecoveredResult<T>(result, isValid)
+          if (data !== null) return { data, failed: false }
+          console.warn(
+            `[mcp-toolkit] tool-result recovery: re-executing "${toolName}" returned no usable payload`,
+          )
+          return { data: null, failed: true }
+        } catch (err) {
+          console.warn(`[mcp-toolkit] tool-result recovery for "${toolName}" failed:`, err)
+          return { data: null, failed: true }
+        }
+      })()
+    }
+
+    const flight = flightRef.current
+    let stale = false
+    void flight.then((outcome) => {
+      // Drop the outcome when this subscription was superseded or the flight
+      // was invalidated by a newer tool run.
+      if (!stale && flightRef.current === flight) setState(outcome)
+    })
+    return () => {
+      stale = true
+    }
+  }, [resultReady, props, isValid, toolName, toolInput, callTool])
+
+  return state
+}

package/src/hooks/use-view-data.ts

@@ -0,0 +1,31 @@
+import { useToolQuery } from "./use-tool-query.js"
+
+export interface ViewDataResult<T> {
+  data: T | null
+  /** True while self-fetching with no data yet — the first paint of a cockpit cell. */
+  loading: boolean
+  error: Error | null
+}
+
+/**
+ * The seam that lets one widget component serve both modes without a duplicate UI.
+ *
+ * Standalone (a `*_show_*` widget) the agent's tool result is handed in via
+ * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`) and
+ * returned verbatim. Embedded in a self-fetching cockpit only scope params are
+ * passed, so the component fetches `tool` with `args` under `key` — disabled
+ * unless data is absent AND `ready` (i.e. the required id/key is present).
+ * Sibling widgets sharing `key` dedupe to a single call, so a composed view of
+ * N widgets over one data feed fetches once.
+ */
+export function useViewData<T>(
+  initialData: T | null | undefined,
+  key: ReadonlyArray<unknown>,
+  tool: string,
+  args: Record<string, unknown>,
+  ready: boolean,
+): ViewDataResult<T> {
+  const query = useToolQuery<T>([...key], tool, args, { enabled: !initialData && ready })
+  const data = initialData ?? query.data ?? null
+  return { data, loading: !data && ready && !query.isError, error: query.error ?? null }
+}

package/src/hooks/use-view-tool-query.ts

@@ -0,0 +1,38 @@
+import { useQuery, type UseQueryResult } from "@tanstack/react-query"
+import { useCallTool } from "../providers/query-provider.js"
+import { parseViewToolResult } from "../lib/parse-tool-result.js"
+
+export interface UseViewToolQueryOptions {
+  enabled?: boolean
+}
+
+/**
+ * Self-fetch hook for `*_show_*` widget tools — the envelope-unwrapping sibling
+ * of {@link useToolQuery}. A widget tool's text channel carries only a model
+ * summary and its `structuredContent` is the full view envelope, so decoding
+ * with the plain {@link parseToolResult} would hand the widget the whole
+ * envelope; this hook decodes via {@link parseViewToolResult} (single-step →
+ * flat data, multi-step → keyed by step id) instead.
+ *
+ * `args` is appended to the effective query key — same queryKey-vs-args
+ * contract as {@link useToolQuery}, so sibling widgets sharing a query key
+ * collapse to a single deduped tool call.
+ */
+export function useViewToolQuery<T = unknown>(
+  queryKey: unknown[],
+  toolName: string,
+  args: object,
+  opts?: UseViewToolQueryOptions,
+): UseQueryResult<T, Error> {
+  const callTool = useCallTool()
+
+  return useQuery<T, Error>({
+    queryKey: [...queryKey, args],
+    queryFn: async () => {
+      if (!callTool) throw new Error("callTool not available")
+      const result = await callTool(toolName, args)
+      return parseViewToolResult<T>(result)
+    },
+    enabled: !!callTool && (opts?.enabled ?? true),
+  })
+}

package/src/index.ts

@@ -0,0 +1,134 @@
+// shadcn base primitives
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+} from "./primitives/card.js"
+export { Badge, badgeVariants } from "./primitives/badge.js"
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "./primitives/table.js"
+export { Separator } from "./primitives/separator.js"
+export { Skeleton } from "./primitives/skeleton.js"
+export { Tabs, TabsList, TabsTrigger, TabsContent } from "./primitives/tabs.js"
+export { Button, buttonVariants } from "./primitives/button.js"
+export { Input } from "./primitives/input.js"
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "./primitives/select.js"
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+} from "./primitives/dialog.js"
+export { Alert, AlertDescription, AlertTitle } from "./primitives/alert.js"
+export { Switch } from "./primitives/switch.js"
+export { ScrollArea, ScrollBar } from "./primitives/scroll-area.js"
+export {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+} from "./primitives/sheet.js"
+
+// Hooks
+// NOTE: the view-tool hooks (`useViewToolQuery`, `useViewData`) are exported
+// from the `./hooks` subpath only — see `packages/ui/src/hooks/index.ts`.
+export { useIsMobile } from "./hooks/use-mobile.js"
+export { useToolQuery, useToolMutation } from "./hooks/use-tool-query.js"
+export type { UseToolQueryOptions } from "./hooks/use-tool-query.js"
+export { useDebouncedValue } from "./hooks/use-debounced-value.js"
+
+// Tone token system — the semantic status tones (ToneVariant + TONE_* maps)
+// behind the tone-aware components below. Pure data + class strings.
+export { TONE_SOFT, TONE_DOT, TONE_TEXT } from "./lib/tone-utils.js"
+export type { ToneVariant } from "./lib/tone-utils.js"
+
+// Composed components — focused widget building blocks assembled from the
+// primitives. Pure (React + primitives + cn), so they live in the root barrel.
+export { GridLayout, GridItem } from "./components/GridLayout.js"
+export type { GridLayoutProps, GridItemProps } from "./components/GridLayout.js"
+export { KpiGrid } from "./components/KpiGrid.js"
+export type { KpiGridProps, KpiGridHeader, KpiCell } from "./components/KpiGrid.js"
+export { LivePill, CountPill } from "./components/Pills.js"
+export type { LivePillProps, CountPillProps } from "./components/Pills.js"
+export { SectionHeading } from "./components/SectionHeading.js"
+export type { SectionHeadingProps } from "./components/SectionHeading.js"
+export { WidgetHeader } from "./components/WidgetHeader.js"
+export type { WidgetHeaderProps } from "./components/WidgetHeader.js"
+export { GroupCard } from "./components/GroupCard.js"
+export type { GroupCardProps } from "./components/GroupCard.js"
+export { FilterBar } from "./components/FilterBar.js"
+export type { FilterBarProps, FilterChip } from "./components/FilterBar.js"
+export { DrillButton } from "./components/DrillButton.js"
+export type { DrillButtonProps } from "./components/DrillButton.js"
+export { ListFooter } from "./components/ListFooter.js"
+export type { ListFooterProps } from "./components/ListFooter.js"
+
+// Providers
+export { AppQueryProvider, useCallTool, queryClient } from "./providers/query-provider.js"
+
+// Theming / white-label token system. Browser-safe (React + DOM only, no
+// `mcp-use/react`), so it belongs in this root barrel: a consumer can re-skin
+// the toolkit's primitives from a single switch without pulling in the host
+// runtime. See packages/ui/src/theme/ and docs/guides/white-labeling.md.
+export { createTheme, ThemeProvider, useTheme, themePresets } from "./theme/index.js"
+export type {
+  ThemeTokens,
+  ThemeDefinition,
+  ThemeVars,
+  CreateThemeOptions,
+  ThemeMode,
+  ThemeContextValue,
+  ThemeProviderProps,
+  ThemePresetId,
+} from "./theme/index.js"
+
+// i18n / localization. Browser-safe (React only, no `mcp-use/react`), so it
+// belongs in this root barrel: a consumer wraps its widget tree in
+// <LocaleProvider locale=… translator=…> and reads the active locale with
+// useLocale/useTranslate. Pairs with `createTranslator` from
+// `@miragon/mcp-toolkit-core`. See packages/ui/src/locale/.
+export { LocaleProvider, useLocale, useTranslate } from "./locale/index.js"
+export type { LocaleContextValue, LocaleProviderProps, BoundTranslate } from "./locale/index.js"
+
+// NOTE: MCP App shell (McpAppView, WidgetRenderer) is exported from the
+// `./app` subpath only. Keeping it out of the main barrel prevents consumers
+// that only need primitives (e.g. an admin portal) from pulling `mcp-use/react`
+// and its langchain transitive peer into their Vite bundle.
+
+// Utils
+export { cn } from "./lib/utils.js"
+export { parseToolResult, parseViewToolResult } from "./lib/parse-tool-result.js"
+export type { ParseToolResultOptions } from "./lib/parse-tool-result.js"

package/src/lib/parse-tool-result.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest"
+import { parseToolResult, parseViewToolResult } from "./parse-tool-result.js"
+
+describe("parseToolResult (structuredContent-first contract)", () => {
+  it("prefers structuredContent over the text channel", () => {
+    const result = {
+      content: [{ type: "text", text: "Process list: 2 definitions." }],
+      structuredContent: { items: [1, 2], total: 2 },
+    }
+    expect(parseToolResult(result)).toEqual({ items: [1, 2], total: 2 })
+  })
+
+  it("prefers structuredContent even when the text channel is parseable JSON", () => {
+    const result = {
+      content: [{ type: "text", text: JSON.stringify({ fromText: true }) }],
+      structuredContent: { fromStructured: true },
+    }
+    expect(parseToolResult(result)).toEqual({ fromStructured: true })
+  })
+
+  it("falls back to JSON-decoding the first text block without structuredContent", () => {
+    const result = {
+      content: [{ type: "text", text: JSON.stringify({ items: [1, 2], total: 2 }) }],
+    }
+    expect(parseToolResult(result)).toEqual({ items: [1, 2], total: 2 })
+  })
+
+  it("returns non-JSON text verbatim without structuredContent", () => {
+    const result = { content: [{ type: "text", text: "plain status line" }] }
+    expect(parseToolResult<string>(result)).toBe("plain status line")
+  })
+
+  it("falls back to the raw result when neither channel is present", () => {
+    const result = { something: "else" }
+    expect(parseToolResult(result)).toEqual({ something: "else" })
+  })
+
+  it("treats structuredContent: null as absent and falls through to text", () => {
+    const result = {
+      content: [{ type: "text", text: JSON.stringify({ fromText: true }) }],
+      structuredContent: null,
+    }
+    expect(parseToolResult(result)).toEqual({ fromText: true })
+  })
+
+  it("returns a falsy-but-present structuredContent (e.g. 0) instead of falling through", () => {
+    const result = { content: [{ type: "text", text: "summary" }], structuredContent: 0 }
+    expect(parseToolResult<number>(result)).toBe(0)
+  })
+
+  it("throws the first text block as the error message on isError results", () => {
+    const result = { isError: true, content: [{ type: "text", text: "boom" }] }
+    expect(() => parseToolResult(result)).toThrowError("boom")
+  })
+
+  it("throws a generic message on isError results without content", () => {
+    expect(() => parseToolResult({ isError: true })).toThrowError("Tool call failed")
+  })
+})
+
+describe('parseToolResult with prefer: "text"', () => {
+  it("reads the text channel first when both are present", () => {
+    const result = {
+      content: [{ type: "text", text: JSON.stringify({ fromText: true }) }],
+      structuredContent: { fromStructured: true },
+    }
+    expect(parseToolResult(result, { prefer: "text" })).toEqual({ fromText: true })
+  })
+
+  it("falls back to structuredContent when there is no text block", () => {
+    const result = { structuredContent: { fromStructured: true } }
+    expect(parseToolResult(result, { prefer: "text" })).toEqual({ fromStructured: true })
+  })
+
+  it("returns non-JSON text verbatim before consulting structuredContent", () => {
+    const result = {
+      content: [{ type: "text", text: "plain line" }],
+      structuredContent: { fromStructured: true },
+    }
+    expect(parseToolResult<string>(result, { prefer: "text" })).toBe("plain line")
+  })
+
+  it("still throws on isError results", () => {
+    const result = { isError: true, content: [{ type: "text", text: "boom" }] }
+    expect(() => parseToolResult(result, { prefer: "text" })).toThrowError("boom")
+  })
+})
+
+describe("parseViewToolResult (show-tool envelope unwrap)", () => {
+  it("unwraps a single-step view envelope to the widget's flat data", () => {
+    const result = {
+      content: [{ type: "text", text: "Model summary." }],
+      structuredContent: {
+        title: "Instances",
+        context: {
+          keys: {},
+          stepIds: ["result"],
+          stepData: { result: { data: { rows: [1], total: 1 }, keys: {} } },
+          errors: [],
+        },
+        layout: [],
+      },
+    }
+    expect(parseViewToolResult(result)).toEqual({ rows: [1], total: 1 })
+  })
+
+  it("returns multi-step composed views keyed by step id", () => {
+    const result = {
+      structuredContent: {
+        context: {
+          stepIds: ["kpis", "result_1"],
+          stepData: {
+            kpis: { data: { totalCount: 5 } },
+            result_1: { data: { patterns: [] } },
+          },
+        },
+        layout: [],
+      },
+    }
+    expect(parseViewToolResult(result)).toEqual({
+      kpis: { totalCount: 5 },
+      result_1: { patterns: [] },
+    })
+  })
+
+  it("passes non-envelope results (e.g. *_data feeds) through unchanged", () => {
+    const data = { jobs: [], totalCount: 0 }
+    const result = {
+      content: [{ type: "text", text: JSON.stringify(data) }],
+      structuredContent: data,
+    }
+    expect(parseViewToolResult(result)).toEqual(data)
+  })
+
+  it("propagates isError results as thrown errors", () => {
+    const result = { isError: true, content: [{ type: "text", text: "boom" }] }
+    expect(() => parseViewToolResult(result)).toThrowError("boom")
+  })
+})

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

@@ -0,0 +1,89 @@
+import type { ViewStructuredContent } from "@miragon/mcp-toolkit-core"
+
+export interface ParseToolResultOptions {
+  /**
+   * Which channel to read first when both are present.
+   *
+   * - `"structured"` (default): `structuredContent`-first. Since the widget-tool
+   *   "text-channel diet" the text block carries only a short model-facing
+   *   summary, while the data payload lives in `structuredContent` (the view
+   *   builders and `*_data` feeds always set it). The text channel remains a
+   *   fallback for plain results from other servers.
+   * - `"text"`: text-first (the pre-0.4 behaviour) — JSON-decode the first text
+   *   block, then fall back to `structuredContent`. Kept for callers that
+   *   deliberately prefer a tool's human-readable text payload.
+   */
+  prefer?: "structured" | "text"
+}
+
+/**
+ * Decodes an MCP tool result down to its data payload.
+ *
+ * Default (`prefer: "structured"`): `isError` → throw the first text block,
+ * then `structuredContent` (if non-null), then JSON-decode the first text
+ * block (verbatim string if it isn't JSON), then the raw result.
+ *
+ * This is **structured-first** — a deliberate, observable change from the
+ * pre-0.4 text-first parsing: tools that return BOTH a text summary and
+ * `structuredContent` now yield the structured payload, not the summary
+ * string. `useToolQuery`/`useToolMutation` and the MCP App shell all decode
+ * through this one parser so the convention is uniform.
+ */
+export function parseToolResult<T = unknown>(result: unknown, opts?: ParseToolResultOptions): T {
+  const r = result as
+    | {
+        content?: Array<{ text?: string }>
+        structuredContent?: unknown
+        isError?: boolean
+      }
+    | undefined
+  if (r?.isError) throw new Error(r.content?.[0]?.text ?? "Tool call failed")
+
+  const fromStructured = (): T | undefined =>
+    r?.structuredContent != null ? (r.structuredContent as T) : undefined
+  const fromText = (): T | undefined => {
+    const text = r?.content?.[0]?.text
+    if (text == null) return undefined
+    try {
+      return JSON.parse(text) as T
+    } catch {
+      return text as T
+    }
+  }
+
+  if (opts?.prefer === "text") {
+    const text = fromText()
+    if (text !== undefined) return text
+    const structured = fromStructured()
+    if (structured !== undefined) return structured
+    return r as T
+  }
+
+  const structured = fromStructured()
+  if (structured !== undefined) return structured
+  const text = fromText()
+  if (text !== undefined) return text
+  return r as T
+}
+
+/** Shape of the `structuredContent` envelope emitted by the view builders. */
+type ViewEnvelope = Pick<ViewStructuredContent, "context">
+
+/**
+ * Decodes a `*_show_*` widget-tool result down to the widget's flat data
+ * payload. `buildSingleWidgetView`/`buildComposedView` wrap the data in the
+ * `McpAppView` envelope (`context.stepData[<id>].data`); this unwraps it:
+ * single-step views yield the step's data directly, multi-step composed views
+ * yield an object keyed by step id. Non-envelope results (e.g. `*_data`
+ * feeds) pass through {@link parseToolResult} unchanged.
+ */
+export function parseViewToolResult<T = unknown>(result: unknown): T {
+  const parsed = parseToolResult<unknown>(result)
+  const ctx = (parsed as ViewEnvelope | null)?.context
+  const stepIds = ctx?.stepIds
+  if (ctx?.stepData && Array.isArray(stepIds) && stepIds.length > 0) {
+    if (stepIds.length === 1) return ctx.stepData[stepIds[0] ?? ""]?.data as T
+    return Object.fromEntries(stepIds.map((id) => [id, ctx.stepData[id]?.data])) as T
+  }
+  return parsed as T
+}

package/src/lib/tone-utils.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import { TONE_DOT, TONE_SOFT, TONE_TEXT, type ToneVariant } from "./tone-utils.js"
+
+const ALL_TONES: ToneVariant[] = ["neutral", "info", "success", "warning", "danger"]
+
+describe("tone-utils", () => {
+  it("covers every ToneVariant in each map (no missing tones)", () => {
+    for (const map of [TONE_SOFT, TONE_DOT, TONE_TEXT]) {
+      expect(Object.keys(map).sort()).toEqual([...ALL_TONES].sort())
+    }
+  })
+
+  it("maps each tone to a non-empty class string in every map", () => {
+    for (const tone of ALL_TONES) {
+      expect(TONE_SOFT[tone], `soft:${tone}`).toBeTruthy()
+      expect(TONE_DOT[tone], `dot:${tone}`).toBeTruthy()
+      expect(TONE_TEXT[tone], `text:${tone}`).toBeTruthy()
+    }
+  })
+
+  it("routes each status tone to its matching design token", () => {
+    expect(TONE_SOFT.danger).toBe("bg-danger-soft text-danger")
+    expect(TONE_SOFT.warning).toBe("bg-warning-soft text-warning")
+    expect(TONE_SOFT.success).toBe("bg-success-soft text-success")
+    expect(TONE_SOFT.info).toBe("bg-info-soft text-info")
+    expect(TONE_DOT.danger).toBe("bg-danger")
+    expect(TONE_TEXT.success).toBe("text-success")
+  })
+
+  it("routes the neutral tone to the shadcn muted ramp", () => {
+    expect(TONE_SOFT.neutral).toBe("bg-muted text-muted-foreground")
+    expect(TONE_DOT.neutral).toBe("bg-muted-foreground")
+    expect(TONE_TEXT.neutral).toBe("text-foreground")
+  })
+})