@miragon/mcp-toolkit-ui 1.0.1 → 1.2.0

package/dist/render-cases.js

@@ -0,0 +1,140 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Button, CountPill, DrillButton, FilterBar, GridItem, GridLayout, GroupCard, KpiGrid, ListFooter, LivePill, LocaleProvider, SectionHeading, ThemeProvider, themePresets, useLocale, WidgetHeader, } from "./index.js";
+import { createStandaloneHostBridge, HostBridgeProvider, useHostBridge } from "./app/host-bridge.js";
+import { HostModelContext } from "./app/adapt-data-widget.js";
+import { WidgetFixtureHost } from "./app/widget-fixture.js";
+import { PRIMITIVE_RENDER_CASES } from "./render-cases-primitives.js";
+/**
+ * SSR render cases for every catalogued component/composite (FITNESS.md phase
+ * 5c). DATA module, not a test: `render-smoke.test.tsx` renders each case via
+ * `react-dom/server`'s `renderToStaticMarkup` (jsdom is deliberately renounced
+ * — SSR is the house render path) and enforces completeness against
+ * `ui-catalog.json` ∪ `ratchets/render-allowlist.json` (shrink-only).
+ *
+ * Each case mounts the component with minimal realistic props and, where the
+ * markup can carry one, a distinctive `marker` string the test asserts on.
+ * The primitive cases live in `render-cases-primitives.tsx` (file-length
+ * budget); this module aggregates them with the composed/host cases.
+ */
+const noop = () => { };
+/** Static bridge for the host-bridge cases — theme "dark" is the probed marker. */
+const probeBridge = createStandaloneHostBridge({
+    callTool: () => Promise.resolve({}),
+    theme: "dark",
+});
+/** Proves HostBridgeProvider actually provides: reads the bridge from context. */
+function BridgeThemeProbe() {
+    const bridge = useHostBridge();
+    return _jsxs("span", { children: ["RC:HostBridgeProvider ", bridge.theme ?? "unset"] });
+}
+/** Proves LocaleProvider actually provides: reads the locale from context. */
+function LocaleProbe() {
+    const locale = useLocale();
+    return _jsxs("span", { children: ["RC:LocaleProvider ", locale] });
+}
+/** Minimal raw `({ data })` widget for the WidgetFixtureHost case. */
+function FixtureProbeWidget({ data }) {
+    return _jsxs("div", { children: ["RC:WidgetFixtureHost ", data?.label ?? "no fixture"] });
+}
+export const RENDER_CASES = [
+    ...PRIMITIVE_RENDER_CASES,
+    // ── Composed components ──
+    {
+        name: "GridLayout",
+        marker: "RC:GridLayout",
+        render: () => (_jsxs(GridLayout, { children: [_jsx(GridItem, { span: 8, children: _jsx("div", { children: "RC:GridLayout" }) }), _jsx(GridItem, { span: 4, children: _jsx("div", { children: "side tile" }) })] })),
+    },
+    {
+        name: "GridItem",
+        marker: "RC:GridItem",
+        render: () => (_jsx(GridLayout, { children: _jsx(GridItem, { span: 6, children: _jsx("div", { children: "RC:GridItem" }) }) })),
+    },
+    {
+        name: "KpiGrid",
+        marker: "RC:KpiGrid",
+        render: () => (_jsx(KpiGrid, { boxed: true, header: { label: "RC:KpiGrid", badge: "live" }, cells: [
+                {
+                    label: "Open",
+                    value: 7,
+                    tone: "danger",
+                    trend: "+2 vs yesterday",
+                    trendDirection: "up",
+                },
+                { label: "Done", value: 12, fraction: "/19", tone: "success" },
+                { label: "Total", value: 19, onClick: noop, ariaLabel: "Show all" },
+            ] })),
+    },
+    {
+        name: "LivePill",
+        marker: "RC:LivePill",
+        render: () => _jsx(LivePill, { tone: "success", children: "RC:LivePill" }),
+    },
+    {
+        name: "CountPill",
+        marker: "RC:CountPill",
+        render: () => _jsx(CountPill, { tone: "warning", children: "RC:CountPill" }),
+    },
+    {
+        name: "SectionHeading",
+        marker: "RC:SectionHeading",
+        render: () => _jsx(SectionHeading, { title: "RC:SectionHeading", hint: "3 shown" }),
+    },
+    {
+        name: "WidgetHeader",
+        marker: "RC:WidgetHeader",
+        render: () => (_jsx(WidgetHeader, { icon: "\u2713", iconTone: "info", title: "RC:WidgetHeader", sub: _jsx(LivePill, { children: "Live" }), actions: _jsx(Button, { size: "sm", variant: "ghost", onClick: noop, children: "Refresh" }) })),
+    },
+    {
+        name: "GroupCard",
+        marker: "RC:GroupCard",
+        render: () => (_jsx(GroupCard, { expanded: true, onToggle: noop, summary: _jsx("div", { children: "RC:GroupCard" }), children: _jsx("div", { children: "Expanded body row" }) })),
+    },
+    {
+        // The search marker lands in the input's value attribute.
+        name: "FilterBar",
+        marker: "RC:FilterBar",
+        render: () => (_jsx(FilterBar, { search: "RC:FilterBar", searchPlaceholder: "Filter tasks\u2026", onSearchChange: noop, chips: [
+                { id: "high", label: "high", count: 2, active: true },
+                { id: "low", label: "low" },
+            ], onChipToggle: noop })),
+    },
+    {
+        name: "DrillButton",
+        marker: "RC:DrillButton",
+        render: () => (_jsx(DrillButton, { onDrill: noop, icon: "\u2197", size: "sm", ariaLabel: "Open order o-1001", children: "RC:DrillButton" })),
+    },
+    {
+        name: "ListFooter",
+        marker: "of 42 tasks",
+        render: () => _jsx(ListFooter, { shown: 8, total: 42, hasMore: true, onLoadMore: noop, noun: "tasks" }),
+    },
+    // ── Host seam / providers ──
+    {
+        name: "HostBridgeProvider",
+        marker: "RC:HostBridgeProvider dark",
+        render: () => (_jsx(HostBridgeProvider, { bridge: probeBridge, children: _jsx(BridgeThemeProbe, {}) })),
+    },
+    {
+        // Outside an mcp-use view HostModelContext reports through the bridge in
+        // an effect (a no-op in SSR) and must still render its children.
+        name: "HostModelContext",
+        marker: "RC:HostModelContext",
+        render: () => (_jsx(HostBridgeProvider, { bridge: probeBridge, children: _jsx(HostModelContext, { content: "Viewing 3 open incidents", children: _jsx("div", { children: "RC:HostModelContext" }) }) })),
+    },
+    {
+        name: "ThemeProvider",
+        marker: "RC:ThemeProvider",
+        render: () => (_jsx(ThemeProvider, { theme: themePresets.miragon, mode: "dark", children: _jsx("div", { children: "RC:ThemeProvider" }) })),
+    },
+    {
+        name: "LocaleProvider",
+        marker: "RC:LocaleProvider de",
+        render: () => (_jsx(LocaleProvider, { locale: "de", children: _jsx(LocaleProbe, {}) })),
+    },
+    {
+        name: "WidgetFixtureHost",
+        marker: "RC:WidgetFixtureHost fixture-data",
+        render: () => (_jsx(WidgetFixtureHost, { widget: FixtureProbeWidget, data: { label: "fixture-data" } })),
+    },
+];
+//# sourceMappingURL=render-cases.js.map

package/dist/render-cases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-cases.js","sourceRoot":"","sources":["../src/render-cases.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miragon/mcp-toolkit-ui",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "React UI for MCP servers: shadcn primitives, composite components, TanStack Query hooks, and the MCP App shell (McpAppView + WidgetRenderer).",
   "repository": {
     "type": "git",
@@ -38,33 +38,37 @@
     "access": "public"
   },
   "peerDependencies": {
-    "mcp-use": "2.0.4",
+    "mcp-use": "2.1.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "tailwindcss": "4.3.3",
-    "@miragon/mcp-toolkit-core": "1.0.1"
+    "@miragon/mcp-toolkit-core": "1.2.0"
   },
   "dependencies": {
-    "@base-ui/react": "1.6.0",
+    "@base-ui/react": "1.7.0",
     "@fontsource-variable/geist": "5.3.0",
     "@tanstack/react-query": "5.101.4",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
-    "lucide-react": "0.562.0",
+    "lucide-react": "1.27.0",
     "radix-ui": "1.6.7",
     "tailwind-merge": "3.6.0",
     "tw-animate-css": "1.4.0"
   },
   "devDependencies": {
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
-    "mcp-use": "2.0.4",
+    "@vitest/coverage-v8": "4.1.10",
+    "fast-check": "4.9.0",
+    "mcp-use": "2.1.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "tailwindcss": "4.3.3",
     "typescript": "6.0.3",
     "vitest": "4.1.10",
-    "@miragon/mcp-toolkit-core": "1.0.1"
+    "@miragon/mcp-toolkit-core": "1.2.0"
   },
   "engines": {
     "node": ">=22.22.2"
@@ -73,6 +77,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint src --max-warnings 0",
     "lint:fix": "eslint src --fix"
   }

package/src/app/builder/BuilderBanners.tsx

@@ -0,0 +1,61 @@
+import { AlertTriangle } from "lucide-react"
+import type { LayoutBuilderLabels } from "./labels.js"
+
+// -------------------------------------------------------------------------- //
+// Builder banners — catalogue-fetch failure + pipeline validation warning
+// -------------------------------------------------------------------------- //
+
+/**
+ * Inline feedback strip under the toolbar. Surfaces two things the builder
+ * previously swallowed:
+ *   - a `get-builder-catalogue` fetch failure (Finding [3]) — only console-
+ *     logged before, so the user couldn't tell the palette was stale, and
+ *   - pipeline validation issues (Finding [10]/[6]) the catalogue reports
+ *     fail-soft but `render-view` would reject fail-hard.
+ *
+ * Renders nothing when there's no error and no issues, so the happy path is
+ * visually unchanged.
+ */
+export function BuilderBanners({
+  L,
+  catalogueToolName,
+  refreshError,
+  validationIssues,
+}: {
+  L: Required<LayoutBuilderLabels>
+  catalogueToolName: string
+  refreshError: string | null
+  validationIssues: string[]
+}) {
+  if (!refreshError && validationIssues.length === 0) return null
+  return (
+    <div className="flex flex-col gap-2" role="status" aria-live="polite">
+      {refreshError && (
+        <div className="border-destructive/30 bg-destructive/10 text-destructive flex items-start gap-2 rounded-md border px-3 py-2 text-xs">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" aria-hidden="true" />
+          <div className="min-w-0">
+            <p className="font-medium">{L.catalogueError}</p>
+            <p className="text-destructive/80 mt-0.5 break-words">
+              <span className="font-mono">{catalogueToolName}</span>: {refreshError}
+            </p>
+          </div>
+        </div>
+      )}
+      {validationIssues.length > 0 && (
+        <div className="flex items-start gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-xs text-amber-700 dark:text-amber-400">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" aria-hidden="true" />
+          <div className="min-w-0">
+            <p className="font-medium">{L.validationWarning}</p>
+            <ul className="mt-0.5 list-inside list-disc space-y-0.5">
+              {validationIssues.map((issue, idx) => (
+                <li key={idx} className="break-words">
+                  {issue}
+                </li>
+              ))}
+            </ul>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/app/builder/CanvasRow.tsx

@@ -0,0 +1,316 @@
+import { memo, useCallback, useRef } from "react"
+import { ChevronDown, ChevronUp, SlidersHorizontal, Trash2, X } from "lucide-react"
+import type { RowDef, WidgetProps } from "@miragon/mcp-toolkit-core"
+import { GridItem, GridLayout } from "../../components/GridLayout.js"
+import { Button } from "../../primitives/button.js"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../../primitives/select.js"
+import { cn } from "../../lib/utils.js"
+import { RenderedWidget, type WidgetComponent } from "../widget-renderer.js"
+import type { LayoutBuilderLabels } from "./labels.js"
+import { WIDGET_DRAG_MIME } from "./labels.js"
+
+// -------------------------------------------------------------------------- //
+// Canvas row — drop target + per-cell controls + resize handle
+// -------------------------------------------------------------------------- //
+
+function CanvasRowImpl({
+  L,
+  row,
+  rowIdx,
+  focused,
+  isFirst,
+  isLast,
+  dragOver,
+  setDragOverRow,
+  setFocusedRowIndex,
+  onRemoveRow,
+  onMoveRow,
+  onSetCellSpan,
+  onRemoveCell,
+  onAddWidget,
+  onConfigureCell,
+  propsSchemaByWidgetId,
+  widgets,
+  widgetProps,
+}: {
+  L: Required<LayoutBuilderLabels>
+  row: RowDef
+  rowIdx: number
+  focused: boolean
+  isFirst: boolean
+  isLast: boolean
+  dragOver: boolean
+  setDragOverRow: (idx: number | null) => void
+  setFocusedRowIndex: (idx: number) => void
+  onRemoveRow: (rowIdx: number) => void
+  onMoveRow: (rowIdx: number, direction: -1 | 1) => void
+  onSetCellSpan: (rowIdx: number, cellIdx: number, span: number) => void
+  onRemoveCell: (rowIdx: number, cellIdx: number) => void
+  onAddWidget: (widgetId: string, targetRowIdx?: number) => void
+  onConfigureCell: (rowIdx: number, cellIdx: number) => void
+  propsSchemaByWidgetId: Map<string, Record<string, unknown>>
+  widgets: Record<string, WidgetComponent>
+  widgetProps: WidgetProps
+}) {
+  const gridRef = useRef<HTMLDivElement | null>(null)
+
+  return (
+    <div
+      onClick={() => setFocusedRowIndex(rowIdx)}
+      onDragOver={(e) => {
+        if (!e.dataTransfer.types.includes(WIDGET_DRAG_MIME)) return
+        e.preventDefault()
+        e.dataTransfer.dropEffect = "copy"
+        setDragOverRow(rowIdx)
+      }}
+      onDragLeave={(e) => {
+        if (e.currentTarget.contains(e.relatedTarget as Node)) return
+        setDragOverRow(null)
+      }}
+      onDrop={(e) => {
+        const id = e.dataTransfer.getData(WIDGET_DRAG_MIME)
+        setDragOverRow(null)
+        if (id) {
+          e.preventDefault()
+          onAddWidget(id, rowIdx)
+        }
+      }}
+      className={cn(
+        "group relative rounded-lg border-l-2 px-3 py-2 transition-colors",
+        focused
+          ? "border-l-primary bg-card"
+          : "bg-background hover:bg-card/60 border-l-transparent",
+        dragOver && "bg-primary/5 border-l-primary",
+      )}
+    >
+      <div className="mb-2 flex items-center justify-between">
+        <div className="text-muted-foreground flex items-center gap-2 text-[11px]">
+          <span className="font-mono">row {rowIdx + 1}</span>
+          <span className="bg-muted/60 rounded px-1 py-0.5 text-[10px]">
+            {row.row.length} {row.row.length === 1 ? "widget" : "widgets"}
+          </span>
+        </div>
+        <div className="opacity-0 transition-opacity group-hover:opacity-100">
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            onClick={(e) => {
+              e.stopPropagation()
+              onMoveRow(rowIdx, -1)
+            }}
+            disabled={isFirst}
+            aria-label="Move row up"
+          >
+            <ChevronUp />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            onClick={(e) => {
+              e.stopPropagation()
+              onMoveRow(rowIdx, 1)
+            }}
+            disabled={isLast}
+            aria-label="Move row down"
+          >
+            <ChevronDown />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            onClick={(e) => {
+              e.stopPropagation()
+              onRemoveRow(rowIdx)
+            }}
+            aria-label={L.removeRow}
+          >
+            <Trash2 />
+          </Button>
+        </div>
+      </div>
+      {row.row.length === 0 ? (
+        <div
+          className={cn(
+            "rounded-md border border-dashed py-6 text-center text-[11px] transition-colors",
+            dragOver
+              ? "border-primary bg-primary/5 text-primary"
+              : "border-muted-foreground/30 text-muted-foreground",
+          )}
+        >
+          {dragOver ? L.canvasDropHint : L.canvasEmpty}
+        </div>
+      ) : (
+        <div ref={gridRef} data-row-grid>
+          <GridLayout>
+            {row.row.map((cell, cellIdx) => {
+              const span = cell.span ?? 12
+              const Widget = widgets[cell.widget]
+              const hasPropsSchema = propsSchemaByWidgetId.has(cell.widget)
+              const propCount = cell.props ? Object.keys(cell.props).length : 0
+              return (
+                <GridItem key={`${cell.widget}-${cellIdx}`} span={span}>
+                  <div className="border-border bg-card relative overflow-hidden rounded-md border shadow-sm">
+                    <div className="text-muted-foreground bg-muted/30 flex items-center justify-between gap-2 border-b px-2 py-1 text-[10px]">
+                      <span className="truncate font-mono">{cell.widget}</span>
+                      <div className="flex shrink-0 items-center gap-2">
+                        <label className="text-muted-foreground/80 inline-flex items-center gap-0.5 font-mono">
+                          <span className="sr-only">Column span</span>
+                          <Select
+                            value={String(span)}
+                            onValueChange={(v) => onSetCellSpan(rowIdx, cellIdx, Number(v))}
+                          >
+                            <SelectTrigger
+                              size="sm"
+                              className="h-5 gap-0.5 border-none bg-transparent px-1 py-0 font-mono text-[10px] shadow-none focus:ring-0"
+                              aria-label="Column span"
+                              onClick={(e) => e.stopPropagation()}
+                            >
+                              <SelectValue />
+                            </SelectTrigger>
+                            <SelectContent>
+                              {Array.from({ length: 12 }, (_, i) => i + 1).map((n) => (
+                                <SelectItem key={n} value={String(n)} className="font-mono text-xs">
+                                  {n}
+                                </SelectItem>
+                              ))}
+                            </SelectContent>
+                          </Select>
+                          <span aria-hidden="true">/12</span>
+                        </label>
+                        {hasPropsSchema && (
+                          <Button
+                            variant="ghost"
+                            size="icon-xs"
+                            onClick={(e) => {
+                              e.stopPropagation()
+                              onConfigureCell(rowIdx, cellIdx)
+                            }}
+                            aria-label="Configure widget props"
+                            title={
+                              propCount > 0
+                                ? `Configure widget props (${propCount} set)`
+                                : "Configure widget props"
+                            }
+                            className={cn(propCount > 0 && "text-primary")}
+                          >
+                            <SlidersHorizontal />
+                          </Button>
+                        )}
+                        <Button
+                          variant="ghost"
+                          size="icon-xs"
+                          onClick={(e) => {
+                            e.stopPropagation()
+                            onRemoveCell(rowIdx, cellIdx)
+                          }}
+                          aria-label="Remove widget"
+                        >
+                          <X />
+                        </Button>
+                      </div>
+                    </div>
+                    <div className="p-2">
+                      <RenderedWidget
+                        widget={Widget}
+                        widgetId={cell.widget}
+                        props={widgetProps}
+                        cellProps={cell.props}
+                        showEmptyHint
+                        notBundledClassName="text-muted-foreground rounded border border-dashed p-3 text-center text-[11px]"
+                      />
+                    </div>
+                    <ResizeHandle
+                      rowIdx={rowIdx}
+                      cellIdx={cellIdx}
+                      span={span}
+                      getGridEl={() => gridRef.current}
+                      onSetCellSpan={onSetCellSpan}
+                    />
+                  </div>
+                </GridItem>
+              )
+            })}
+          </GridLayout>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export const CanvasRow = memo(CanvasRowImpl)
+
+// -------------------------------------------------------------------------- //
+// Resize handle
+// -------------------------------------------------------------------------- //
+
+function ResizeHandle({
+  rowIdx,
+  cellIdx,
+  span,
+  getGridEl,
+  onSetCellSpan,
+}: {
+  rowIdx: number
+  cellIdx: number
+  span: number
+  getGridEl: () => HTMLElement | null
+  onSetCellSpan: (rowIdx: number, cellIdx: number, span: number) => void
+}) {
+  const onPointerDown = useCallback(
+    (e: React.PointerEvent<HTMLDivElement>) => {
+      e.preventDefault()
+      e.stopPropagation()
+      const grid = getGridEl()
+      if (!grid) return
+      const rect = grid.getBoundingClientRect()
+      const colWidth = rect.width / 12
+      const startX = e.clientX
+      const startSpan = span
+      const onMove = (ev: PointerEvent) => {
+        const delta = ev.clientX - startX
+        const next = Math.round(startSpan + delta / colWidth)
+        onSetCellSpan(rowIdx, cellIdx, Math.max(1, Math.min(12, next)))
+      }
+      const onUp = () => {
+        window.removeEventListener("pointermove", onMove)
+        window.removeEventListener("pointerup", onUp)
+      }
+      window.addEventListener("pointermove", onMove)
+      window.addEventListener("pointerup", onUp)
+    },
+    [cellIdx, getGridEl, onSetCellSpan, rowIdx, span],
+  )
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      const dir = e.key === "ArrowLeft" ? -1 : e.key === "ArrowRight" ? 1 : 0
+      if (dir === 0) return
+      e.preventDefault()
+      e.stopPropagation()
+      onSetCellSpan(rowIdx, cellIdx, Math.max(1, Math.min(12, span + dir)))
+    },
+    [cellIdx, onSetCellSpan, rowIdx, span],
+  )
+
+  return (
+    <div
+      onPointerDown={onPointerDown}
+      onClick={(e) => e.stopPropagation()}
+      onKeyDown={onKeyDown}
+      tabIndex={0}
+      className="hover:bg-primary/40 focus-visible:bg-primary/40 focus-visible:ring-primary/60 absolute top-0 right-0 h-full w-1.5 cursor-col-resize touch-none select-none focus-visible:ring-1 focus-visible:outline-none"
+      aria-label="Resize widget"
+      role="separator"
+      aria-orientation="vertical"
+      aria-valuenow={span}
+      aria-valuemin={1}
+      aria-valuemax={12}
+    />
+  )
+}

package/src/app/builder/CellPropsSheet.tsx

@@ -0,0 +1,47 @@
+import type { RowDef } from "@miragon/mcp-toolkit-core"
+import { WidgetPropsSheet } from "../widget-props-sheet.js"
+
+// -------------------------------------------------------------------------- //
+// Cell props sheet — mounts the WidgetPropsSheet for the configured cell
+// -------------------------------------------------------------------------- //
+
+/**
+ * Mounted once at the LayoutBuilder root so that exactly one props editor
+ * can be open at a time across the entire workspace — including across
+ * tabs. `configuringCell` addresses `{ rowIdx, cellIdx }` on the currently
+ * active draft surface (rows or active tab's rows); renders nothing when no
+ * cell is being configured or the address no longer resolves.
+ */
+export function CellPropsSheet({
+  configuringCell,
+  activeRows,
+  propsSchemaByWidgetId,
+  onApply,
+  onClose,
+}: {
+  configuringCell: { rowIdx: number; cellIdx: number } | null
+  activeRows: RowDef[]
+  propsSchemaByWidgetId: Map<string, Record<string, unknown>>
+  onApply: (rowIdx: number, cellIdx: number, next: Record<string, unknown> | undefined) => void
+  onClose: () => void
+}) {
+  if (!configuringCell) return null
+  const cell = activeRows[configuringCell.rowIdx]?.row[configuringCell.cellIdx]
+  if (!cell) return null
+  const schema = propsSchemaByWidgetId.get(cell.widget)
+  return (
+    <WidgetPropsSheet
+      open
+      onOpenChange={(open) => {
+        if (!open) onClose()
+      }}
+      widgetId={cell.widget}
+      schema={schema}
+      value={cell.props}
+      onApply={(next) => {
+        onApply(configuringCell.rowIdx, configuringCell.cellIdx, next)
+        onClose()
+      }}
+    />
+  )
+}

package/src/app/builder/EmptyHint.tsx

@@ -0,0 +1,29 @@
+import { Layers, SlidersHorizontal } from "lucide-react"
+import { Button } from "../../primitives/button.js"
+import type { LayoutBuilderLabels } from "./labels.js"
+
+// -------------------------------------------------------------------------- //
+// Empty hint — shown on the Layout view before any widget is reachable
+// -------------------------------------------------------------------------- //
+
+export function EmptyHint({
+  L,
+  onGotoPipeline,
+}: {
+  L: Required<LayoutBuilderLabels>
+  onGotoPipeline: () => void
+}) {
+  return (
+    <div className="border-muted-foreground/30 text-muted-foreground flex flex-col items-center gap-2 rounded-md border border-dashed p-10 text-sm">
+      <Layers className="size-5" />
+      <p>No widgets reachable yet.</p>
+      <p className="text-xs">
+        Open the <span className="font-medium">{L.viewPipelineTab}</span> tab to seed keys or add a
+        pipeline step — the palette unlocks as soon as a widget's contract is satisfied.
+      </p>
+      <Button variant="outline" size="sm" onClick={onGotoPipeline} className="mt-1">
+        <SlidersHorizontal /> Open {L.viewPipelineTab}
+      </Button>
+    </div>
+  )
+}