@miragon/mcp-toolkit-ui 0.10.1

package/dist/theme/presets.js

@@ -0,0 +1,68 @@
+import { createTheme } from "./create-theme.js";
+/**
+ * Ready-made white-label themes — a demonstration of {@link createTheme} and a
+ * starting point a client can fork. Each preset sets a distinct brand `primary`,
+ * a matching `ring`/`accent`, and a `radius`, plus a `dark` override that
+ * brightens the brand colour for legibility on dark surfaces (mirroring how
+ * `globals.css` brightens tokens under `.dark`).
+ *
+ * Colours are authored in `oklch` to stay consistent with the toolkit's token
+ * palette in `globals.css`. Apply one with `<ThemeProvider theme={themePresets.violet}>`.
+ */
+export const themePresets = {
+    /**
+     * The toolkit's own brand: a confident indigo-blue with a slightly tighter
+     * radius. A sensible default when a client has no brand of their own yet.
+     */
+    miragon: createTheme({
+        primary: "oklch(0.52 0.21 264)",
+        primaryForeground: "oklch(0.985 0 0)",
+        accent: "oklch(0.95 0.03 264)",
+        accentForeground: "oklch(0.32 0.12 264)",
+        ring: "oklch(0.52 0.21 264)",
+        radius: "0.5rem",
+    }, {
+        dark: {
+            primary: "oklch(0.7 0.16 264)",
+            primaryForeground: "oklch(0.18 0.02 264)",
+            accent: "oklch(0.32 0.06 264)",
+            accentForeground: "oklch(0.97 0 0)",
+            ring: "oklch(0.7 0.16 264)",
+        },
+    }),
+    /** A vivid violet brand with rounder corners — playful, consumer-facing. */
+    violet: createTheme({
+        primary: "oklch(0.55 0.24 295)",
+        primaryForeground: "oklch(0.985 0 0)",
+        accent: "oklch(0.95 0.04 295)",
+        accentForeground: "oklch(0.34 0.14 295)",
+        ring: "oklch(0.55 0.24 295)",
+        radius: "0.875rem",
+    }, {
+        dark: {
+            primary: "oklch(0.72 0.18 295)",
+            primaryForeground: "oklch(0.18 0.03 295)",
+            accent: "oklch(0.33 0.08 295)",
+            accentForeground: "oklch(0.97 0 0)",
+            ring: "oklch(0.72 0.18 295)",
+        },
+    }),
+    /** A grounded emerald brand with a crisp, near-square radius — enterprise. */
+    emerald: createTheme({
+        primary: "oklch(0.58 0.15 162)",
+        primaryForeground: "oklch(0.985 0 0)",
+        accent: "oklch(0.95 0.04 162)",
+        accentForeground: "oklch(0.34 0.1 162)",
+        ring: "oklch(0.58 0.15 162)",
+        radius: "0.375rem",
+    }, {
+        dark: {
+            primary: "oklch(0.72 0.15 162)",
+            primaryForeground: "oklch(0.17 0.03 162)",
+            accent: "oklch(0.32 0.07 162)",
+            accentForeground: "oklch(0.97 0 0)",
+            ring: "oklch(0.72 0.15 162)",
+        },
+    }),
+};
+//# sourceMappingURL=presets.js.map

package/dist/theme/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/theme/presets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAwB,MAAM,mBAAmB,CAAA;AAErE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;;OAGG;IACH,OAAO,EAAE,WAAW,CAClB;QACE,OAAO,EAAE,sBAAsB;QAC/B,iBAAiB,EAAE,kBAAkB;QACrC,MAAM,EAAE,sBAAsB;QAC9B,gBAAgB,EAAE,sBAAsB;QACxC,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,QAAQ;KACjB,EACD;QACE,IAAI,EAAE;YACJ,OAAO,EAAE,qBAAqB;YAC9B,iBAAiB,EAAE,sBAAsB;YACzC,MAAM,EAAE,sBAAsB;YAC9B,gBAAgB,EAAE,iBAAiB;YACnC,IAAI,EAAE,qBAAqB;SAC5B;KACF,CACF;IAED,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CACjB;QACE,OAAO,EAAE,sBAAsB;QAC/B,iBAAiB,EAAE,kBAAkB;QACrC,MAAM,EAAE,sBAAsB;QAC9B,gBAAgB,EAAE,sBAAsB;QACxC,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,UAAU;KACnB,EACD;QACE,IAAI,EAAE;YACJ,OAAO,EAAE,sBAAsB;YAC/B,iBAAiB,EAAE,sBAAsB;YACzC,MAAM,EAAE,sBAAsB;YAC9B,gBAAgB,EAAE,iBAAiB;YACnC,IAAI,EAAE,sBAAsB;SAC7B;KACF,CACF;IAED,8EAA8E;IAC9E,OAAO,EAAE,WAAW,CAClB;QACE,OAAO,EAAE,sBAAsB;QAC/B,iBAAiB,EAAE,kBAAkB;QACrC,MAAM,EAAE,sBAAsB;QAC9B,gBAAgB,EAAE,qBAAqB;QACvC,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,UAAU;KACnB,EACD;QACE,IAAI,EAAE;YACJ,OAAO,EAAE,sBAAsB;YAC/B,iBAAiB,EAAE,sBAAsB;YACzC,MAAM,EAAE,sBAAsB;YAC9B,gBAAgB,EAAE,iBAAiB;YACnC,IAAI,EAAE,sBAAsB;SAC7B;KACF,CACF;CACwC,CAAA"}

package/dist/theme/theme-provider.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+import type { ThemeDefinition } from "./create-theme.js";
+/**
+ * How the `.dark` class is resolved on the theme scope:
+ * - `"light"` / `"dark"` — forced, ignores the OS preference.
+ * - `"system"` — follows `prefers-color-scheme` via `matchMedia`, updating live.
+ *
+ * A host that already knows the colour scheme (e.g. `HostBridge.theme`) can pass
+ * its value straight through as `mode` so the white-label theme tracks the host.
+ */
+export type ThemeMode = "light" | "dark" | "system";
+/** The value exposed by {@link useTheme}. */
+export interface ThemeContextValue {
+    /** The active theme definition, or `null` when only a mode is being managed. */
+    theme: ThemeDefinition | null;
+    /** The mode as requested on the provider (may be `"system"`). */
+    mode: ThemeMode;
+    /** The mode actually applied right now (`"system"` resolved to light/dark). */
+    resolvedMode: "light" | "dark";
+}
+/**
+ * Read the active theme/mode from the nearest {@link ThemeProvider}. Throws when
+ * called outside a provider so a missing wrapper fails loudly rather than
+ * silently rendering the default theme.
+ */
+export declare function useTheme(): ThemeContextValue;
+/** Props for {@link ThemeProvider}. */
+export interface ThemeProviderProps {
+    /**
+     * The white-label theme to apply (from {@link createTheme} or `themePresets`).
+     * Omit to manage only the light/dark `mode` against the toolkit defaults.
+     */
+    theme?: ThemeDefinition;
+    /**
+     * Colour-scheme mode. Defaults to `"light"`. Pass `HostBridge.theme` through
+     * here to follow the host, or `"system"` to track the OS preference.
+     */
+    mode?: ThemeMode;
+    /**
+     * The HTML element to render as the scope wrapper. Defaults to `"div"`. Use
+     * `"span"` for inline contexts; any intrinsic element with a `style`/className
+     * works.
+     */
+    as?: "div" | "span" | "section" | "main";
+    /** Extra classes merged onto the scope wrapper. */
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Apply a white-label {@link ThemeDefinition} to a subtree. Renders a wrapper
+ * element carrying the theme's CSS variables as inline `style`, so they override
+ * the `:root` defaults for every descendant — `Card`, `Button`, `bg-card`,
+ * `text-primary`, and `rounded-lg` all re-skin without touching the widgets.
+ *
+ * Dark mode is handled at the scope: the `.dark` class is toggled on the wrapper
+ * (not `<html>`) per the resolved {@link ThemeMode}, and the theme's `darkVars`
+ * are layered on under it. This keeps theming local — two differently themed
+ * subtrees (e.g. a brand preview gallery) coexist on one page.
+ *
+ * Uses only React + the DOM (no `mcp-use/react`), so it ships from the root
+ * barrel and works in a host-free standalone app, a host, or SSR alike.
+ *
+ * @example
+ * <ThemeProvider theme={themePresets.violet} mode={host.theme ?? "system"}>
+ *   <YourWidget />
+ * </ThemeProvider>
+ */
+export declare function ThemeProvider({ theme, mode, as: As, className, children, }: ThemeProviderProps): ReactNode;
+//# sourceMappingURL=theme-provider.d.ts.map

package/dist/theme/theme-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-provider.d.ts","sourceRoot":"","sources":["../../src/theme/theme-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEnD,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IAC7B,iEAAiE;IACjE,IAAI,EAAE,SAAS,CAAA;IACf,+EAA+E;IAC/E,YAAY,EAAE,OAAO,GAAG,MAAM,CAAA;CAC/B;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,iBAAiB,CAM5C;AA6BD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;IACxC,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,IAAc,EACd,EAAE,EAAE,EAAU,EACd,SAAS,EACT,QAAQ,GACT,EAAE,kBAAkB,GAAG,SAAS,CA8BhC"}

package/dist/theme/theme-provider.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState, } from "react";
+const ThemeContext = createContext(null);
+/**
+ * Read the active theme/mode from the nearest {@link ThemeProvider}. Throws when
+ * called outside a provider so a missing wrapper fails loudly rather than
+ * silently rendering the default theme.
+ */
+export function useTheme() {
+    const value = useContext(ThemeContext);
+    if (!value) {
+        throw new Error("useTheme() must be used within a <ThemeProvider>.");
+    }
+    return value;
+}
+/**
+ * Resolve `"system"` to a concrete `"light"` | `"dark"` and keep it in sync with
+ * the OS preference. SSR-safe: returns `"light"` until mounted (no `window`),
+ * then subscribes to `matchMedia` on the client. Forced modes short-circuit the
+ * media query entirely.
+ */
+function useResolvedMode(mode) {
+    const [systemMode, setSystemMode] = useState("light");
+    useEffect(() => {
+        if (mode !== "system")
+            return;
+        if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+            return;
+        const query = window.matchMedia("(prefers-color-scheme: dark)");
+        const sync = () => {
+            setSystemMode(query.matches ? "dark" : "light");
+        };
+        sync();
+        query.addEventListener("change", sync);
+        return () => {
+            query.removeEventListener("change", sync);
+        };
+    }, [mode]);
+    return mode === "system" ? systemMode : mode;
+}
+/**
+ * Apply a white-label {@link ThemeDefinition} to a subtree. Renders a wrapper
+ * element carrying the theme's CSS variables as inline `style`, so they override
+ * the `:root` defaults for every descendant — `Card`, `Button`, `bg-card`,
+ * `text-primary`, and `rounded-lg` all re-skin without touching the widgets.
+ *
+ * Dark mode is handled at the scope: the `.dark` class is toggled on the wrapper
+ * (not `<html>`) per the resolved {@link ThemeMode}, and the theme's `darkVars`
+ * are layered on under it. This keeps theming local — two differently themed
+ * subtrees (e.g. a brand preview gallery) coexist on one page.
+ *
+ * Uses only React + the DOM (no `mcp-use/react`), so it ships from the root
+ * barrel and works in a host-free standalone app, a host, or SSR alike.
+ *
+ * @example
+ * <ThemeProvider theme={themePresets.violet} mode={host.theme ?? "system"}>
+ *   <YourWidget />
+ * </ThemeProvider>
+ */
+export function ThemeProvider({ theme, mode = "light", as: As = "div", className, children, }) {
+    const resolvedMode = useResolvedMode(mode);
+    const isDark = resolvedMode === "dark";
+    // Merge the light vars with the dark overrides only when dark is active, so a
+    // dark scope gets the brand's dark palette on top of `.dark`'s defaults.
+    const style = useMemo(() => {
+        if (!theme)
+            return {};
+        if (isDark && theme.darkVars) {
+            return { ...theme.vars, ...theme.darkVars };
+        }
+        return theme.vars;
+    }, [theme, isDark]);
+    const value = useMemo(() => ({ theme: theme ?? null, mode, resolvedMode }), [theme, mode, resolvedMode]);
+    const classes = [isDark ? "dark" : undefined, "bg-background text-foreground", className]
+        .filter(Boolean)
+        .join(" ");
+    return (_jsx(ThemeContext.Provider, { value: value, children: _jsx(As, { className: classes, style: style, "data-theme-mode": resolvedMode, children: children }) }));
+}
+//# sourceMappingURL=theme-provider.js.map

package/dist/theme/theme-provider.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@miragon/mcp-toolkit-ui",
+  "version": "0.10.1",
+  "description": "React UI for MCP servers: shadcn primitives, composite components, TanStack Query hooks, and the MCP App shell (McpAppView + WidgetRenderer).",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./app": {
+      "types": "./dist/app/index.d.ts",
+      "import": "./dist/app/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js"
+    },
+    "./globals.css": "./src/globals.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "ui-catalog.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "mcp-use": "1.34.5",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tailwindcss": "4.3.3",
+    "@miragon/mcp-toolkit-core": "0.10.1"
+  },
+  "dependencies": {
+    "@base-ui/react": "1.6.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": "1.25.0",
+    "radix-ui": "1.6.7",
+    "tailwind-merge": "3.6.0",
+    "tw-animate-css": "1.4.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "mcp-use": "1.34.5",
+    "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": "0.10.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --max-warnings 0",
+    "lint:fix": "eslint src --fix"
+  }
+}

package/src/app/adapt-data-widget.tsx

@@ -0,0 +1,51 @@
+import type { ComponentType } from "react"
+import { ModelContext } from "mcp-use/react"
+import type { WidgetProps } from "@miragon/mcp-toolkit-core"
+import type { WidgetComponent } from "./widget-renderer.js"
+
+/**
+ * Builds the model-context line for an adapted widget. Receives the resolved
+ * step data (never null — the adapter skips the description while loading) plus
+ * the per-cell layout props so scope filters that only travel as props (e.g.
+ * `period` / `engine` on dashboard widgets) can be reported too.
+ */
+export type DescribeForModel<T> = (
+  data: NonNullable<T>,
+  props: Readonly<Record<string, unknown>>,
+) => string
+
+/**
+ * Wraps a "single-data" widget component (signature `({ data }: { data: T | null })`)
+ * so it can be registered as a framework {@link WidgetComponent} (which receives
+ * `WidgetProps = { keys, context, widgetProps? }`). The adapter looks up the
+ * matching step result in `context.steps` by its `_dataType` and forwards
+ * `result.data` to the wrapped widget. Lets `render-view` and `*_show_*` tools
+ * (via `buildSingleWidgetView`) share the same widget components without
+ * changing their props.
+ *
+ * Per-cell `props` from the layout (`row[].props`) are spread onto the
+ * wrapped widget as named props. This lets the same widget appear multiple
+ * times in one view with different scoping (e.g. one tab per process key).
+ *
+ * When `describeForModel` is provided the adapter wraps the widget in a
+ * `ModelContext` so the model knows what the user is looking at (view identity,
+ * active filters, headline numbers) without per-widget boilerplate. The
+ * description is only rendered once the step data is present; widgets that
+ * self-fetch when the adapter has no data (cockpit views) must render their own
+ * `<ModelContext>` instead.
+ */
+export function adaptDataWidget<T>(
+  Widget: ComponentType<{ data: T | null } & Record<string, unknown>>,
+  dataType: string,
+  describeForModel?: DescribeForModel<T>,
+): WidgetComponent {
+  function AdaptedWidget({ context, widgetProps }: WidgetProps) {
+    const stepResult = Object.values(context.steps).find((s) => s._dataType === dataType)
+    const data = (stepResult?.data ?? null) as T | null
+    const widget = <Widget {...(widgetProps ?? {})} data={data} />
+    if (data == null || !describeForModel) return widget
+    return <ModelContext content={describeForModel(data, widgetProps ?? {})}>{widget}</ModelContext>
+  }
+  AdaptedWidget.displayName = `Adapted(${Widget.displayName ?? Widget.name ?? "Widget"})`
+  return AdaptedWidget
+}

package/src/app/builder/CatalogueSheet.tsx

@@ -0,0 +1,230 @@
+import { useMemo } from "react"
+import { ArrowDownToLine, Library, Plus } from "lucide-react"
+import type { AvailableStep, KeyCatalogEntry, UnreachableWidget } from "@miragon/mcp-toolkit-core"
+import { Badge } from "../../primitives/badge.js"
+import { Button } from "../../primitives/button.js"
+import { ScrollArea } from "../../primitives/scroll-area.js"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "../../primitives/sheet.js"
+import { cn } from "../../lib/utils.js"
+import type { LayoutBuilderLabels } from "./labels.js"
+
+// -------------------------------------------------------------------------- //
+// Catalogue Sheet — slides in from the right
+// -------------------------------------------------------------------------- //
+
+export function CatalogueSheet({
+  L,
+  open,
+  onOpenChange,
+  keyCatalog,
+  availableSteps,
+  unreachableWidgets,
+  onSeedKey,
+  onAddProducingStep,
+}: {
+  L: Required<LayoutBuilderLabels>
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  keyCatalog: KeyCatalogEntry[]
+  availableSteps: AvailableStep[]
+  unreachableWidgets: UnreachableWidget[]
+  onSeedKey: (name: string) => void
+  onAddProducingStep: (key: string) => void
+}) {
+  const producerOf = useMemo(() => {
+    const map = new Map<string, string | undefined>()
+    for (const e of keyCatalog) map.set(e.key, e.producedBySteps[0])
+    return map
+  }, [keyCatalog])
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent className="w-full sm:max-w-md md:max-w-lg">
+        <SheetHeader>
+          <SheetTitle className="flex items-center gap-2 text-base">
+            <Library className="size-4" />
+            {L.catalogue}
+          </SheetTitle>
+          <SheetDescription>{L.catalogueDescription}</SheetDescription>
+        </SheetHeader>
+
+        <ScrollArea className="flex-1 px-4 pb-4">
+          <div className="flex flex-col gap-6">
+            <section className="flex flex-col gap-2">
+              <CatalogueSectionHeader title={L.catalogueKeys} count={keyCatalog.length} />
+              {keyCatalog.length === 0 ? (
+                <p className="text-muted-foreground text-xs italic">No keys registered.</p>
+              ) : (
+                <ul className="flex flex-col gap-1">
+                  {keyCatalog.map((entry) => (
+                    <li
+                      key={entry.key}
+                      className="hover:bg-accent/40 flex flex-col gap-1 rounded-md border px-2 py-1.5 text-xs"
+                    >
+                      <div className="flex items-start justify-between gap-2">
+                        <span className="truncate font-mono">{entry.key}</span>
+                        <span
+                          className={cn(
+                            "inline-flex shrink-0 items-center gap-1 text-[10px]",
+                            entry.inContext
+                              ? "text-emerald-600 dark:text-emerald-400"
+                              : "text-muted-foreground",
+                          )}
+                        >
+                          <span
+                            className={cn(
+                              "size-1.5 rounded-full",
+                              entry.inContext ? "bg-emerald-500" : "bg-muted-foreground/40",
+                            )}
+                          />
+                          {entry.inContext ? L.catalogueLive : L.catalogueMissing}
+                        </span>
+                      </div>
+                      {(entry.producedBySteps.length > 0 ||
+                        entry.consumedBySteps.length > 0 ||
+                        entry.consumedByWidgets.length > 0) && (
+                        <div className="text-muted-foreground/80 flex flex-col gap-0.5 text-[10px]">
+                          {entry.producedBySteps.length > 0 && (
+                            <span>
+                              {L.catalogueProducedBy}{" "}
+                              <span className="font-mono">{entry.producedBySteps.join(", ")}</span>
+                            </span>
+                          )}
+                          {entry.consumedBySteps.length > 0 && (
+                            <span>
+                              step {L.catalogueConsumedBy}{" "}
+                              <span className="font-mono">{entry.consumedBySteps.join(", ")}</span>
+                            </span>
+                          )}
+                          {entry.consumedByWidgets.length > 0 && (
+                            <span>
+                              widget {L.catalogueConsumedBy}{" "}
+                              <span className="font-mono">
+                                {entry.consumedByWidgets.join(", ")}
+                              </span>
+                            </span>
+                          )}
+                        </div>
+                      )}
+                      {!entry.inContext && (
+                        <div className="mt-0.5 flex items-center gap-1">
+                          <Button variant="ghost" size="xs" onClick={() => onSeedKey(entry.key)}>
+                            <Plus /> {L.cataloguePickKey}
+                          </Button>
+                          {producerOf.get(entry.key) && (
+                            <Button
+                              variant="ghost"
+                              size="xs"
+                              onClick={() => onAddProducingStep(entry.key)}
+                            >
+                              <ArrowDownToLine /> {L.catalogueAddProducingStep}
+                            </Button>
+                          )}
+                        </div>
+                      )}
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </section>
+
+            <section className="flex flex-col gap-2">
+              <CatalogueSectionHeader title={L.catalogueSteps} count={availableSteps.length} />
+              {availableSteps.length === 0 ? (
+                <p className="text-muted-foreground text-xs italic">No steps registered.</p>
+              ) : (
+                <ul className="flex flex-col gap-1">
+                  {availableSteps.map((s) => (
+                    <li
+                      key={s.id}
+                      className="flex flex-col gap-0.5 rounded-md border px-2 py-1.5 text-xs"
+                    >
+                      <span className="truncate font-mono">{s.id}</span>
+                      <div className="text-muted-foreground/80 flex flex-wrap gap-x-3 text-[10px]">
+                        <span className="font-mono">
+                          ← {s.requires.length ? s.requires.join(", ") : "(no inputs)"}
+                        </span>
+                        <span className="font-mono">
+                          → {s.produces.length ? s.produces.join(", ") : "(none)"}
+                        </span>
+                      </div>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </section>
+
+            <section className="flex flex-col gap-2">
+              <CatalogueSectionHeader
+                title={L.catalogueUnreachable}
+                count={unreachableWidgets.length}
+              />
+              {unreachableWidgets.length === 0 ? (
+                <p className="text-muted-foreground text-xs italic">
+                  {L.catalogueUnreachableEmpty}
+                </p>
+              ) : (
+                <ul className="flex flex-col gap-1">
+                  {unreachableWidgets.map((w) => {
+                    const candidate = w.missingKeys
+                      .map((k) => ({ key: k, step: producerOf.get(k) }))
+                      .find((c) => c.step)
+                    return (
+                      <li
+                        key={w.id}
+                        className="bg-muted/20 flex flex-col gap-1 rounded-md border px-2 py-1.5 text-xs"
+                      >
+                        <span className="truncate font-mono">{w.id}</span>
+                        <span className="text-muted-foreground/80 text-[10px]">
+                          {L.catalogueNeedsKeys}{" "}
+                          <span className="font-mono">{w.missingKeys.join(", ")}</span>
+                        </span>
+                        <div className="mt-0.5 flex flex-wrap items-center gap-1">
+                          {w.missingKeys.map((k) => (
+                            <Button key={k} variant="ghost" size="xs" onClick={() => onSeedKey(k)}>
+                              <Plus />
+                              <span className="font-mono">{k}</span>
+                            </Button>
+                          ))}
+                          {candidate && (
+                            <Button
+                              variant="outline"
+                              size="xs"
+                              onClick={() => onAddProducingStep(candidate.key)}
+                            >
+                              <ArrowDownToLine /> {L.catalogueAddProducingStep}
+                            </Button>
+                          )}
+                        </div>
+                      </li>
+                    )
+                  })}
+                </ul>
+              )}
+            </section>
+          </div>
+        </ScrollArea>
+      </SheetContent>
+    </Sheet>
+  )
+}
+
+function CatalogueSectionHeader({ title, count }: { title: string; count: number }) {
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-muted-foreground text-[10px] font-semibold tracking-[0.12em] uppercase">
+        {title}
+      </span>
+      <span className="bg-border h-px flex-1" aria-hidden="true" />
+      <Badge variant="outline" className="px-1.5 text-[10px]">
+        {count}
+      </Badge>
+    </div>
+  )
+}