@miragon/mcp-toolkit-ui 1.1.0 → 2.0.0

package/src/app/mcp-app-view-chrome.tsx

@@ -0,0 +1,204 @@
+/**
+ * Presentational chrome for `McpAppView` — the toolbar, the pipeline error
+ * list, and the build/render body — plus the view-envelope types they share.
+ * Split out of `mcp-app-view.tsx` so the shell component keeps only the
+ * host-sync and state logic while this file stays hook-free.
+ */
+import { Maximize2, Minimize2, Pencil, RefreshCw } from "lucide-react"
+import type { LayoutConfig, PipelineStepRef } from "@miragon/mcp-toolkit-core"
+import { LayoutBuilder, type LayoutBuilderProps } from "./layout-builder.js"
+import { WidgetRenderer, type WidgetComponent } from "./widget-renderer.js"
+
+export interface McpAppViewLabels {
+  loading?: string
+  refresh?: string
+  refreshing?: string
+  enterFullscreen?: string
+  exitFullscreen?: string
+  build?: string
+}
+
+export const DEFAULT_LABELS: Required<McpAppViewLabels> = {
+  loading: "Waiting for pipeline result...",
+  refresh: "Refresh",
+  refreshing: "Loading...",
+  enterFullscreen: "Fullscreen",
+  exitFullscreen: "Collapse",
+  build: "Build",
+}
+
+export interface RefreshParams {
+  keys?: Record<string, unknown>
+  steps?: PipelineStepRef[]
+  layout?: LayoutConfig
+  title?: string
+}
+
+export interface ViewData {
+  _refreshParams?: RefreshParams
+  title?: string
+  context: {
+    keys: Record<string, unknown>
+    stepIds: string[]
+    stepData: Record<
+      string,
+      { data: unknown; keys: Record<string, unknown>; _app: string; _dataType: string }
+    >
+    errors: { stepId: string; reason: string }[]
+  }
+  layout?: LayoutConfig
+  /**
+   * Whether the server's in-iframe builder platform is usable (set by
+   * `render-view` from `createFrameworkApp`'s `app.builder`). The shell gates
+   * its Build affordance on this so the edit button never appears against a
+   * server whose `get-builder-catalogue` tool isn't registered.
+   */
+  builderAvailable?: boolean
+}
+
+/**
+ * A renderable view payload: the envelope `render-view`/`show_*` tools emit
+ * as `structuredContent`. Module-level so it is referentially stable as the
+ * recovery hook's `isValid` dependency.
+ */
+export function isCompleteViewData(value: unknown): value is ViewData {
+  const v = value as ViewData | null | undefined
+  return Boolean(v?.context && v?.layout)
+}
+
+// -------------------------------------------------------------------------- //
+// Toolbar
+// -------------------------------------------------------------------------- //
+
+export interface ViewToolbarProps {
+  /** The toolbar hides entirely while build mode owns the surface. */
+  hidden: boolean
+  viewData: ViewData
+  builderAvailable: boolean
+  isFullscreen: boolean
+  isRefreshing: boolean
+  labels: Required<McpAppViewLabels>
+  onRefresh: () => Promise<void>
+  onEnterBuildMode: () => void
+  onToggleFullscreen: () => Promise<void>
+}
+
+export function ViewToolbar({
+  hidden,
+  viewData,
+  builderAvailable,
+  isFullscreen,
+  isRefreshing,
+  labels,
+  onRefresh,
+  onEnterBuildMode,
+  onToggleFullscreen,
+}: ViewToolbarProps) {
+  if (hidden) return null
+  return (
+    <div className="mb-4 flex items-center justify-between">
+      {viewData.title && <h2 className="text-xl font-bold">{viewData.title}</h2>}
+      <div className="ml-auto flex items-center gap-2">
+        {viewData._refreshParams && viewData.layout && (
+          <button
+            onClick={() => {
+              void onRefresh()
+            }}
+            disabled={isRefreshing}
+            className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors disabled:opacity-50"
+          >
+            <RefreshCw
+              aria-hidden="true"
+              className={`h-4 w-4 ${isRefreshing ? "animate-spin" : ""}`}
+            />
+            {isRefreshing ? labels.refreshing : labels.refresh}
+          </button>
+        )}
+        {builderAvailable && viewData._refreshParams && (
+          <button
+            onClick={onEnterBuildMode}
+            className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
+          >
+            <Pencil className="h-4 w-4" />
+            {labels.build}
+          </button>
+        )}
+        <button
+          onClick={() => {
+            void onToggleFullscreen()
+          }}
+          className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
+        >
+          {isFullscreen ? (
+            <Minimize2 aria-hidden="true" className="h-4 w-4" />
+          ) : (
+            <Maximize2 aria-hidden="true" className="h-4 w-4" />
+          )}
+          {isFullscreen ? labels.exitFullscreen : labels.enterFullscreen}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+// -------------------------------------------------------------------------- //
+// Pipeline error list
+// -------------------------------------------------------------------------- //
+
+export function StepErrors({
+  hidden,
+  errors,
+}: {
+  /** Build mode surfaces its own diagnostics; the shell list hides. */
+  hidden: boolean
+  errors: ViewData["context"]["errors"]
+}) {
+  if (hidden || errors.length === 0) return null
+  return (
+    <div className="mb-4 flex flex-col gap-2">
+      {errors.map((err) => (
+        <div key={err.stepId} className="bg-destructive/10 text-destructive rounded-lg p-3 text-sm">
+          <strong>{err.stepId}:</strong> {err.reason}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// -------------------------------------------------------------------------- //
+// Body: LayoutBuilder in build mode, WidgetRenderer otherwise
+// -------------------------------------------------------------------------- //
+
+export interface ViewBodyProps {
+  buildMode: boolean
+  viewData: ViewData
+  widgets: Record<string, WidgetComponent>
+  callTool: (name: string, args: object) => Promise<unknown>
+  onExit: LayoutBuilderProps["onExit"]
+}
+
+export function ViewBody({ buildMode, viewData, widgets, callTool, onExit }: ViewBodyProps) {
+  if (buildMode) {
+    return (
+      <LayoutBuilder
+        initialLayout={viewData.layout}
+        title={viewData.title}
+        initialKeys={viewData._refreshParams?.keys}
+        initialSteps={viewData._refreshParams?.steps}
+        widgets={widgets}
+        callTool={callTool}
+        onExit={onExit}
+      />
+    )
+  }
+  if (!viewData.layout) return null
+  return (
+    <WidgetRenderer
+      layout={viewData.layout}
+      keys={viewData.context.keys}
+      stepData={viewData.context.stepData}
+      errors={viewData.context.errors}
+      widgets={widgets}
+    />
+  )
+}

package/src/app/mcp-app-view.tsx

@@ -1,71 +1,23 @@
 import { useState, useCallback } from "react"
 import { useDisplayMode, useHostContext, useToolContext } from "mcp-use/react"
-import { Maximize2, Minimize2, Pencil, RefreshCw } from "lucide-react"
 import type { LayoutConfig, PipelineStepRef } from "@miragon/mcp-toolkit-core"
 import { Skeleton } from "../primitives/skeleton.js"
 import { AppQueryProvider, queryClient } from "../providers/query-provider.js"
 import { useToolResultRecovery } from "../hooks/use-tool-result-recovery.js"
 import { parseToolResult } from "../lib/parse-tool-result.js"
 import { useHostBridge } from "./host-bridge.js"
-import { LayoutBuilder } from "./layout-builder.js"
-import { WidgetRenderer, type WidgetComponent } from "./widget-renderer.js"
+import {
+  DEFAULT_LABELS,
+  isCompleteViewData,
+  StepErrors,
+  ViewBody,
+  ViewToolbar,
+  type McpAppViewLabels,
+  type ViewData,
+} from "./mcp-app-view-chrome.js"
+import type { WidgetComponent } from "./widget-renderer.js"
 
-export interface McpAppViewLabels {
-  loading?: string
-  refresh?: string
-  refreshing?: string
-  enterFullscreen?: string
-  exitFullscreen?: string
-  build?: string
-}
-
-const DEFAULT_LABELS: Required<McpAppViewLabels> = {
-  loading: "Waiting for pipeline result...",
-  refresh: "Refresh",
-  refreshing: "Loading...",
-  enterFullscreen: "Fullscreen",
-  exitFullscreen: "Collapse",
-  build: "Build",
-}
-
-interface RefreshParams {
-  keys?: Record<string, unknown>
-  steps?: PipelineStepRef[]
-  layout?: LayoutConfig
-  title?: string
-}
-
-interface ViewData {
-  _refreshParams?: RefreshParams
-  title?: string
-  context: {
-    keys: Record<string, unknown>
-    stepIds: string[]
-    stepData: Record<
-      string,
-      { data: unknown; keys: Record<string, unknown>; _app: string; _dataType: string }
-    >
-    errors: { stepId: string; reason: string }[]
-  }
-  layout?: LayoutConfig
-  /**
-   * Whether the server's in-iframe builder platform is usable (set by
-   * `render-view` from `createFrameworkApp`'s `app.builder`). The shell gates
-   * its Build affordance on this so the edit button never appears against a
-   * server whose `get-builder-catalogue` tool isn't registered.
-   */
-  builderAvailable?: boolean
-}
-
-/**
- * A renderable view payload: the envelope `render-view`/`show_*` tools emit
- * as `structuredContent`. Module-level so it is referentially stable as the
- * recovery hook's `isValid` dependency.
- */
-function isCompleteViewData(value: unknown): value is ViewData {
-  const v = value as ViewData | null | undefined
-  return Boolean(v?.context && v?.layout)
-}
+export type { McpAppViewLabels } from "./mcp-app-view-chrome.js"
 
 export interface McpAppViewProps {
   /**
@@ -264,7 +216,7 @@ export function McpAppView({
     )
   }
 
-  const showHeader = !buildMode
+  const isFullscreen = displayMode === "fullscreen"
 
   // Follow the server's own signal by default: render-view reports
   // `builderAvailable` (derived from `app.builder`), so the Build button only
@@ -281,95 +233,35 @@ export function McpAppView({
         // `bootstrapView`'s auto-resize, so we let content dictate height and
         // avoid setting overflowY (which would clip our own content inside a
         // host that's already auto-sized to us).
-        ...(displayMode === "fullscreen"
-          ? { minHeight: "100vh", overflowY: "auto" as const }
-          : null),
+        ...(isFullscreen ? { minHeight: "100vh", overflowY: "auto" as const } : null),
         paddingTop: safeArea.top,
         paddingRight: safeArea.right,
         paddingBottom: safeArea.bottom,
         paddingLeft: safeArea.left,
       }}
     >
-      {showHeader && (
-        <div className="mb-4 flex items-center justify-between">
-          {viewData.title && <h2 className="text-xl font-bold">{viewData.title}</h2>}
-          <div className="ml-auto flex items-center gap-2">
-            {viewData._refreshParams && viewData.layout && (
-              <button
-                onClick={() => {
-                  void refreshView()
-                }}
-                disabled={isRefreshing}
-                className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors disabled:opacity-50"
-              >
-                <RefreshCw
-                  aria-hidden="true"
-                  className={`h-4 w-4 ${isRefreshing ? "animate-spin" : ""}`}
-                />
-                {isRefreshing ? effectiveLabels.refreshing : effectiveLabels.refresh}
-              </button>
-            )}
-            {builderAvailable && viewData._refreshParams && (
-              <button
-                onClick={() => setBuildMode(true)}
-                className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
-              >
-                <Pencil className="h-4 w-4" />
-                {effectiveLabels.build}
-              </button>
-            )}
-            <button
-              onClick={() => {
-                void toggleFullscreen()
-              }}
-              className="hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm font-medium transition-colors"
-            >
-              {displayMode === "fullscreen" ? (
-                <Minimize2 aria-hidden="true" className="h-4 w-4" />
-              ) : (
-                <Maximize2 aria-hidden="true" className="h-4 w-4" />
-              )}
-              {displayMode === "fullscreen"
-                ? effectiveLabels.exitFullscreen
-                : effectiveLabels.enterFullscreen}
-            </button>
-          </div>
-        </div>
-      )}
+      <ViewToolbar
+        hidden={buildMode}
+        viewData={viewData}
+        builderAvailable={builderAvailable}
+        isFullscreen={isFullscreen}
+        isRefreshing={isRefreshing}
+        labels={effectiveLabels}
+        onRefresh={refreshView}
+        onEnterBuildMode={() => setBuildMode(true)}
+        onToggleFullscreen={toggleFullscreen}
+      />
 
-      {!buildMode && viewData.context.errors.length > 0 && (
-        <div className="mb-4 flex flex-col gap-2">
-          {viewData.context.errors.map((err) => (
-            <div
-              key={err.stepId}
-              className="bg-destructive/10 text-destructive rounded-lg p-3 text-sm"
-            >
-              <strong>{err.stepId}:</strong> {err.reason}
-            </div>
-          ))}
-        </div>
-      )}
+      <StepErrors hidden={buildMode} errors={viewData.context.errors} />
 
       <AppQueryProvider callTool={callToolFn}>
-        {buildMode ? (
-          <LayoutBuilder
-            initialLayout={viewData.layout}
-            title={viewData.title}
-            initialKeys={viewData._refreshParams?.keys}
-            initialSteps={viewData._refreshParams?.steps}
-            widgets={widgets}
-            callTool={callToolFn}
-            onExit={exitBuildMode}
-          />
-        ) : viewData.layout ? (
-          <WidgetRenderer
-            layout={viewData.layout}
-            keys={viewData.context.keys}
-            stepData={viewData.context.stepData}
-            errors={viewData.context.errors}
-            widgets={widgets}
-          />
-        ) : null}
+        <ViewBody
+          buildMode={buildMode}
+          viewData={viewData}
+          widgets={widgets}
+          callTool={callToolFn}
+          onExit={exitBuildMode}
+        />
       </AppQueryProvider>
     </main>
   )

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import { parseToolResult } from "./parse-tool-result.js"
+
+// Deterministic PRNG: a property failure in CI must replay identically on the
+// next run, never appear as a fresh random draw (FITNESS.md phase 5c).
+fc.configureGlobal({ seed: 42, numRuns: 100 })
+
+// CallToolResult-ish shapes: structuredContent × content arrays whose first
+// text block is valid JSON about half the time and arbitrary text otherwise.
+const textArb = fc.oneof(
+  fc.string(),
+  fc.jsonValue().map((value) => JSON.stringify(value)),
+)
+const contentArb = fc.oneof(
+  fc.constant([]),
+  fc.array(fc.record({ type: fc.constant("text"), text: textArb }, { requiredKeys: ["type"] }), {
+    maxLength: 2,
+  }),
+)
+const resultArb = fc.record(
+  {
+    isError: fc.constant(false),
+    structuredContent: fc.oneof(fc.constant(null), fc.jsonValue()),
+    content: contentArb,
+  },
+  { requiredKeys: [] },
+)
+
+describe("parseToolResult (property)", () => {
+  // Bug class guarded: this is the single decode seam every widget, query hook
+  // and the app shell funnel through — a malformed host response crashing here
+  // would take down the whole widget render path instead of one data read.
+  it("never throws on arbitrary junk without a truthy isError", () => {
+    const junkArb = fc
+      .anything()
+      .filter((junk) => !(typeof junk === "object" && junk !== null && "isError" in junk))
+    fc.assert(
+      fc.property(junkArb, (junk) => {
+        expect(() => parseToolResult(junk)).not.toThrow()
+      }),
+    )
+  })
+
+  // Bug class guarded: the structured-first precedence IS the 0.4 contract —
+  // a tool emitting both a text summary and structuredContent must decode to
+  // the data payload, never regress to the summary string; and every result
+  // must land on a documented outcome (structured, JSON text, verbatim text,
+  // raw result), never on undefined.
+  it("yields exactly the documented outcome, structured content first", () => {
+    fc.assert(
+      fc.property(resultArb, (result) => {
+        const out: unknown = parseToolResult(result)
+        const text = Array.isArray(result.content) ? result.content[0]?.text : undefined
+        if (result.structuredContent != null) {
+          expect(out).toBe(result.structuredContent)
+        } else if (text !== undefined) {
+          let decoded: unknown = text
+          try {
+            decoded = JSON.parse(text)
+          } catch {
+            // Non-JSON text is returned verbatim — that IS the documented outcome.
+          }
+          expect(out).toEqual(decoded)
+        } else {
+          expect(out).toBe(result)
+        }
+      }),
+    )
+  })
+
+  // Bug class guarded: error results must surface as thrown Errors carrying
+  // the first text block, so TanStack Query error states (and try/catch in
+  // widgets) show the server's message instead of silently rendering junk.
+  it("throws the first text block for every isError result", () => {
+    fc.assert(
+      fc.property(resultArb, fc.string(), (result, message) => {
+        const errorResult = { ...result, isError: true, content: [{ type: "text", text: message }] }
+        let thrown: unknown
+        try {
+          parseToolResult(errorResult)
+        } catch (err) {
+          thrown = err
+        }
+        expect(thrown).toBeInstanceOf(Error)
+        expect((thrown as Error).message).toBe(message)
+      }),
+    )
+  })
+})