@miragon/mcp-toolkit-ui 1.1.0 → 2.0.0

package/src/app/builder/builder-reducer.ts

@@ -97,193 +97,227 @@ function mapActiveRows(
 }
 
 // -------------------------------------------------------------------------- //
-// Reducer
+// Per-action handlers (dispatch table)
 // -------------------------------------------------------------------------- //
 
-export function draftReducer(state: BuilderDraftState, action: BuilderAction): BuilderDraftState {
-  switch (action.type) {
-    case "addWidgetToRow": {
-      const rows = activeRowsOf(state.draft, state.activeTabIndex)
-      const safeLen = rows.length > 0 ? rows.length : 1
-      const idx = Math.min(Math.max(action.targetRowIdx ?? state.focusedRowIndex, 0), safeLen - 1)
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
-        const safeRows = rs.length > 0 ? rs : emptyRows()
-        return safeRows.map((r, i) =>
-          i === idx
-            ? { row: [...r.row, { widget: action.widgetId, span: action.defaultSpan }] }
-            : r,
-        )
-      })
-      return { ...state, draft, focusedRowIndex: idx }
-    }
+type ActionOf<K extends BuilderAction["type"]> = Extract<BuilderAction, { type: K }>
 
-    case "addRow": {
-      let newIndex = state.focusedRowIndex
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
-        const next = [...rows, { row: [] }]
-        newIndex = next.length - 1
-        return next
-      })
-      return { ...state, draft, focusedRowIndex: newIndex }
-    }
+function addWidgetToRow(
+  state: BuilderDraftState,
+  action: ActionOf<"addWidgetToRow">,
+): BuilderDraftState {
+  const rows = activeRowsOf(state.draft, state.activeTabIndex)
+  const safeLen = rows.length > 0 ? rows.length : 1
+  const idx = Math.min(Math.max(action.targetRowIdx ?? state.focusedRowIndex, 0), safeLen - 1)
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
+    const safeRows = rs.length > 0 ? rs : emptyRows()
+    return safeRows.map((r, i) =>
+      i === idx ? { row: [...r.row, { widget: action.widgetId, span: action.defaultSpan }] } : r,
+    )
+  })
+  return { ...state, draft, focusedRowIndex: idx }
+}
 
-    case "removeRow": {
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
-        const next = rows.filter((_, i) => i !== action.rowIdx)
-        return next.length > 0 ? next : emptyRows()
-      })
-      // Matches the previous behaviour: decrement, floored at 0. Finding [9]
-      // clamping is scoped to tab switch / removeTab, so this stays as-is.
-      return { ...state, draft, focusedRowIndex: Math.max(0, state.focusedRowIndex - 1) }
-    }
+function addRow(state: BuilderDraftState): BuilderDraftState {
+  let newIndex = state.focusedRowIndex
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
+    const next = [...rows, { row: [] }]
+    newIndex = next.length - 1
+    return next
+  })
+  return { ...state, draft, focusedRowIndex: newIndex }
+}
 
-    case "moveRow": {
-      const target = action.rowIdx + action.direction
-      const rows = activeRowsOf(state.draft, state.activeTabIndex)
-      if (target < 0 || target >= rows.length) return state
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
-        const next = [...rs]
-        const [moved] = next.splice(action.rowIdx, 1)
-        if (!moved) return rs
-        next.splice(target, 0, moved)
-        return next
-      })
-      return { ...state, draft, focusedRowIndex: target }
-    }
+function removeRow(state: BuilderDraftState, action: ActionOf<"removeRow">): BuilderDraftState {
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) => {
+    const next = rows.filter((_, i) => i !== action.rowIdx)
+    return next.length > 0 ? next : emptyRows()
+  })
+  // Matches the previous behaviour: decrement, floored at 0. Finding [9]
+  // clamping is scoped to tab switch / removeTab, so this stays as-is.
+  return { ...state, draft, focusedRowIndex: Math.max(0, state.focusedRowIndex - 1) }
+}
 
-    case "setCellSpan": {
-      const clamped = Math.max(1, Math.min(12, action.span))
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
-        rows.map((r, i) =>
-          i === action.rowIdx
-            ? { row: r.row.map((c, j) => (j === action.cellIdx ? { ...c, span: clamped } : c)) }
-            : r,
-        ),
-      )
-      return { ...state, draft }
-    }
+function moveRow(state: BuilderDraftState, action: ActionOf<"moveRow">): BuilderDraftState {
+  const target = action.rowIdx + action.direction
+  const rows = activeRowsOf(state.draft, state.activeTabIndex)
+  if (target < 0 || target >= rows.length) return state
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rs) => {
+    const next = [...rs]
+    const [moved] = next.splice(action.rowIdx, 1)
+    if (!moved) return rs
+    next.splice(target, 0, moved)
+    return next
+  })
+  return { ...state, draft, focusedRowIndex: target }
+}
 
-    case "removeCell": {
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
-        rows.map((r, i) =>
-          i === action.rowIdx ? { row: r.row.filter((_, j) => j !== action.cellIdx) } : r,
-        ),
-      )
-      return { ...state, draft }
-    }
+function setCellSpan(state: BuilderDraftState, action: ActionOf<"setCellSpan">): BuilderDraftState {
+  const clamped = Math.max(1, Math.min(12, action.span))
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+    rows.map((r, i) =>
+      i === action.rowIdx
+        ? { row: r.row.map((c, j) => (j === action.cellIdx ? { ...c, span: clamped } : c)) }
+        : r,
+    ),
+  )
+  return { ...state, draft }
+}
 
-    case "setCellProps": {
-      const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
-        rows.map((r, i) =>
-          i === action.rowIdx
-            ? {
-                row: r.row.map((c, j) => {
-                  if (j !== action.cellIdx) return c
-                  if (action.next === undefined) {
-                    const rest: typeof c = { widget: c.widget }
-                    if (c.span !== undefined) rest.span = c.span
-                    return rest
-                  }
-                  return { ...c, props: action.next }
-                }),
-              }
-            : r,
-        ),
-      )
-      return { ...state, draft }
-    }
+function removeCell(state: BuilderDraftState, action: ActionOf<"removeCell">): BuilderDraftState {
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+    rows.map((r, i) =>
+      i === action.rowIdx ? { row: r.row.filter((_, j) => j !== action.cellIdx) } : r,
+    ),
+  )
+  return { ...state, draft }
+}
 
-    case "setFocusedRow":
-      return { ...state, focusedRowIndex: Math.max(0, action.rowIdx) }
+function setCellProps(
+  state: BuilderDraftState,
+  action: ActionOf<"setCellProps">,
+): BuilderDraftState {
+  const draft = mapActiveRows(state.draft, state.activeTabIndex, (rows) =>
+    rows.map((r, i) =>
+      i === action.rowIdx
+        ? {
+            row: r.row.map((c, j) => {
+              if (j !== action.cellIdx) return c
+              if (action.next === undefined) {
+                const rest: typeof c = { widget: c.widget }
+                if (c.span !== undefined) rest.span = c.span
+                return rest
+              }
+              return { ...c, props: action.next }
+            }),
+          }
+        : r,
+    ),
+  )
+  return { ...state, draft }
+}
 
-    case "selectTab": {
-      if (state.draft.kind !== "tabs") return state
-      if (action.tabIdx < 0 || action.tabIdx >= state.draft.tabs.length) return state
-      const rows = state.draft.tabs[action.tabIdx]?.rows ?? []
-      return {
-        ...state,
-        activeTabIndex: action.tabIdx,
-        focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
-      }
-    }
+function setFocusedRow(
+  state: BuilderDraftState,
+  action: ActionOf<"setFocusedRow">,
+): BuilderDraftState {
+  return { ...state, focusedRowIndex: Math.max(0, action.rowIdx) }
+}
 
-    case "startEditingTab":
-      return { ...state, editingTabIdx: action.tabIdx }
+function selectTab(state: BuilderDraftState, action: ActionOf<"selectTab">): BuilderDraftState {
+  if (state.draft.kind !== "tabs") return state
+  if (action.tabIdx < 0 || action.tabIdx >= state.draft.tabs.length) return state
+  const rows = state.draft.tabs[action.tabIdx]?.rows ?? []
+  return {
+    ...state,
+    activeTabIndex: action.tabIdx,
+    focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
+  }
+}
 
-    case "stopEditingTab":
-      return { ...state, editingTabIdx: null }
+function startEditingTab(
+  state: BuilderDraftState,
+  action: ActionOf<"startEditingTab">,
+): BuilderDraftState {
+  return { ...state, editingTabIdx: action.tabIdx }
+}
 
-    case "addTab": {
-      if (state.draft.kind === "tabs") {
-        const label = `Tab ${state.draft.tabs.length + 1}`
-        const nextTabs: DraftTab[] = [...state.draft.tabs, { label, rows: emptyRows() }]
-        return {
-          ...state,
-          draft: { kind: "tabs", tabs: nextTabs },
-          activeTabIndex: nextTabs.length - 1,
-        }
-      }
-      const seededTabs: DraftTab[] = [
-        { label: "Tab 1", rows: state.draft.rows },
-        { label: "Tab 2", rows: emptyRows() },
-      ]
-      return { ...state, draft: { kind: "tabs", tabs: seededTabs }, activeTabIndex: 1 }
-    }
+function stopEditingTab(state: BuilderDraftState): BuilderDraftState {
+  return { ...state, editingTabIdx: null }
+}
 
-    case "renameTab": {
-      const trimmed = action.label.trim()
-      if (!trimmed) return state
-      if (state.draft.kind !== "tabs") return state
-      // Reject duplicates — Tabs keys by label, collisions break the
-      // component. Signal the rejection so the UI can give feedback; the
-      // old label stays put.
-      if (state.draft.tabs.some((t, i) => i !== action.tabIdx && t.label === trimmed)) {
-        return { ...state, renameRejectedAt: state.renameRejectedAt + 1 }
-      }
-      const tabs = state.draft.tabs.map((t, i) =>
-        i === action.tabIdx ? { ...t, label: trimmed } : t,
-      )
-      return { ...state, draft: { kind: "tabs", tabs } }
+function addTab(state: BuilderDraftState): BuilderDraftState {
+  if (state.draft.kind === "tabs") {
+    const label = `Tab ${state.draft.tabs.length + 1}`
+    const nextTabs: DraftTab[] = [...state.draft.tabs, { label, rows: emptyRows() }]
+    return {
+      ...state,
+      draft: { kind: "tabs", tabs: nextTabs },
+      activeTabIndex: nextTabs.length - 1,
     }
+  }
+  const seededTabs: DraftTab[] = [
+    { label: "Tab 1", rows: state.draft.rows },
+    { label: "Tab 2", rows: emptyRows() },
+  ]
+  return { ...state, draft: { kind: "tabs", tabs: seededTabs }, activeTabIndex: 1 }
+}
 
-    case "removeTab": {
-      if (state.draft.kind !== "tabs") return state
-      const tabs = state.draft.tabs.filter((_, i) => i !== action.tabIdx)
-      const activeTabIndex = clampRowIndex(state.activeTabIndex, tabs.length)
-      if (tabs.length === 0) {
-        const draft: DraftLayout = { kind: "rows", rows: emptyRows() }
-        return {
-          ...state,
-          draft,
-          activeTabIndex: 0,
-          editingTabIdx: null,
-          focusedRowIndex: clampRowIndex(state.focusedRowIndex, draft.rows.length),
-        }
-      }
-      if (tabs.length === 1 && tabs[0]) {
-        const draft: DraftLayout = { kind: "rows", rows: tabs[0].rows }
-        return {
-          ...state,
-          draft,
-          activeTabIndex: 0,
-          editingTabIdx: null,
-          focusedRowIndex: clampRowIndex(state.focusedRowIndex, draft.rows.length),
-        }
-      }
-      const rows = tabs[activeTabIndex]?.rows ?? []
-      return {
-        ...state,
-        draft: { kind: "tabs", tabs },
-        activeTabIndex,
-        editingTabIdx: null,
-        focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
-      }
-    }
+function renameTab(state: BuilderDraftState, action: ActionOf<"renameTab">): BuilderDraftState {
+  const trimmed = action.label.trim()
+  if (!trimmed) return state
+  if (state.draft.kind !== "tabs") return state
+  // Reject duplicates — Tabs keys by label, collisions break the
+  // component. Signal the rejection so the UI can give feedback; the
+  // old label stays put.
+  if (state.draft.tabs.some((t, i) => i !== action.tabIdx && t.label === trimmed)) {
+    return { ...state, renameRejectedAt: state.renameRejectedAt + 1 }
+  }
+  const tabs = state.draft.tabs.map((t, i) => (i === action.tabIdx ? { ...t, label: trimmed } : t))
+  return { ...state, draft: { kind: "tabs", tabs } }
+}
 
-    default: {
-      // Exhaustiveness guard: a new action type without a case is a type error.
-      const _never: never = action
-      return _never
+function removeTab(state: BuilderDraftState, action: ActionOf<"removeTab">): BuilderDraftState {
+  if (state.draft.kind !== "tabs") return state
+  const tabs = state.draft.tabs.filter((_, i) => i !== action.tabIdx)
+  // One tab left collapses back to a flat draft (zero left: a flat empty one).
+  if (tabs.length <= 1) {
+    const draft: DraftLayout = { kind: "rows", rows: tabs[0]?.rows ?? emptyRows() }
+    return {
+      ...state,
+      draft,
+      activeTabIndex: 0,
+      editingTabIdx: null,
+      focusedRowIndex: clampRowIndex(state.focusedRowIndex, draft.rows.length),
     }
   }
+  const activeTabIndex = clampRowIndex(state.activeTabIndex, tabs.length)
+  const rows = tabs[activeTabIndex]?.rows ?? []
+  return {
+    ...state,
+    draft: { kind: "tabs", tabs },
+    activeTabIndex,
+    editingTabIdx: null,
+    focusedRowIndex: clampRowIndex(state.focusedRowIndex, rows.length),
+  }
+}
+
+// -------------------------------------------------------------------------- //
+// Reducer
+// -------------------------------------------------------------------------- //
+
+/**
+ * Dispatch table instead of a switch: one small handler per action. The
+ * mapped type keeps it exhaustive — a new `BuilderAction` variant without a
+ * matching entry is a type error (the table equivalent of the old switch's
+ * `never` default).
+ */
+const handlers: {
+  [K in BuilderAction["type"]]: (state: BuilderDraftState, action: ActionOf<K>) => BuilderDraftState
+} = {
+  addWidgetToRow,
+  addRow,
+  removeRow,
+  moveRow,
+  setCellSpan,
+  removeCell,
+  setCellProps,
+  setFocusedRow,
+  selectTab,
+  startEditingTab,
+  stopEditingTab,
+  addTab,
+  renameTab,
+  removeTab,
+}
+
+export function draftReducer(state: BuilderDraftState, action: BuilderAction): BuilderDraftState {
+  // TS cannot correlate `handlers[action.type]` with `action` across the
+  // union, so widen the picked handler once; the table type above already
+  // guarantees the per-variant pairing.
+  const handle = handlers[action.type] as (
+    state: BuilderDraftState,
+    action: BuilderAction,
+  ) => BuilderDraftState
+  return handle(state, action)
 }

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

@@ -0,0 +1,187 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type {
+  AvailableStep,
+  KeyCatalogEntry,
+  PipelineContext,
+  PipelineStepRef,
+  ReachableWidget,
+  UnreachableWidget,
+} from "@miragon/mcp-toolkit-core"
+import { parseToolResult } from "../../lib/parse-tool-result.js"
+import {
+  entriesToKeys,
+  toPipelineContext,
+  type KeyEntry,
+  type WireContext,
+} from "./builder-model.js"
+import type { RefreshStatus } from "./labels.js"
+
+// -------------------------------------------------------------------------- //
+// Builder catalogue hook — live snapshots from `get-builder-catalogue`
+// -------------------------------------------------------------------------- //
+
+const EMPTY_CONTEXT: PipelineContext = { steps: {}, keys: {}, errors: [] }
+
+/**
+ * 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
+ * status for the auto-apply chip, and the lookups derived from the
+ * snapshots. Extracted from `layout-builder.tsx` unchanged: fetch on mount
+ * (no debounce) so the builder is ready immediately, then debounce 600ms on
+ * every keys/steps edit. The ref pattern keeps the effect dependent on only
+ * `keyEntries` / `stepEntries`.
+ */
+export function useBuilderCatalogue({
+  callTool,
+  catalogueToolName,
+  keyEntries,
+  stepEntries,
+}: {
+  callTool: (name: string, args: object) => Promise<unknown>
+  catalogueToolName: string
+  keyEntries: KeyEntry[]
+  stepEntries: PipelineStepRef[]
+}) {
+  // ── Live snapshots from get-builder-catalogue responses ─────────────────
+  // Start empty — the first effect below fetches the catalogue on mount.
+  const [liveReachable, setLiveReachable] = useState<ReachableWidget[]>([])
+  const [liveUnreachable, setLiveUnreachable] = useState<UnreachableWidget[]>([])
+  const [liveCatalog, setLiveCatalog] = useState<KeyCatalogEntry[]>([])
+  const [liveSteps, setLiveSteps] = useState<AvailableStep[]>([])
+  const [liveContext, setLiveContext] = useState<PipelineContext>(EMPTY_CONTEXT)
+  // 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
+  // configured wouldn't render.
+  const [validationIssues, setValidationIssues] = useState<string[]>([])
+
+  // ── Refresh status (for the auto-apply chip) ────────────────────────────
+  const [status, setStatus] = useState<RefreshStatus>("idle")
+  // Last catalogue-fetch failure (Finding [3]). Surfaced as a toolbar banner
+  // 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)
+
+  const refreshBuilder = useCallback(async () => {
+    setStatus("refreshing")
+    try {
+      const result = await callTool(catalogueToolName, {
+        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 ?? [])
+      // A successful fetch clears any stale failure banner.
+      setRefreshError(null)
+    } catch (err) {
+      // Fail soft: when the host's server hasn't registered the app-only
+      // `get-builder-catalogue` tool (the builder platform is opt-in via
+      // `app.builder`), the call rejects. Degrade to the static catalogue
+      // already derived from the layout rather than crashing the iframe —
+      // but surface the failure so the user knows the palette may be stale
+      // (Finding [3]).
+      const reason = err instanceof Error ? err.message : String(err)
+      console.warn(
+        `[mcp-toolkit] builder catalogue fetch failed (${catalogueToolName}): ${reason}. ` +
+          "The builder platform may be disabled on this server (app.builder).",
+      )
+      setRefreshError(reason)
+    } finally {
+      setStatus("idle")
+    }
+  }, [catalogueToolName, callTool, keyEntries, stepEntries])
+
+  const refreshRef = useRef(refreshBuilder)
+  useEffect(() => {
+    refreshRef.current = refreshBuilder
+  }, [refreshBuilder])
+  const isFirstRun = useRef(true)
+  useEffect(() => {
+    if (isFirstRun.current) {
+      isFirstRun.current = false
+      void refreshRef.current()
+      return
+    }
+    setStatus("pending")
+    const handle = window.setTimeout(() => {
+      void refreshRef.current()
+    }, 600)
+    return () => {
+      window.clearTimeout(handle)
+    }
+  }, [keyEntries, stepEntries])
+
+  // ── Derived lookups ─────────────────────────────────────────────────────
+  const widgetById = useMemo(() => {
+    const map = new Map<string, ReachableWidget>()
+    for (const w of liveReachable) map.set(w.id, w)
+    return map
+  }, [liveReachable])
+
+  // Per-widget propsSchema lookup. Merged from both reachable and
+  // unreachable lists because a saved layout can reference a widget whose
+  // `requires` aren't currently satisfied — we still want the user to be
+  // able to edit its props.
+  const propsSchemaByWidgetId = useMemo(() => {
+    const map = new Map<string, Record<string, unknown>>()
+    for (const w of liveReachable) {
+      if (w.propsSchema) map.set(w.id, w.propsSchema)
+    }
+    for (const w of liveUnreachable) {
+      if (w.propsSchema) map.set(w.id, w.propsSchema)
+    }
+    return map
+  }, [liveReachable, liveUnreachable])
+
+  const paletteByApp = useMemo(() => {
+    const groups = new Map<string, ReachableWidget[]>()
+    for (const w of liveReachable) {
+      if (!groups.has(w.app)) groups.set(w.app, [])
+      groups.get(w.app)!.push(w)
+    }
+    return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
+  }, [liveReachable])
+
+  const liveKeyCount = useMemo(() => liveCatalog.filter((c) => c.inContext).length, [liveCatalog])
+
+  const stepsByApp = useMemo(() => {
+    const groups = new Map<string, AvailableStep[]>()
+    for (const s of liveSteps) {
+      if (!groups.has(s.app)) groups.set(s.app, [])
+      groups.get(s.app)!.push(s)
+    }
+    return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
+  }, [liveSteps])
+
+  return {
+    liveReachable,
+    liveUnreachable,
+    liveCatalog,
+    liveSteps,
+    liveContext,
+    validationIssues,
+    status,
+    refreshError,
+    widgetById,
+    propsSchemaByWidgetId,
+    paletteByApp,
+    liveKeyCount,
+    stepsByApp,
+  }
+}

package/src/app/builder/use-key-step-entries.ts

@@ -0,0 +1,60 @@
+import { useCallback, useState } from "react"
+import type { PipelineStepRef } from "@miragon/mcp-toolkit-core"
+import { defaultStepIdFor, keysToEntries, type KeyEntry } from "./builder-model.js"
+
+// -------------------------------------------------------------------------- //
+// Keys + steps editor state — the pipeline tab's editable entry lists
+// -------------------------------------------------------------------------- //
+
+/**
+ * Owns the key/step editor entries and their mutations, extracted from
+ * `layout-builder.tsx` unchanged. `addKey` de-dupes a prefilled name (the
+ * catalogue's "Add as key" action) and `addStep` derives a unique context
+ * id via `defaultStepIdFor`.
+ */
+export function useKeyStepEntries({
+  initialKeys,
+  initialSteps,
+}: {
+  initialKeys?: Record<string, unknown>
+  initialSteps?: PipelineStepRef[]
+}) {
+  const [keyEntries, setKeyEntries] = useState<KeyEntry[]>(() => keysToEntries(initialKeys))
+  const [stepEntries, setStepEntries] = useState<PipelineStepRef[]>(() => initialSteps ?? [])
+
+  const addKey = useCallback((prefilledName?: string) => {
+    setKeyEntries((prev) => {
+      if (prefilledName) {
+        if (prev.some((e) => e.name === prefilledName)) return prev
+        return [...prev, { name: prefilledName, rawValue: "" }]
+      }
+      return [...prev, { name: "", rawValue: "" }]
+    })
+  }, [])
+
+  const updateKey = useCallback((idx: number, patch: Partial<KeyEntry>) => {
+    setKeyEntries((prev) => prev.map((e, i) => (i === idx ? { ...e, ...patch } : e)))
+  }, [])
+
+  const removeKey = useCallback((idx: number) => {
+    setKeyEntries((prev) => prev.filter((_, i) => i !== idx))
+  }, [])
+
+  const addStep = useCallback((stepId?: string) => {
+    setStepEntries((prev) => {
+      const taken = new Set(prev.map((s) => s.id))
+      const newId = stepId ? defaultStepIdFor(stepId, taken) : `step-${prev.length + 1}`
+      return [...prev, { id: newId, step: stepId ?? "", optional: false }]
+    })
+  }, [])
+
+  const updateStep = useCallback((idx: number, patch: Partial<PipelineStepRef>) => {
+    setStepEntries((prev) => prev.map((s, i) => (i === idx ? { ...s, ...patch } : s)))
+  }, [])
+
+  const removeStep = useCallback((idx: number) => {
+    setStepEntries((prev) => prev.filter((_, i) => i !== idx))
+  }, [])
+
+  return { keyEntries, stepEntries, addKey, updateKey, removeKey, addStep, updateStep, removeStep }
+}