@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/app/mcp-use-host-bridge.test.tsx

@@ -0,0 +1,180 @@
+// @vitest-environment happy-dom
+import { useEffect, type ReactNode } from "react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { flushEffects, hookProbe, renderWithEffects, type EffectRender } from "../render-effects.js"
+import { useHostBridge, type HostBridge } from "./host-bridge.js"
+import { McpUseHostBridgeProvider, useViewResultSink } from "./mcp-use-host-bridge.js"
+import { useHostModelContext } from "./model-context.js"
+
+/**
+ * `McpUseHostBridgeProvider`'s wiring with its effects running (toolkit#176
+ * K15, K20, N29): `getWidgetData()` returns the payload the view reports it
+ * shows, the bridge's `setModelContext` is one line of the view's native
+ * model-context tree, and `useHostModelContext` lines come and go with their
+ * component. The mcp-use view hooks are the only mock.
+ */
+
+const host = vi.hoisted(
+  (): {
+    tool: { status: string; toolOutput?: unknown }
+    useViewState: ReturnType<typeof vi.fn> | null
+  } => ({ tool: { status: "pending" }, useViewState: null }),
+)
+
+vi.mock(import("mcp-use/react"), async (importOriginal) => {
+  const actual = await importOriginal()
+  const { createElement } = await import("react")
+  host.useViewState = vi.fn()
+  const ModelContext = ({ content }: { content: string }) =>
+    // Not a <meta>: React 19 hoists those into <head>.
+    createElement("output", { "data-model-context": content })
+  const stable = {
+    dynamic: { callTool: () => Promise.resolve({}) },
+    followUp: () => Promise.resolve(),
+    openExternal: () => Promise.resolve(),
+  }
+  return {
+    ...actual,
+    ModelContext: ModelContext as unknown as typeof actual.ModelContext,
+    useDynamicTool: (() => stable.dynamic) as unknown as typeof actual.useDynamicTool,
+    useSendFollowUp: (() => stable.followUp) as unknown as typeof actual.useSendFollowUp,
+    useOpenExternal: (() => stable.openExternal) as unknown as typeof actual.useOpenExternal,
+    useToolContext: (() => host.tool) as unknown as typeof actual.useToolContext,
+    useViewTheme: (() => "light") as unknown as typeof actual.useViewTheme,
+    useHostContext: (() => ({ isAvailable: true })) as unknown as typeof actual.useHostContext,
+    useViewState: host.useViewState as unknown as typeof actual.useViewState,
+  }
+})
+
+const PAYLOAD = { title: "Incidents", context: { keys: {} }, layout: { rows: [] } }
+
+/** Reports `payload` the way McpAppView reports what it shows. */
+function Reporter({ payload }: { payload: unknown }) {
+  const report = useViewResultSink()
+  useEffect(() => {
+    report?.(payload)
+  }, [payload, report])
+  return null
+}
+
+/** Calls the bridge's setModelContext with `text` on every change. */
+function BridgeLine({ text }: { text: string }) {
+  const bridge = useHostBridge()
+  useEffect(() => {
+    bridge.setModelContext?.(text)
+  }, [bridge, text])
+  return null
+}
+
+function Line({ content }: { content: string | null }) {
+  useHostModelContext(content)
+  return null
+}
+
+const lines = (view: EffectRender) =>
+  [...view.container.querySelectorAll("[data-model-context]")].map((node) =>
+    node.getAttribute("data-model-context"),
+  )
+
+let mounted: EffectRender | null = null
+
+async function render(children: ReactNode) {
+  mounted = await renderWithEffects(<McpUseHostBridgeProvider>{children}</McpUseHostBridgeProvider>)
+  return mounted
+}
+
+const rerender = (view: EffectRender, children: ReactNode) =>
+  view.rerender(<McpUseHostBridgeProvider>{children}</McpUseHostBridgeProvider>)
+
+beforeEach(() => {
+  host.tool = { status: "pending", toolOutput: undefined }
+})
+
+afterEach(async () => {
+  await mounted?.unmount()
+  mounted = null
+})
+
+describe("McpUseHostBridgeProvider getWidgetData (K15)", () => {
+  const bridgeProbe = () => hookProbe((): HostBridge => useHostBridge())
+
+  it("returns the payload the view reports while the host's latch is still pending", async () => {
+    const probe = bridgeProbe()
+    const view = await render(<probe.Probe />)
+    expect(probe.current().getWidgetData()).toBeNull()
+    await rerender(
+      view,
+      <>
+        <probe.Probe />
+        <Reporter payload={PAYLOAD} />
+      </>,
+    )
+    await flushEffects()
+    expect(probe.current().getWidgetData()).toEqual(PAYLOAD)
+  })
+
+  it("prefers the reported payload over an unusable latched output (structuredContent: null)", async () => {
+    host.tool = { status: "ready", toolOutput: null }
+    const probe = bridgeProbe()
+    const view = await render(<probe.Probe />)
+    expect(probe.current().getWidgetData()).toBeNull()
+    await rerender(
+      view,
+      <>
+        <probe.Probe />
+        <Reporter payload={PAYLOAD} />
+      </>,
+    )
+    await flushEffects()
+    expect(probe.current().getWidgetData()).toEqual(PAYLOAD)
+  })
+
+  it("without a report, the latched output once ready", async () => {
+    host.tool = { status: "ready", toolOutput: PAYLOAD }
+    const probe = bridgeProbe()
+    await render(<probe.Probe />)
+    expect(probe.current().getWidgetData()).toEqual(PAYLOAD)
+  })
+})
+
+describe("McpUseHostBridgeProvider model context (K20, N29)", () => {
+  it("the bridge's setModelContext is one native line: set, replaced, removed when blank", async () => {
+    const view = await render(<BridgeLine text="Viewing 3 incidents" />)
+    await flushEffects()
+    expect(lines(view)).toEqual(["Viewing 3 incidents"])
+    await rerender(view, <BridgeLine text="Viewing 2 incidents" />)
+    await flushEffects()
+    expect(lines(view), "last writer wins: still one line").toEqual(["Viewing 2 incidents"])
+    await rerender(view, <BridgeLine text="" />)
+    await flushEffects()
+    expect(lines(view)).toEqual([])
+  })
+
+  it("never seeds the widgets' view state (N29)", async () => {
+    await render(<BridgeLine text="Viewing 3 incidents" />)
+    await flushEffects()
+    expect(host.useViewState).not.toHaveBeenCalled()
+  })
+
+  it("useHostModelContext joins the tree on mount and leaves it on unmount or when blank", async () => {
+    const view = await render(
+      <>
+        <Line content="Filter: open" />
+        <Line content="Selected: #42" />
+      </>,
+    )
+    expect(lines(view)).toEqual(["Filter: open", "Selected: #42"])
+    await rerender(
+      view,
+      <>
+        <Line content="Filter: open" />
+        <Line content="  " />
+      </>,
+    )
+    expect(lines(view), "a blank line is removed").toEqual(["Filter: open"])
+    await rerender(view, <Line content="Filter: open" />)
+    expect(lines(view)).toEqual(["Filter: open"])
+    await rerender(view, null)
+    expect(lines(view), "unmounted, its line is gone").toEqual([])
+  })
+})

package/src/app/mcp-use-host-bridge.tsx

@@ -14,24 +14,17 @@ import {
   useOpenExternal,
   useSendFollowUp,
   useToolContext,
-  useViewState,
   useViewTheme,
 } from "mcp-use/react"
 import { HostBridgeProvider, toHostBridge, type HostBridge } from "./host-bridge.js"
-
-/**
- * `true` inside an mcp-use 2.x view — i.e. under a
- * {@link McpUseHostBridgeProvider}, which itself only renders under a
- * `bootstrapView`-mounted tree. Components that want to use `mcp-use/react`
- * primitives (which throw outside a view) branch on this instead of probing
- * mcp-use internals; see `adaptDataWidget`'s ModelContext handling.
- */
-const McpUseViewContext = createContext(false)
-
-/** Whether the subtree runs inside an mcp-use view (see {@link McpUseViewContext}). */
-export function useIsInsideMcpUseView(): boolean {
-  return useContext(McpUseViewContext)
-}
+import {
+  McpUseViewContext,
+  ModelContextChannelContext,
+  ModelContextLines,
+  modelContextLine,
+  withModelContextLine,
+  type ModelContextChannel,
+} from "./model-context.js"
 
 type DynamicCallTool = (name: string, args: Record<string, unknown>) => Promise<unknown>
 type BoundCall = (args: Record<string, unknown>) => Promise<unknown>
@@ -99,6 +92,34 @@ function useDynamicToolPool(): { callTool: DynamicCallTool; binders: ReactNode }
   return { callTool, binders }
 }
 
+/** The line of the bridge's own `setModelContext` (last writer wins). */
+const BRIDGE_LINE = "host-bridge"
+
+/**
+ * Where the view reports the payload it shows (the host's, a stripped-result
+ * recovery's, the user's retry or refresh), so `HostBridge.getWidgetData()`
+ * returns what the view shows (toolkit#176 K15): the bridge, not one
+ * component's local state, holds the view's data.
+ */
+const ViewResultSinkContext = createContext<((payload: unknown) => void) | null>(null)
+
+/**
+ * The sink for the payload a view shows, or `null` outside a
+ * {@link McpUseHostBridgeProvider}. `McpAppView` reports through it.
+ */
+export function useViewResultSink(): ((payload: unknown) => void) | null {
+  return useContext(ViewResultSinkContext)
+}
+
+/**
+ * What `getWidgetData()` returns: the payload the view reported it shows,
+ * else the rendering tool's output once the call latched `"ready"`.
+ */
+function bridgeOutput(shown: unknown, tool: { status: string; toolOutput?: unknown }): unknown {
+  if (shown !== undefined) return shown
+  return tool.status === "ready" ? tool.toolOutput : undefined
+}
+
 /**
  * Install the `mcp-use` {@link HostBridge} (plus the view-scope flag) for a
  * subtree inside an mcp-use 2.x view.
@@ -112,10 +133,16 @@ function useDynamicToolPool(): { callTool: DynamicCallTool; binders: ReactNode }
  * - `sendFollowup` / `openExternal` — `useSendFollowUp` / `useOpenExternal`;
  *   while the bridge is not connected (local `file://` preview), `openExternal`
  *   throws into `toHostBridge`'s documented `window.open` fallback.
- * - `setModelContext` — writes `{ __model_context }` into the view state,
- *   which hosts receive via `ui/update-model-context` (ext-apps) or
- *   `widgetState` (ChatGPT). The key is a toolkit-owned convention since 2.x.
- * - `getWidgetData` — the rendering tool's `structuredContent` once ready.
+ * - `setModelContext` — one line of the view's model-context tree (an mcp-use
+ *   `ModelContext` node beside the ones `HostModelContext` and
+ *   `useHostModelContext` register), which hosts receive via
+ *   `ui/update-model-context` (ext-apps) or `widgetState` (ChatGPT). The
+ *   provider does not seed mcp-use's view state, so a widget's own
+ *   `useViewState(default)` keeps its default (N29).
+ * - `getWidgetData` — the payload the view reports it shows
+ *   ({@link useViewResultSink}): the host's, or the one it got by re-running
+ *   the tool when the host stripped it or kept back an unusable one. Without
+ *   a report, the rendering tool's `structuredContent` once ready.
  *
  * Must render inside a `bootstrapView`-mounted tree (the mcp-use hooks throw
  * otherwise) — `McpToolkitApp` does this for the standard bundle; use it
@@ -128,9 +155,17 @@ export function McpUseHostBridgeProvider({ children }: { children: ReactNode }):
   const tool = useToolContext()
   const theme = useViewTheme()
   const { isAvailable } = useHostContext()
-  const [, setViewState] = useViewState<Record<string, unknown>>({})
+  const [lines, setLines] = useState<ReadonlyMap<string, string>>(() => new Map())
+  const channel = useMemo<ModelContextChannel>(
+    () => ({ set: (id, content) => setLines((prev) => withModelContextLine(prev, id, content)) }),
+    [],
+  )
+  // The payload the view reports it shows wins: after a latch the view could
+  // not render (`structuredContent: null` latches "ready"), the host's own
+  // output is not what the user sees.
+  const [shown, setShown] = useState<unknown>(undefined)
 
-  const output = tool.status === "ready" ? tool.toolOutput : undefined
+  const output = bridgeOutput(shown, tool)
 
   const bridge = useMemo<HostBridge>(
     () =>
@@ -147,18 +182,26 @@ export function McpUseHostBridgeProvider({ children }: { children: ReactNode }):
         },
         output,
         theme,
+        // toHostBridge writes model context as `{ __model_context }`: it
+        // becomes the bridge's line of the one channel, never view state.
         setState: (state) => {
-          setViewState((prev) => ({ ...prev, ...state }))
+          const text = state.__model_context
+          if (typeof text === "string") channel.set(BRIDGE_LINE, modelContextLine(text))
           return Promise.resolve()
         },
       }),
-    [callTool, sendFollowUp, openExternal, output, theme, isAvailable, setViewState],
+    [callTool, sendFollowUp, openExternal, output, theme, isAvailable, channel],
   )
 
   return (
     <McpUseViewContext.Provider value={true}>
       {binders}
-      <HostBridgeProvider bridge={bridge}>{children}</HostBridgeProvider>
+      <ModelContextLines lines={lines} />
+      <ModelContextChannelContext.Provider value={channel}>
+        <ViewResultSinkContext.Provider value={setShown}>
+          <HostBridgeProvider bridge={bridge}>{children}</HostBridgeProvider>
+        </ViewResultSinkContext.Provider>
+      </ModelContextChannelContext.Provider>
     </McpUseViewContext.Provider>
   )
 }

package/src/app/model-context.test.tsx

@@ -0,0 +1,116 @@
+import type { ReactNode } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it, vi } from "vitest"
+import {
+  HostModelContext,
+  McpUseViewContext,
+  ModelContextLines,
+  modelContextLine,
+  useIsInsideMcpUseView,
+  withModelContextLine,
+} from "./model-context.js"
+
+// The native node, made visible (it throws outside a bootstrapView mount).
+vi.mock(import("mcp-use/react"), async (importOriginal) => {
+  const actual = await importOriginal()
+  const { createElement, Fragment } = await import("react")
+  const ModelContext = ({ content, children }: { content: string; children?: ReactNode }) =>
+    createElement(
+      Fragment,
+      null,
+      createElement("meta", { "data-model-context": content }),
+      children,
+    )
+  return { ...actual, ModelContext: ModelContext as unknown as typeof actual.ModelContext }
+})
+
+/**
+ * The view's ONE model-context channel (toolkit#176 K20, N29): every line
+ * the view reports joins the native mcp-use tree inside a view; outside one
+ * it falls back to the bridge.
+ */
+describe("withModelContextLine", () => {
+  it("sets, replaces and removes a line, keeping the order of first registration", () => {
+    const one = withModelContextLine(new Map(), "a", "Viewing 3 incidents")
+    const two = withModelContextLine(one, "b", "Filter: open")
+    const replaced = withModelContextLine(two, "a", "Viewing 2 incidents")
+    expect([...replaced]).toEqual([
+      ["a", "Viewing 2 incidents"],
+      ["b", "Filter: open"],
+    ])
+    expect([...withModelContextLine(replaced, "a", null)]).toEqual([["b", "Filter: open"]])
+  })
+
+  it("returns the same map when nothing changes (no re-render)", () => {
+    const lines = withModelContextLine(new Map(), "a", "x")
+    expect(withModelContextLine(lines, "a", "x")).toBe(lines)
+    expect(withModelContextLine(lines, "missing", null)).toBe(lines)
+  })
+})
+
+describe("modelContextLine", () => {
+  it("a blank line is nothing to report", () => {
+    expect(modelContextLine("Viewing 3 incidents")).toBe("Viewing 3 incidents")
+    expect(modelContextLine("  ")).toBeNull()
+    expect(modelContextLine("")).toBeNull()
+    expect(modelContextLine(null)).toBeNull()
+    expect(modelContextLine(undefined)).toBeNull()
+  })
+})
+
+describe("HostModelContext", () => {
+  it("inside a view: the native node, its children nested below it", () => {
+    const html = renderToStaticMarkup(
+      <McpUseViewContext.Provider value={true}>
+        <HostModelContext content="Viewing 3 incidents">
+          <span>board</span>
+        </HostModelContext>
+      </McpUseViewContext.Provider>,
+    )
+    expect(html).toBe('<meta data-model-context="Viewing 3 incidents"/><span>board</span>')
+  })
+
+  it("reports one line without children", () => {
+    const html = renderToStaticMarkup(
+      <McpUseViewContext.Provider value={true}>
+        <HostModelContext content="The view could not be shown." />
+      </McpUseViewContext.Provider>,
+    )
+    expect(html).toBe('<meta data-model-context="The view could not be shown."/>')
+  })
+
+  it("outside a view: no native node, the children render (the bridge gets the line)", () => {
+    const html = renderToStaticMarkup(
+      <HostModelContext content="Viewing 3 incidents">
+        <span>board</span>
+      </HostModelContext>,
+    )
+    expect(html).toBe("<span>board</span>")
+  })
+})
+
+describe("ModelContextLines / useIsInsideMcpUseView", () => {
+  it("renders one native node per channel line", () => {
+    const lines = new Map([
+      ["a", "Viewing 3 incidents"],
+      ["host-bridge", "Selected: INC-7"],
+    ])
+    expect(renderToStaticMarkup(<ModelContextLines lines={lines} />)).toBe(
+      '<meta data-model-context="Viewing 3 incidents"/><meta data-model-context="Selected: INC-7"/>',
+    )
+  })
+
+  it("reports the view scope", () => {
+    function Probe() {
+      return <i>{String(useIsInsideMcpUseView())}</i>
+    }
+    expect(renderToStaticMarkup(<Probe />)).toBe("<i>false</i>")
+    expect(
+      renderToStaticMarkup(
+        <McpUseViewContext.Provider value={true}>
+          <Probe />
+        </McpUseViewContext.Provider>,
+      ),
+    ).toBe("<i>true</i>")
+  })
+})

package/src/app/model-context.tsx

@@ -0,0 +1,125 @@
+import { createContext, useContext, useEffect, useId, type ReactNode } from "react"
+import { ModelContext } from "mcp-use/react"
+import { useHostBridgeOrNull } from "./host-bridge.js"
+
+/**
+ * The view's model context: what the model reads about the view on its next
+ * turn (`ui/update-model-context`). The one module that builds on mcp-use's
+ * native `ModelContext`, which throws outside a `bootstrapView` mount; every
+ * other component reports through {@link HostModelContext} or
+ * {@link useHostModelContext} (toolkit#176 K20).
+ */
+
+/**
+ * `true` inside an mcp-use 2.x view — i.e. under a `McpUseHostBridgeProvider`,
+ * which itself only renders under a `bootstrapView`-mounted tree. Components
+ * that want to use `mcp-use/react` primitives (which throw outside a view)
+ * branch on this instead of probing mcp-use internals. Exported for the
+ * provider and for tests that render a view-scoped subtree.
+ */
+export const McpUseViewContext = createContext(false)
+
+/** Whether the subtree runs inside an mcp-use view (see {@link McpUseViewContext}). */
+export function useIsInsideMcpUseView(): boolean {
+  return useContext(McpUseViewContext)
+}
+
+/**
+ * Model-context reporting that works on every host — the host-portable
+ * replacement for rendering `mcp-use/react`'s `ModelContext` directly.
+ *
+ * Inside an mcp-use view it renders the native `ModelContext`, which nests:
+ * the lines of its children hang below its own in the one description the
+ * host receives. Everywhere else — ChatGPT via `createChatGptHostBridge`, the
+ * `WidgetFixtureHost` harness, standalone apps — the description flows
+ * through the bridge's `setModelContext` instead (last-writer-wins; fine for
+ * the single-widget mounts those hosts render).
+ *
+ * Widgets that self-fetch and report their own context (cockpit views like
+ * `TasksBoard`) must use this instead of importing `ModelContext` from
+ * `mcp-use/react` — the direct import crashes the widget in every non-view
+ * mount, starting with the widget playground. Without `children` it reports
+ * one line where it is rendered.
+ */
+export function HostModelContext({
+  content,
+  children,
+}: {
+  content: string
+  children?: ReactNode
+}): ReactNode {
+  const insideView = useIsInsideMcpUseView()
+  if (insideView) return <ModelContext content={content}>{children}</ModelContext>
+  return <BridgeModelContext content={content}>{children}</BridgeModelContext>
+}
+
+function BridgeModelContext({ content, children }: { content: string; children?: ReactNode }) {
+  const bridge = useHostBridgeOrNull()
+  const setModelContext = bridge?.setModelContext
+  useEffect(() => {
+    setModelContext?.(content)
+  }, [setModelContext, content])
+  return children
+}
+
+/**
+ * The view's ONE model-context channel: lines registered here render as
+ * root-level native `ModelContext` nodes ({@link ModelContextLines}), the
+ * tree `HostModelContext` nodes join too, so the host receives everything
+ * the view reports in one description. `McpUseHostBridgeProvider` owns it.
+ */
+export interface ModelContextChannel {
+  /** Set (`content`) or remove (`null`) the line registered under `id`. */
+  set: (id: string, content: string | null) => void
+}
+
+export const ModelContextChannelContext = createContext<ModelContextChannel | null>(null)
+
+/** `lines` with `id` set to `content` (or removed for `null`); the same map when nothing changes. */
+export function withModelContextLine(
+  lines: ReadonlyMap<string, string>,
+  id: string,
+  content: string | null,
+): ReadonlyMap<string, string> {
+  if (content === null ? !lines.has(id) : lines.get(id) === content) return lines
+  const next = new Map(lines)
+  if (content === null) next.delete(id)
+  else next.set(id, content)
+  return next
+}
+
+/** A line of model context, or `null` for a blank one (nothing to report). */
+export function modelContextLine(content: string | null | undefined): string | null {
+  return content?.trim() ? content : null
+}
+
+/** Renders the channel's lines as native `ModelContext` nodes (inside a view only). */
+export function ModelContextLines({ lines }: { lines: ReadonlyMap<string, string> }): ReactNode {
+  return [...lines].map(([id, content]) => <ModelContext key={id} content={content} />)
+}
+
+/**
+ * Report one line of model context for as long as the calling component is
+ * mounted: what the user is looking at, a filter, an error the user sees.
+ * The channel helper for components with nothing to wrap
+ * ({@link HostModelContext} is the wrapping form).
+ *
+ * Inside an mcp-use view the line joins the view's one model-context tree and
+ * leaves it on unmount or when `content` turns blank. Elsewhere (the ChatGPT
+ * bridge, the fixture harness, standalone apps) it goes through the bridge's
+ * `setModelContext`, last writer wins.
+ */
+export function useHostModelContext(content: string | null | undefined): void {
+  const channel = useContext(ModelContextChannelContext)
+  const setModelContext = useHostBridgeOrNull()?.setModelContext
+  const id = useId()
+  const line = modelContextLine(content)
+  useEffect(() => {
+    if (channel) {
+      channel.set(id, line)
+      return () => channel.set(id, null)
+    }
+    if (line !== null) setModelContext?.(line)
+    return undefined
+  }, [channel, id, line, setModelContext])
+}

package/src/app/use-build-mode-focus.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, type RefObject } from "react"
+
+/** Where focus goes when build mode opens: the builder's title. */
+export const BUILDER_FOCUS_TARGET = '[data-slot="builder-title"]'
+/** Where focus goes when build mode closes (Apply or Discard): the edit button that opened it. */
+export const VIEW_FOCUS_TARGET = '[data-slot="view-edit"]'
+
+/**
+ * The selector focus moves to when build mode switches, or `null` when it
+ * did not switch (the first render included). Pure, so the hand-off is
+ * unit-testable without a DOM.
+ */
+export function buildModeFocusTarget(previous: boolean, current: boolean): string | null {
+  if (previous === current) return null
+  return current ? BUILDER_FOCUS_TARGET : VIEW_FOCUS_TARGET
+}
+
+/**
+ * Where focus goes when a `LayoutBuilder` mounts, by its reset `generation`:
+ * after a reset (Discard without `onExit`, > 0) the builder's title, because
+ * the Discard button that had the focus went with the old builder; on the
+ * first mount nowhere (McpAppView's build-mode switch handles that one).
+ */
+export function builderMountFocusTarget(generation: number): string | null {
+  return generation > 0 ? BUILDER_FOCUS_TARGET : null
+}
+
+/**
+ * Focuses the element `target` selects inside the returned ref's element once
+ * it mounts; `null` focuses nothing. `LayoutBuilder` passes
+ * {@link builderMountFocusTarget} of its reset generation.
+ */
+export function useFocusOnMount<T extends HTMLElement>(target: string | null): RefObject<T | null> {
+  const ref = useRef<T>(null)
+  useEffect(() => {
+    if (target) ref.current?.querySelector<HTMLElement>(target)?.focus()
+  }, [target])
+  return ref
+}
+
+/**
+ * Moves focus across the build-mode switch: the button that opened the
+ * builder disappears with the toolbar, so focus lands on the builder's title;
+ * Apply and Discard unmount the builder, so focus returns to the edit button.
+ * Focus that already sits outside the view (another frame, the host) stays
+ * where it is.
+ */
+export function useBuildModeFocus(
+  buildMode: boolean,
+  frameRef: RefObject<HTMLElement | null>,
+): void {
+  const previous = useRef(buildMode)
+  useEffect(() => {
+    const target = buildModeFocusTarget(previous.current, buildMode)
+    previous.current = buildMode
+    const frame = frameRef.current
+    if (!target || !frame) return
+    const active = frame.ownerDocument.activeElement
+    if (active && active !== frame.ownerDocument.body && !frame.contains(active)) return
+    frame.querySelector<HTMLElement>(target)?.focus()
+  }, [buildMode, frameRef])
+}