@miragon/pulse-widget-shell 0.0.0-stage → 0.21.0

package/dist/ui/app-shell-providers.test.js

@@ -0,0 +1,249 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { bootstrapView, disposeView } from "mcp-use/react";
+import { queryClient, useLocale } from "@miragon/mcp-toolkit-ui";
+import { useHostBridge } from "@miragon/mcp-toolkit-ui/app";
+import { AppShellProviders } from "./app-shell-providers.js";
+import { SHELL_SETTINGS_DATA } from "../shell-settings-contract.js";
+import { useHostWidgets } from "./host-widgets.js";
+import { LocalizedAppView } from "./localized-app-view.js";
+import { useHostDisplayMode } from "./widget-shell.js";
+const PROFILE_FEED = SHELL_SETTINGS_DATA;
+function profileResult(view) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(view) }],
+        structuredContent: view,
+    };
+}
+/** A minimal host: answers `ui/initialize` and `tools/call`, records everything the view sent. */
+function createFakeHost(options) {
+    const sent = [];
+    const transport = {
+        onmessage: undefined,
+        onclose: undefined,
+        onerror: undefined,
+        start: () => Promise.resolve(),
+        close: () => {
+            transport.onclose?.();
+            return Promise.resolve();
+        },
+        send: (message) => {
+            sent.push(message);
+            if (message.id !== undefined && message.method) {
+                const reply = answer(message);
+                queueMicrotask(() => transport.onmessage?.({ jsonrpc: "2.0", id: message.id, ...reply }));
+            }
+            return Promise.resolve();
+        },
+    };
+    function answer(message) {
+        if (message.method === "ui/initialize") {
+            return {
+                result: {
+                    protocolVersion: message.params?.protocolVersion,
+                    hostInfo: { name: "fake-host", version: "1.0.0" },
+                    hostCapabilities: options.hostCapabilities ?? {
+                        serverTools: {},
+                        updateModelContext: { text: {} },
+                    },
+                    hostContext: options.hostContext,
+                },
+            };
+        }
+        if (message.method === "tools/call") {
+            const result = options.tools?.[String(message.params?.name)];
+            if (result)
+                return { result };
+            return { error: { code: -32602, message: `unknown tool ${String(message.params?.name)}` } };
+        }
+        return { result: {} };
+    }
+    return {
+        transport: transport,
+        /** The methods the view sent, in order (requests and notifications). */
+        methods: () => sent.map((m) => m.method),
+        toolCalls: () => sent
+            .filter((m) => m.method === "tools/call")
+            .map((m) => ({ name: m.params?.name, arguments: m.params?.arguments })),
+        notify: (method, params) => transport.onmessage?.({ jsonrpc: "2.0", method, params }),
+    };
+}
+const DemoWidget = () => null;
+/** Everything the stack provides, in one line: locale | display mode | registry. */
+function Probe() {
+    // Throws without the host bridge above — part of what is under test.
+    useHostBridge();
+    const widgets = Object.keys(useHostWidgets()).join(",");
+    return _jsx("output", { "data-testid": "probe", children: `${useLocale()}|${useHostDisplayMode()}|${widgets}` });
+}
+function mount(host) {
+    bootstrapView({
+        default: () => (_jsx(AppShellProviders, { widgets: { "demo:widget": DemoWidget }, children: _jsx(Probe, {}) })),
+    }, { transport: host.transport });
+}
+const probe = () => document.querySelector("[data-testid=probe]")?.textContent;
+const root = document.documentElement;
+afterEach(async () => {
+    await disposeView();
+    document.getElementById("root")?.remove();
+    // The toolkit's query client is a module singleton shared by every mount —
+    // the suite runs on its PRODUCTION defaults (react-query's retries
+    // included); cancelling stops any retry still waiting.
+    await queryClient.cancelQueries();
+    queryClient.clear();
+    root.className = "";
+    root.lang = "";
+    root.removeAttribute("data-theme");
+    root.removeAttribute("style");
+    vi.unstubAllGlobals();
+});
+describe("AppShellProviders (real mcp-use view runtime)", () => {
+    it("wires host bridge → display mode → profile → widget registry, in that order", async () => {
+        const host = createFakeHost({
+            hostContext: {
+                theme: "dark",
+                displayMode: "fullscreen",
+                availableDisplayModes: ["inline", "fullscreen"],
+            },
+            tools: { [PROFILE_FEED]: profileResult({ language: "de" }) },
+        });
+        mount(host);
+        // ProfileGate reached the host through the bridge ABOVE it (the profile
+        // locale arrived), the display mode came from the view scope, and the
+        // registry is provided below the gate.
+        await vi.waitFor(() => expect(probe()).toBe("de|fullscreen|demo:widget"));
+        expect(host.toolCalls()).toEqual([{ name: PROFILE_FEED, arguments: {} }]);
+        // The profile language and the host's theme are applied document-wide —
+        // one theme on every channel the CSS, the host and native controls read.
+        expect(root.lang).toBe("de");
+        expect(root.classList.contains("dark")).toBe(true);
+        expect(root.getAttribute("data-theme")).toBe("dark");
+        expect(root.style.getPropertyValue("color-scheme")).toBe("dark");
+    });
+    it("follows the HOST's theme and, for a system profile, its locale — over a light OS and English defaults (#339)", async () => {
+        vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({
+            matches: false,
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+        }));
+        const host = createFakeHost({
+            hostContext: { theme: "dark", locale: "de-DE" },
+            tools: { [PROFILE_FEED]: profileResult({ language: "system" }) },
+        });
+        mount(host);
+        await vi.waitFor(() => expect(probe()).toBe("de|inline|demo:widget"));
+        expect(root.lang).toBe("de");
+        expect(root.classList.contains("dark")).toBe(true);
+        expect(root.getAttribute("data-theme")).toBe("dark");
+    });
+    it("puts the host's style variables and font on the document, and fills it in fullscreen", async () => {
+        const host = createFakeHost({
+            hostContext: {
+                theme: "light",
+                displayMode: "fullscreen",
+                availableDisplayModes: ["inline", "fullscreen"],
+                styles: {
+                    variables: { "--font-sans": "HostSans, sans-serif", "--font-mono": "HostMono" },
+                    css: { fonts: "@font-face { font-family: HostSans; src: local(Arial); }" },
+                },
+            },
+            tools: { [PROFILE_FEED]: profileResult({ language: "en" }) },
+        });
+        mount(host);
+        await vi.waitFor(() => expect(probe()).toBe("en|fullscreen|demo:widget"));
+        // The host's font fills the fallback slot of the theme's font roles
+        // (adoptHostFontVariables), so the stack stays Geist first, then the
+        // host's font, then the system; the role names themselves are not
+        // overwritten.
+        expect(root.style.getPropertyValue("--host-font-sans")).toBe("HostSans, sans-serif");
+        expect(root.style.getPropertyValue("--host-font-mono")).toBe("HostMono");
+        expect(root.style.getPropertyValue("--font-sans")).toBe("");
+        expect(root.style.getPropertyValue("--font-mono")).toBe("");
+        expect(document.getElementById("__mcp-host-fonts")?.textContent).toContain("HostSans");
+        expect(root.style.height).toBe("100%");
+        document.getElementById("__mcp-host-fonts")?.remove();
+    });
+    it("follows a host display-mode change live", async () => {
+        const host = createFakeHost({
+            hostContext: { displayMode: "fullscreen", availableDisplayModes: ["inline", "fullscreen"] },
+            tools: { [PROFILE_FEED]: profileResult({ language: "en" }) },
+        });
+        mount(host);
+        await vi.waitFor(() => expect(probe()).toBe("en|fullscreen|demo:widget"));
+        host.notify("ui/notifications/host-context-changed", { displayMode: "inline" });
+        await vi.waitFor(() => expect(probe()).toBe("en|inline|demo:widget"));
+    });
+    it("still renders, in English and the OS theme, on a host that cannot call server tools", async () => {
+        // No `serverTools` capability: every tool call (the profile feed
+        // included) rejects inside the guest — the gate must degrade, not crash,
+        // and not wait out react-query's retries (the toolkit's client keeps the
+        // default 3, ~7 s of backoff): the first failure releases it.
+        // A dark OS, so the theme fallback is observable (light is the default).
+        vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({
+            matches: true,
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+        }));
+        const host = createFakeHost({ hostContext: {}, hostCapabilities: {} });
+        mount(host);
+        // Within 1 s — inside the gate's 1.5 s profile bound, so the bound cannot
+        // be what released it …
+        await vi.waitFor(() => expect(probe()).toBe("en|inline|demo:widget"), { timeout: 1_000 });
+        // … while the retries still run: the query is pending after one failure.
+        expect(queryClient.getQueryState(["shell:settings", {}])).toMatchObject({
+            status: "pending",
+            fetchFailureCount: 1,
+        });
+        expect(host.toolCalls()).toEqual([]);
+        expect(root.lang).toBe("en");
+        expect(root.classList.contains("dark")).toBe(true);
+    });
+});
+/** A module widget with its own heading, as `WidgetHeader` renders it. */
+const HeadedWidget = () => _jsx("h2", { children: "Widget heading" });
+const VIEW_WIDGETS = { "demo:headed": HeadedWidget };
+/** A `show_*` / `render-view` result: the server's view title over one widget. */
+const VIEW_RESULT = {
+    content: [{ type: "text", text: "Rendered the view." }],
+    structuredContent: {
+        title: "Server view title",
+        context: { keys: {}, stepIds: [], stepData: {}, errors: [] },
+        layout: { rows: [{ row: [{ widget: "demo:headed" }] }] },
+    },
+};
+/**
+ * Mount a view the way every composed-server bundle does (AppShellProviders +
+ * LocalizedAppView), deliver the tool's result over the real view runtime and
+ * return the headings it renders. `toolName` is what the host names in
+ * SEP-1865 `toolInfo`; the chain under test is toolInfo → ShellHost.toolName
+ * (ViewHostBridge) → viewTitleMode → the toolkit toolbar's title.
+ */
+async function viewHeadings(toolName) {
+    const host = createFakeHost({
+        hostContext: toolName
+            ? { toolInfo: { tool: { name: toolName, inputSchema: { type: "object" } } } }
+            : {},
+        tools: { [PROFILE_FEED]: profileResult({ language: "en" }) },
+    });
+    bootstrapView({
+        default: () => (_jsx(AppShellProviders, { widgets: VIEW_WIDGETS, children: _jsx(LocalizedAppView, { widgets: VIEW_WIDGETS }) })),
+    }, { transport: host.transport });
+    await vi.waitFor(() => expect(host.methods()).toContain("ui/notifications/initialized"));
+    host.notify("ui/notifications/tool-input", { arguments: {} });
+    host.notify("ui/notifications/tool-result", VIEW_RESULT);
+    await vi.waitFor(() => expect(document.body.textContent).toContain("Widget heading"));
+    return [...document.querySelectorAll("h1, h2, h3, h4, h5, h6")].map((h) => h.textContent);
+}
+describe("LocalizedAppView: one title per view (real mcp-use view runtime)", () => {
+    it("hides the toolbar title over a module view: the widget's heading is the one title", async () => {
+        expect(await viewHeadings("camunda7_show_process_list")).toEqual(["Widget heading"]);
+    });
+    it("keeps the toolbar title over a composed render-view, whose widgets carry none", async () => {
+        expect(await viewHeadings("render-view")).toEqual(["Server view title", "Widget heading"]);
+    });
+    it("keeps it where the host does not name the rendering tool", async () => {
+        expect(await viewHeadings(undefined)).toEqual(["Server view title", "Widget heading"]);
+    });
+});
+//# sourceMappingURL=app-shell-providers.test.js.map

package/dist/ui/app-shell-providers.test.js.map

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

package/dist/ui/ask-ai-button.d.ts

@@ -0,0 +1,56 @@
+import type { AskAiPrompt } from "./ask-ai-prompt.js";
+import { type LucideIcon } from "./icon.js";
+/**
+ * Placement tiers. All but `menuitem` render as the same secondary outline
+ * button (a hand-off is never the view's primary action: the deterministic
+ * next step, Retry or Resolve, is); `icon` drops the visible label for dense
+ * rows; `menuitem` is an entry of a row's action menu ({@link MENU_ITEM},
+ * `role="menuitem"`), whose card is its surface.
+ */
+export type AskAiVariant = "primary" | "subtle" | "icon" | "menuitem";
+export interface AskAiButtonProps {
+    /**
+     * The hand-off posted to the agent as the user's chat message (`askAi` →
+     * `sendFollowup`). Only {@link askAiPrompt} builds one: a short localized
+     * intent + ids, engine text fenced as untrusted data, and only the tools
+     * the deployment registers for the model. `null` — nothing in the task is
+     * available here (or not yet known) — renders no button at all.
+     */
+    prompt: AskAiPrompt | null;
+    /**
+     * The Lucide icon of the CONCRETE function the chat will do — `FileSearch`
+     * to explain an error, `ClipboardList` to draft a ticket, `GitCompare` to
+     * compare (CI: no sparkles, no generic "AI" symbol). Defaults to a neutral
+     * `MessageSquare` (it goes to the chat).
+     */
+    icon?: LucideIcon;
+    /**
+     * A verb phrase that says the work happens in the chat: "Im Chat
+     * erklären" / "Explain in chat", "Ticket im Chat entwerfen". Defaults to
+     * the locale's "Im Chat analysieren" / "Analyze in chat". For `icon` it
+     * moves to `aria-label`/`title`.
+     */
+    label?: string;
+    /**
+     * `primary` = the one surface-level entry of a view; `subtle` = per-row /
+     * per-section (the common case); `icon` = dense table rows (icon only,
+     * label → aria-label); `menuitem` = an entry of a row's action menu.
+     */
+    variant?: AskAiVariant;
+    /** Tooltip/aria override; defaults to `label`. */
+    title?: string;
+    disabled?: boolean;
+    /** Optional hook fired after the handoff is dispatched. */
+    onSent?: () => void;
+}
+/**
+ * The single "cross into chat" affordance for the whole cockpit and the ONLY
+ * owner of the {@link useHostActions} `askAi` call site (a structural test
+ * fails on any other) for analyze / explain / compare / draft / prepare-action
+ * handoffs. Renders the same everywhere: an outline button with the icon of
+ * the concrete function and a verb that names the chat. Deterministic
+ * navigation (`useNav`/`showWidget`) and mutations must NOT use this — they
+ * keep their own controls.
+ */
+export declare function AskAiButton({ prompt, icon, label, variant, title, disabled, onSent, }: AskAiButtonProps): import("react").JSX.Element | null;
+//# sourceMappingURL=ask-ai-button.d.ts.map

package/dist/ui/ask-ai-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-button.d.ts","sourceRoot":"","sources":["../../src/ui/ask-ai-button.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AAIjD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAErE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAC1B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,IAAoB,EACpB,KAAK,EACL,OAAkB,EAClB,KAAK,EACL,QAAQ,EACR,MAAM,GACP,EAAE,gBAAgB,sCA2ClB"}

package/dist/ui/ask-ai-button.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, useLocale } from "@miragon/mcp-toolkit-ui";
+import { MessageSquare } from "lucide-react";
+import { useHostActions } from "@miragon/mcp-toolkit-ui/app";
+import { Icon } from "./icon.js";
+import { kitLabels } from "./kit-labels.js";
+import { MENU_ITEM } from "./menu-item.js";
+/**
+ * The single "cross into chat" affordance for the whole cockpit and the ONLY
+ * owner of the {@link useHostActions} `askAi` call site (a structural test
+ * fails on any other) for analyze / explain / compare / draft / prepare-action
+ * handoffs. Renders the same everywhere: an outline button with the icon of
+ * the concrete function and a verb that names the chat. Deterministic
+ * navigation (`useNav`/`showWidget`) and mutations must NOT use this — they
+ * keep their own controls.
+ */
+export function AskAiButton({ prompt, icon = MessageSquare, label, variant = "subtle", title, disabled, onSent, }) {
+    const host = useHostActions();
+    const locale = useLocale();
+    if (prompt === null)
+        return null;
+    // The kit has no message catalog of its own, so the default verb follows the
+    // ambient locale — otherwise every label-less call site leaks English into a
+    // localized cockpit.
+    const effectiveLabel = label ?? kitLabels(locale).askAiDefault;
+    const send = () => {
+        host.askAi(prompt);
+        onSent?.();
+    };
+    if (variant === "menuitem") {
+        return (_jsxs("button", { type: "button", role: "menuitem", tabIndex: -1, disabled: disabled, title: title, className: MENU_ITEM, onClick: send, children: [_jsx(Icon, { icon: icon, dense: true }), effectiveLabel] }));
+    }
+    const isIcon = variant === "icon";
+    return (_jsxs(Button, { type: "button", variant: "outline", size: isIcon ? "icon-sm" : "sm", disabled: disabled, "aria-label": isIcon ? (title ?? effectiveLabel) : undefined, title: isIcon ? (title ?? effectiveLabel) : title, onClick: send, children: [_jsx(Icon, { icon: icon, dense: isIcon }), !isIcon && effectiveLabel] }));
+}
+//# sourceMappingURL=ask-ai-button.js.map

package/dist/ui/ask-ai-button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-button.js","sourceRoot":"","sources":["../../src/ui/ask-ai-button.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAE5D,OAAO,EAAE,IAAI,EAAmB,MAAM,WAAW,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AA+C1C;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,MAAM,EACN,IAAI,GAAG,aAAa,EACpB,KAAK,EACL,OAAO,GAAG,QAAQ,EAClB,KAAK,EACL,QAAQ,EACR,MAAM,GACW;IACjB,MAAM,IAAI,GAAG,cAAc,EAAE,CAAA;IAC7B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAChC,6EAA6E;IAC7E,6EAA6E;IAC7E,qBAAqB;IACrB,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,YAAY,CAAA;IAC9D,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAClB,MAAM,EAAE,EAAE,CAAA;IACZ,CAAC,CAAA;IACD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,OAAO,CACL,kBACE,IAAI,EAAC,QAAQ,EACb,IAAI,EAAC,UAAU,EACf,QAAQ,EAAE,CAAC,CAAC,EACZ,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,IAAI,aAEb,KAAC,IAAI,IAAC,IAAI,EAAE,IAAI,EAAE,KAAK,SAAG,EACzB,cAAc,IACR,CACV,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,KAAK,MAAM,CAAA;IACjC,OAAO,CACL,MAAC,MAAM,IACL,IAAI,EAAC,QAAQ,EACb,OAAO,EAAC,SAAS,EACjB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAC/B,QAAQ,EAAE,QAAQ,gBACN,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,EAC1D,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,EACjD,OAAO,EAAE,IAAI,aAEb,KAAC,IAAI,IAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAI,EAClC,CAAC,MAAM,IAAI,cAAc,IACnB,CACV,CAAA;AACH,CAAC"}

package/dist/ui/ask-ai-button.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ask-ai-button.test.d.ts.map

package/dist/ui/ask-ai-button.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-button.test.d.ts","sourceRoot":"","sources":["../../src/ui/ask-ai-button.test.tsx"],"names":[],"mappings":""}

package/dist/ui/ask-ai-button.test.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { LocaleProvider } from "@miragon/mcp-toolkit-ui";
+import { HostBridgeProvider } from "@miragon/mcp-toolkit-ui/app";
+import { FileSearch } from "lucide-react";
+import { AskAiButton } from "./ask-ai-button.js";
+import { askAiPrompt } from "./ask-ai-prompt.js";
+afterEach(cleanup);
+function renderButton(prompt, locale = "en", props = {}) {
+    const sendFollowup = vi.fn();
+    const bridge = {
+        callTool: vi.fn(),
+        sendFollowup,
+        openExternal: vi.fn(),
+        getWidgetData: () => null,
+    };
+    const view = render(_jsx(HostBridgeProvider, { bridge: bridge, children: _jsx(LocaleProvider, { locale: locale, children: _jsx(AskAiButton, { prompt: prompt, ...props }) }) }));
+    return { ...view, sendFollowup };
+}
+const prompt = (locale = "en") => askAiPrompt({
+    intent: "Explain this.",
+    locale,
+    ids: { incidentId: "i1" },
+    surface: { has: () => true },
+});
+describe("AskAiButton", () => {
+    it("posts the built hand-off unchanged as the follow-up", () => {
+        const { sendFollowup } = renderButton(prompt());
+        fireEvent.click(screen.getByRole("button", { name: "Analyze in chat" }));
+        expect(sendFollowup).toHaveBeenCalledWith('Explain this.\nIds: incidentId="i1"');
+    });
+    it("renders nothing for a hand-off with nothing available in this deployment", () => {
+        const { container } = renderButton(null);
+        expect(container.querySelector("button")).toBeNull();
+    });
+    it("defaults its verb to the locale, a verb that names the chat", () => {
+        renderButton(prompt("de"), "de");
+        expect(screen.getByRole("button", { name: "Im Chat analysieren" })).toBeTruthy();
+    });
+    it("draws a decorative Lucide icon (default: the chat bubble), never the ✦ sparkle", () => {
+        const { container } = renderButton(prompt());
+        const svg = container.querySelector("svg");
+        expect(svg.getAttribute("class")).toContain("lucide-message-square");
+        expect(svg.getAttribute("aria-hidden")).toBe("true");
+        expect(container.textContent).not.toContain("✦");
+    });
+    it("shows the icon of the concrete function and the caller's verb", () => {
+        const { container } = renderButton(prompt(), "en", {
+            icon: FileSearch,
+            label: "Explain in chat",
+        });
+        expect(screen.getByRole("button", { name: "Explain in chat" })).toBeTruthy();
+        expect(container.querySelector("svg").getAttribute("class")).toContain("lucide-file-search");
+    });
+    it("the icon variant moves the label into the accessible name and the tooltip", () => {
+        const { container } = renderButton(prompt(), "en", {
+            variant: "icon",
+            label: "Draft a ticket in chat",
+        });
+        const button = screen.getByRole("button", { name: "Draft a ticket in chat" });
+        expect(button.getAttribute("title")).toBe("Draft a ticket in chat");
+        expect(button.textContent).toBe("");
+        // A dense icon bar: the CI's narrower stroke, set on the icon itself.
+        expect(container.querySelector("svg").getAttribute("stroke-width")).toBe("2");
+    });
+    it("the menuitem variant is a plain entry of a menu that posts the same hand-off", () => {
+        const onSent = vi.fn();
+        const { container, sendFollowup } = renderButton(prompt(), "en", {
+            variant: "menuitem",
+            icon: FileSearch,
+            label: "Explain error in chat",
+            onSent,
+        });
+        const item = screen.getByRole("menuitem", { name: "Explain error in chat" });
+        expect(item.getAttribute("tabindex")).toBe("-1");
+        // No button chrome: the menu's card is its surface (CI §8): an entry on
+        // the small radius in the dense step, the blue-soft hover, half opacity
+        // when off, its focus ring drawn inside.
+        expect(item.getAttribute("data-slot")).toBeNull();
+        const classes = item.className.split(/\s+/);
+        for (const role of [
+            "rounded-sm",
+            "text-dense",
+            "hover:bg-accent",
+            "disabled:opacity-50",
+            "focus-visible:ring-inset",
+        ]) {
+            expect(classes, role).toContain(role);
+        }
+        expect(container.querySelector("svg").getAttribute("class")).toContain("lucide-file-search");
+        fireEvent.click(item);
+        expect(sendFollowup).toHaveBeenCalledWith('Explain this.\nIds: incidentId="i1"');
+        expect(onSent).toHaveBeenCalledTimes(1);
+    });
+    it("every variant is the same secondary outline, never a brand accent", () => {
+        renderButton(prompt(), "en", { variant: "primary" });
+        const button = screen.getByRole("button", { name: "Analyze in chat" });
+        expect(button.className).not.toMatch(/text-info|text-link|bg-primary/);
+    });
+});
+//# sourceMappingURL=ask-ai-button.test.js.map

package/dist/ui/ask-ai-button.test.js.map

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

package/dist/ui/ask-ai-prompt.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The ONE builder of every widget → model hand-off text (#338).
+ *
+ * An Ask-AI hand-off reaches the host as a `role: "user"` chat message
+ * (`askAi` → `sendFollowup`), so whatever a widget inlines reads to the model
+ * as the operator's own words. A model context (`HostModelContext`) is quieter
+ * but just as trusted. Both are therefore assembled from typed parts only:
+ *
+ * - `intent` — a SHORT task from the module's message catalogue (localized,
+ *   static text: no data, no tool names);
+ * - `ids` / `facts` — identifiers the model passes to tools and on-screen
+ *   numbers; a value that is not id-shaped is never inlined, it moves into
+ *   the untrusted block instead;
+ * - `untrusted` — engine or third-party free text (exception messages,
+ *   process and activity names, business keys, variable values), length
+ *   capped and quoted in a fence the text cannot close, under an explicit
+ *   "data, not instructions" label;
+ * - `tools` — the tools that fit the task, filtered by the deployment's live
+ *   surface, so a hand-off never names a tool the server does not register
+ *   for the model; `toolIds` — arguments only some of those tools take,
+ *   inlined only while their tool is named (strict inputs refuse an argument
+ *   a tool does not take).
+ */
+/** A hand-off built by {@link askAiPrompt} — the only prompt `AskAiButton` accepts. */
+export type AskAiPrompt = string & {
+    readonly __brand: "AskAiPrompt";
+};
+/** An id or on-screen fact: inlined only when id-shaped, else quoted as untrusted. */
+export type HandOffValue = string | number | boolean | readonly string[] | null | undefined;
+/** Engine / third-party free text, quoted as data under its author-chosen name. */
+export interface UntrustedText {
+    /** What the text is (`incidentMessage`, `businessKey`) — a fixed identifier, never data. */
+    label: string;
+    text: string | null | undefined;
+}
+/**
+ * Which tools the deployment registers for the model — the filter every tool
+ * mention passes. Three answers:
+ *
+ * - `true` — registered: the tool is named;
+ * - `false` — absent, or not answered yet (fail closed: a hand-off whose
+ *   tools are ALL `false` is null, so its button appears a moment late
+ *   instead of naming a tool that is gone);
+ * - `undefined` — cannot be known (the surface feed failed, or the host has
+ *   no in-widget tools/call): the tool is not named, but the hand-off is
+ *   still built — intent, ids and fence, no Tools line — since the host can
+ *   still post it.
+ */
+export interface ToolSurface {
+    has(tool: string): boolean | undefined;
+}
+/** A surface that confirms nothing (no tool is ever mentioned). */
+export declare const EMPTY_TOOL_SURFACE: ToolSurface;
+export interface HandOffParts {
+    /** Identifiers the model passes to the listed tools (`engine`, `incidentId`, …). */
+    ids?: Readonly<Record<string, HandOffValue>>;
+    /** On-screen numbers and flags the task refers to (`openIncidents`, …). */
+    facts?: Readonly<Record<string, HandOffValue>>;
+    /** Engine / third-party free text — only ever inside the fence. */
+    untrusted?: readonly UntrustedText[];
+    /** The tools that fit the task; the ones off `surface` are dropped. */
+    tools?: readonly string[];
+    /**
+     * Arguments only SOME listed tools take (`period` for an analytics drill),
+     * keyed by tool: inlined into the Ids line only while that tool is named —
+     * a dropped tool must not leave behind an argument the remaining tools'
+     * strict inputs refuse.
+     */
+    toolIds?: Readonly<Record<string, Readonly<Record<string, HandOffValue>>>>;
+    surface: ToolSurface;
+}
+export interface AskAiPromptSpec extends HandOffParts {
+    /** The short task, from the module's catalogue (`t("askAi.…")`) — static text. */
+    intent: string;
+    /** The active locale — decides the language of the fixed labels. */
+    locale: string;
+}
+export interface ModelContextSpec extends HandOffParts {
+    /** What the operator is looking at — static, model-facing text. */
+    summary: string;
+}
+/** Max characters of ONE untrusted text; longer text keeps its head. */
+export declare const MAX_UNTRUSTED_CHARS = 600;
+interface Labels {
+    ids: string;
+    facts: string;
+    tools: string;
+    untrusted: string;
+}
+/** The kit has no catalogue of its own; these few labels follow the locale like AskAiButton's verb. */
+export declare const ASK_AI_PROMPT_LABELS: Readonly<Record<"en" | "de", Labels>>;
+/**
+ * A fenced block the text cannot close: the fence is one backtick longer than
+ * the longest backtick run inside (at least three). A closing fence must be at
+ * least as long as the opening one, so no line of the text can end the block —
+ * whatever it says stays quoted data.
+ */
+export declare function fenceUntrusted(text: string): string;
+/**
+ * Build an Ask-AI hand-off. Returns `null` — and `AskAiButton` renders
+ * nothing — when the task named tools and the surface answers `false` for
+ * EVERY one: there is nothing the model could do with it in this deployment
+ * (or the surface has not answered yet; the button then appears once it
+ * has). A tool the surface cannot know (`undefined`) keeps the hand-off,
+ * built without naming that tool.
+ */
+export declare function askAiPrompt(spec: AskAiPromptSpec): AskAiPrompt | null;
+/**
+ * Build a model-context text (`HostModelContext` content) from the same parts.
+ * Never null: the context describes the view whether or not a tool fits.
+ * English — it addresses the model, not the user.
+ */
+export declare function modelContextText(spec: ModelContextSpec): string;
+export {};
+//# sourceMappingURL=ask-ai-prompt.d.ts.map

package/dist/ui/ask-ai-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-prompt.d.ts","sourceRoot":"","sources":["../../src/ui/ask-ai-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAA;AAEtE,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAA;AAE3F,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACvC;AAED,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,EAAE,WAAkC,CAAA;AAEnE,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAA;IAC5C,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAA;IAC9C,mEAAmE;IACnE,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IACpC,uEAAuE;IACvE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1E,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAiBtC,UAAU,MAAM;IACd,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAetE,CAAA;AAsCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD;AAiDD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,CAWrE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE/D"}