@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/app/builder/labels.ts

@@ -4,130 +4,24 @@
  * 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.
+ * which would create an import cycle. React-free and `mcp-use`-free. The
+ * strings themselves live in the toolkit catalog (`locale/messages-*.ts`).
  */
 
-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
-}
+import { TOOLKIT_MESSAGES, type BuilderMessages } from "../../locale/toolkit-messages.js"
 
-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.",
-}
+/**
+ * Override strings for every user-facing caption in the builder. Each field
+ * defaults to the active locale's toolkit catalog (`useToolkitMessages().builder`).
+ */
+export type LayoutBuilderLabels = Partial<BuilderMessages>
+
+/**
+ * English builder strings.
+ * @deprecated Read the active locale's strings with `useToolkitMessages().builder`
+ * (or `TOOLKIT_MESSAGES.en.builder`); this alias stays for existing imports.
+ */
+export const DEFAULT_LABELS: Required<LayoutBuilderLabels> = TOOLKIT_MESSAGES.en.builder
 
 /**
  * MIME type used to carry a widget id across the palette → canvas drag.

package/src/app/builder/reveal.ts

@@ -0,0 +1,10 @@
+/**
+ * Secondary builder controls (row, tab and cell actions) stay quiet until the
+ * pointer is over their group or focus is anywhere inside it, and are always
+ * visible where nothing can hover (touch screens). Spread it on the controls'
+ * container inside an element with `group`; a control that is never revealed
+ * by hover alone is a CI §12 rule ("alles per Tastatur bedienbar"), guarded by
+ * `builder-ux.test.tsx`.
+ */
+export const REVEAL_ON_INTENT =
+  "opacity-0 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100"

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

@@ -1,4 +1,5 @@
 import { CircleDot, Loader2 } from "lucide-react"
+import { TONE_DOT, TONE_TEXT } from "../../lib/tone-utils.js"
 import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js"
 
 /**
@@ -22,15 +23,18 @@ export function StatusChip({
   }
   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" />
+      <span className={`inline-flex items-center gap-1.5 ${TONE_TEXT.warning}`}>
+        <span
+          aria-hidden="true"
+          className={`size-1.5 animate-pulse rounded-full ${TONE_DOT.warning}`}
+        />
         {L.statusPending}
       </span>
     )
   }
   return (
-    <span className="text-primary inline-flex items-center gap-1.5">
-      <Loader2 className="size-3 animate-spin" />
+    <span className={`inline-flex items-center gap-1.5 ${TONE_TEXT.info}`}>
+      <Loader2 aria-hidden="true" className="size-3 animate-spin" />
       {L.statusRefreshing}
     </span>
   )

package/src/app/builder/use-builder-catalogue.ts

@@ -1,6 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 import type {
   AvailableStep,
+  CatalogueApp,
+  DisplayText,
   KeyCatalogEntry,
   PipelineContext,
   PipelineStepRef,
@@ -22,6 +24,17 @@ import type { RefreshStatus } from "./labels.js"
 
 const EMPTY_CONTEXT: PipelineContext = { steps: {}, keys: {}, errors: [] }
 
+/** What the builder reads from a `get-builder-catalogue` response (every field optional). */
+interface CatalogueSnapshot {
+  reachableWidgets?: ReachableWidget[]
+  unreachableWidgets?: UnreachableWidget[]
+  availableSteps?: AvailableStep[]
+  keyCatalog?: KeyCatalogEntry[]
+  validationIssues?: string[]
+  context?: WireContext
+  apps?: CatalogueApp[]
+}
+
 /**
  * Owns the builder's live catalogue: the snapshots fetched from the app-only
  * `get-builder-catalogue` tool (the LLM never sees this data), the refresh
@@ -49,6 +62,9 @@ export function useBuilderCatalogue({
   const [liveCatalog, setLiveCatalog] = useState<KeyCatalogEntry[]>([])
   const [liveSteps, setLiveSteps] = useState<AvailableStep[]>([])
   const [liveContext, setLiveContext] = useState<PipelineContext>(EMPTY_CONTEXT)
+  // The titled apps (the palette's group headings); the catalogue leaves the
+  // field out when no app has a title.
+  const [liveApps, setLiveApps] = useState<CatalogueApp[]>([])
   // Pipeline validation issues from the catalogue (Finding [10]/[6]). The
   // catalogue is fail-soft, but `render-view` is fail-hard, so we surface
   // these so the user sees — before committing — that the pipeline as
@@ -61,6 +77,26 @@ export function useBuilderCatalogue({
   // instead of only `console.warn`-ing, so the user knows the palette/context
   // may be stale. Cleared on the next successful refresh.
   const [refreshError, setRefreshError] = useState<string | null>(null)
+  // The first fetch has settled (answer or failure). Until then the palette
+  // shows a loading state, not "no elements" (CI §9: a skeleton while loading).
+  const [loaded, setLoaded] = useState(false)
+
+  // Takes over what one catalogue response carries; a field it lacks keeps
+  // the last snapshot.
+  const applySnapshot = useCallback((sc: CatalogueSnapshot | null) => {
+    if (sc?.reachableWidgets) setLiveReachable(sc.reachableWidgets)
+    if (sc?.unreachableWidgets) setLiveUnreachable(sc.unreachableWidgets)
+    if (sc?.availableSteps) setLiveSteps(sc.availableSteps)
+    if (sc?.keyCatalog) setLiveCatalog(sc.keyCatalog)
+    if (sc?.context) setLiveContext(toPipelineContext(sc.context))
+    // Absent `apps` means no app has a title (not "unchanged").
+    if (sc) setLiveApps(sc.apps ?? [])
+    // Pipeline issues are fail-soft in the catalogue but fail-hard in
+    // render-view; surface them so the user sees the render path wouldn't
+    // run as configured (Finding [10]/[6]). Coerce undefined → [] so a
+    // fixed pipeline clears a previously-shown warning.
+    setValidationIssues(sc?.validationIssues ?? [])
+  }, [])
 
   const refreshBuilder = useCallback(async () => {
     setStatus("refreshing")
@@ -69,24 +105,7 @@ export function useBuilderCatalogue({
         keys: entriesToKeys(keyEntries),
         steps: stepEntries.filter((s) => s.step.trim().length > 0),
       })
-      const sc = parseToolResult<{
-        reachableWidgets?: ReachableWidget[]
-        unreachableWidgets?: UnreachableWidget[]
-        availableSteps?: AvailableStep[]
-        keyCatalog?: KeyCatalogEntry[]
-        validationIssues?: string[]
-        context?: WireContext
-      } | null>(result)
-      if (sc?.reachableWidgets) setLiveReachable(sc.reachableWidgets)
-      if (sc?.unreachableWidgets) setLiveUnreachable(sc.unreachableWidgets)
-      if (sc?.availableSteps) setLiveSteps(sc.availableSteps)
-      if (sc?.keyCatalog) setLiveCatalog(sc.keyCatalog)
-      if (sc?.context) setLiveContext(toPipelineContext(sc.context))
-      // Pipeline issues are fail-soft in the catalogue but fail-hard in
-      // render-view; surface them so the user sees the render path wouldn't
-      // run as configured (Finding [10]/[6]). Coerce undefined → [] so a
-      // fixed pipeline clears a previously-shown warning.
-      setValidationIssues(sc?.validationIssues ?? [])
+      applySnapshot(parseToolResult<CatalogueSnapshot | null>(result))
       // A successful fetch clears any stale failure banner.
       setRefreshError(null)
     } catch (err) {
@@ -104,13 +123,19 @@ export function useBuilderCatalogue({
       setRefreshError(reason)
     } finally {
       setStatus("idle")
+      setLoaded(true)
     }
-  }, [catalogueToolName, callTool, keyEntries, stepEntries])
+  }, [applySnapshot, catalogueToolName, callTool, keyEntries, stepEntries])
 
   const refreshRef = useRef(refreshBuilder)
   useEffect(() => {
     refreshRef.current = refreshBuilder
   }, [refreshBuilder])
+  // Retry of the catalogue error state: fetch again right away, with the
+  // current keys and steps.
+  const retryCatalogue = useCallback(() => {
+    void refreshRef.current()
+  }, [])
   const isFirstRun = useRef(true)
   useEffect(() => {
     if (isFirstRun.current) {
@@ -149,6 +174,20 @@ export function useBuilderCatalogue({
     return map
   }, [liveReachable, liveUnreachable])
 
+  // Display text (title, summary, their keys) per widget id, from both lists:
+  // a canvas cell or the props sheet may name a widget the current keys do
+  // not reach.
+  const displayByWidgetId = useMemo(() => {
+    const map = new Map<string, DisplayText>()
+    for (const w of [...liveUnreachable, ...liveReachable]) map.set(w.id, w)
+    return map
+  }, [liveReachable, liveUnreachable])
+
+  const appDisplayByName = useMemo(
+    () => new Map<string, DisplayText>(liveApps.map((app) => [app.name, app])),
+    [liveApps],
+  )
+
   const paletteByApp = useMemo(() => {
     const groups = new Map<string, ReachableWidget[]>()
     for (const w of liveReachable) {
@@ -177,9 +216,13 @@ export function useBuilderCatalogue({
     liveContext,
     validationIssues,
     status,
+    loaded,
     refreshError,
+    retryCatalogue,
     widgetById,
     propsSchemaByWidgetId,
+    displayByWidgetId,
+    appDisplayByName,
     paletteByApp,
     liveKeyCount,
     stepsByApp,

package/src/app/builder/use-builder-session.ts

@@ -0,0 +1,68 @@
+import { useCallback, useState } from "react"
+import {
+  draftStatus,
+  viewAfterAdvancedToggle,
+  type BuilderView,
+  type DraftStatus,
+} from "./builder-model.js"
+
+// -------------------------------------------------------------------------- //
+// Builder session state that is not the draft itself
+// -------------------------------------------------------------------------- //
+
+/**
+ * Which builder view is shown and whether advanced mode is on. The data
+ * sources (keys, steps, context ids) and the catalogue are technical, so they
+ * live behind "Advanced"; switching it off leaves a now hidden view for the
+ * layout.
+ */
+export function useBuilderMode() {
+  const [advanced, setAdvanced] = useState(false)
+  const [view, setView] = useState<BuilderView>("layout")
+  const toggleAdvanced = useCallback(() => {
+    const next = !advanced
+    setAdvanced(next)
+    setView(viewAfterAdvancedToggle(view, next))
+  }, [advanced, view])
+  /** The empty layout's one next step: show the data sources. */
+  const openDataSources = useCallback(() => {
+    setAdvanced(true)
+    setView("pipeline")
+  }, [])
+  return { advanced, view, setView, toggleAdvanced, openDataSources }
+}
+
+/**
+ * Inline rename feedback. The reducer rejects duplicate tab labels and bumps
+ * `renameRejectedAt`; each bump shows "name already exists" until the inline
+ * editor closes (render-phase setState, the house pattern for derived state).
+ */
+export function useRenameFeedback(renameRejectedAt: number, editingTabIdx: number | null): boolean {
+  const [renameRejected, setRenameRejected] = useState(false)
+  const [prevRenameRejectedAt, setPrevRenameRejectedAt] = useState(renameRejectedAt)
+  if (renameRejectedAt !== prevRenameRejectedAt) {
+    setPrevRenameRejectedAt(renameRejectedAt)
+    setRenameRejected(true)
+  }
+  const [prevEditingTabIdx, setPrevEditingTabIdx] = useState(editingTabIdx)
+  if (editingTabIdx !== prevEditingTabIdx) {
+    setPrevEditingTabIdx(editingTabIdx)
+    if (editingTabIdx === null) setRenameRejected(false)
+  }
+  return renameRejected
+}
+
+/**
+ * Tracks the draft against the view before editing and the last saved
+ * dashboard (see `draftStatus`). `snapshot` is the current `builderSnapshot`;
+ * the first one is the pre-edit baseline.
+ */
+export function useDraftStatus(snapshot: string): DraftStatus & {
+  /** Records `saved` (the snapshot that went into a saved dashboard). */
+  markSaved: (saved: string) => void
+} {
+  const [baseline] = useState(snapshot)
+  const [saved, setSaved] = useState<string | null>(null)
+  const markSaved = useCallback((value: string) => setSaved(value), [])
+  return { ...draftStatus(snapshot, baseline, saved), markSaved }
+}

package/src/app/builder/use-display-resolver.ts

@@ -0,0 +1,24 @@
+import { useMemo } from "react"
+import { useToolkitLocale, useTranslate } from "../../locale/locale-provider.js"
+import { keyResolverFrom, type DisplayKeyResolver } from "./builder-model.js"
+
+/** What the builder needs to turn a definition's display text into words. */
+export interface DisplayResolver {
+  /** The locale the builder's own text is in (a `LocaleProvider`'s, else the host's). */
+  locale: string
+  /** Resolves a `titleKey`/`summaryKey` through the `LocaleProvider`'s translator. */
+  resolveKey: DisplayKeyResolver
+}
+
+/**
+ * Binds `displayLabel` / `propFieldText` to the builder's locale: inline
+ * per-locale titles follow the same language as the builder chrome around
+ * them, and i18n keys resolve through the nearest `LocaleProvider`'s
+ * translator (outside one, keys stay unknown and the inline text or the id
+ * shows instead).
+ */
+export function useDisplayResolver(): DisplayResolver {
+  const locale = useToolkitLocale()
+  const translate = useTranslate()
+  return useMemo(() => ({ locale, resolveKey: keyResolverFrom(translate) }), [locale, translate])
+}

package/src/app/builder/use-save-dashboard.ts

@@ -22,6 +22,7 @@ export function useSaveDashboard({
   stepEntries,
   draft,
   onSaved,
+  onSuccess,
 }: {
   callTool: (name: string, args: object) => Promise<unknown>
   saveToolName: string
@@ -31,6 +32,8 @@ export function useSaveDashboard({
   stepEntries: PipelineStepRef[]
   draft: DraftLayout
   onSaved?: (result: { id: string; name: string }) => void
+  /** Confirms every successful save (the builder raises a toast), with the saved name. */
+  onSuccess?: (name: string) => void
 }) {
   const [isBusy, setBusy] = useState(false)
   const [saveOpen, setSaveOpen] = useState(false)
@@ -56,6 +59,7 @@ export function useSaveDashboard({
       })
       const saved = parseToolResult<{ id?: string; name?: string } | null>(result)
       setSaveOpen(false)
+      onSuccess?.(saved?.name ?? saveName.trim())
       if (saved?.id && onSaved) {
         onSaved({
           id: saved.id,
@@ -75,6 +79,7 @@ export function useSaveDashboard({
     draft,
     keyEntries,
     onSaved,
+    onSuccess,
     saveDescription,
     saveName,
     saveToolName,

package/src/app/index.ts

@@ -1,6 +1,20 @@
 export { McpAppView } from "./mcp-app-view.js"
-export type { McpAppViewProps, McpAppViewLabels } from "./mcp-app-view.js"
+export type {
+  McpAppViewProps,
+  McpAppViewLabels,
+  DescribeStep,
+  DescribeViewError,
+  ViewErrorKind,
+  RecoveryPolicy,
+  ViewTitleLevel,
+  ViewTitleMode,
+} from "./mcp-app-view.js"
 export { McpToolkitApp, mountMcpToolkitApp } from "./mcp-toolkit-app.js"
+// The passive host-lifecycle observer behind the stripped-result recovery
+// (toolkit#176): installed as the bundle evaluates; a custom shell may call it
+// explicitly before its own `bootstrapView`.
+export { installToolResultObserver } from "../lib/tool-result-observer.js"
+export type { ToolObservation, ToolResultObserver } from "../lib/tool-result-observer.js"
 export {
   WidgetRenderer,
   WidgetErrorBoundary,
@@ -10,10 +24,12 @@ export {
 export type { WidgetRendererProps, WidgetComponent } from "./widget-renderer.js"
 export { LayoutBuilder } from "./layout-builder.js"
 export type { LayoutBuilderProps, LayoutBuilderLabels } from "./layout-builder.js"
+export type { BuilderExitCommit } from "./builder/builder-model.js"
 
 // App-level value modules that import `mcp-use/react` (ModelContext, the 2.x
 // view hooks) — exported from this subpath only, never the root barrel.
-export { adaptDataWidget, HostModelContext } from "./adapt-data-widget.js"
+export { adaptDataWidget } from "./adapt-data-widget.js"
+export { HostModelContext, useHostModelContext } from "./model-context.js"
 export type { DescribeForModel } from "./adapt-data-widget.js"
 export { useHostActions, buildShowWidgetIntent } from "./use-host-actions.js"
 export type { HostActions } from "./use-host-actions.js"
@@ -36,7 +52,8 @@ export type {
   OpenAiAppsSdk,
   StandaloneHostBridgeOptions,
 } from "./host-bridge.js"
-export { McpUseHostBridgeProvider, useIsInsideMcpUseView } from "./mcp-use-host-bridge.js"
+export { McpUseHostBridgeProvider } from "./mcp-use-host-bridge.js"
+export { useIsInsideMcpUseView } from "./model-context.js"
 
 // Storybook-style harness for developing widgets in isolation with fixture
 // data and a simulated HostBridge. Lives under ./app to keep every host-facing