@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

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/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,8 +123,9 @@ export function useBuilderCatalogue({
       setRefreshError(reason)
     } finally {
       setStatus("idle")
+      setLoaded(true)
     }
-  }, [catalogueToolName, callTool, keyEntries, stepEntries])
+  }, [applySnapshot, catalogueToolName, callTool, keyEntries, stepEntries])
 
   const refreshRef = useRef(refreshBuilder)
   useEffect(() => {
@@ -154,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) {
@@ -182,10 +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/index.ts

@@ -4,10 +4,17 @@ export type {
   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,
@@ -17,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"
@@ -43,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