@miragon/pulse-analytics-connector 0.0.0-bootstrap.0 → 0.21.0

package/src/widgets/names.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest"
+import { translator } from "../messages/index.js"
+import { activityTypeKey, activityTypeLabel } from "./names.js"
+
+describe("activity types in words", () => {
+  it.each([
+    ["serviceTask", "aActivityType.serviceTask"],
+    ["callActivity", "aActivityType.callActivity"],
+    ["exclusiveGateway", "aActivityType.exclusiveGateway"],
+    ["startEvent", "aActivityType.startEvent"],
+    ["startTimerEvent", "aActivityType.startEvent"],
+    ["messageStartEvent", "aActivityType.startEvent"],
+    ["noneEndEvent", "aActivityType.endEvent"],
+    ["errorEndEvent", "aActivityType.endEvent"],
+    ["endEvent", "aActivityType.endEvent"],
+    ["boundaryError", "aActivityType.boundaryEvent"],
+    ["boundaryTimer", "aActivityType.boundaryEvent"],
+    ["intermediateTimer", "aActivityType.intermediateEvent"],
+    ["intermediateMessageThrowEvent", "aActivityType.intermediateEvent"],
+  ])("%s reads as %s", (type, key) => {
+    expect(activityTypeKey(type)).toBe(key)
+  })
+
+  it("leaves a type it does not know as the engine wrote it", () => {
+    expect(activityTypeKey("multiInstanceBody")).toBeNull()
+    expect(activityTypeKey("")).toBeNull()
+    const t = (key: string) => translator("de", key)
+    expect(activityTypeLabel(t, "multiInstanceBody")).toBe("multiInstanceBody")
+    expect(activityTypeLabel(t, "userTask")).toBe("User-Task")
+    expect(activityTypeLabel((key) => translator("en", key), "noneEndEvent")).toBe("End event")
+  })
+})

package/src/widgets/names.ts

@@ -0,0 +1,39 @@
+import type { T } from "../messages/use-t.js"
+
+/**
+ * The engine's activity types (`activity_type`, the engine's own names such
+ * as `noneEndEvent` or `boundaryError`) folded into the BPMN element a reader
+ * knows. A type it does not know stays as the engine wrote it.
+ */
+const EXACT_TYPES = new Set([
+  "serviceTask",
+  "userTask",
+  "scriptTask",
+  "sendTask",
+  "receiveTask",
+  "businessRuleTask",
+  "manualTask",
+  "task",
+  "callActivity",
+  "subProcess",
+  "exclusiveGateway",
+  "parallelGateway",
+  "inclusiveGateway",
+  "eventBasedGateway",
+])
+
+/** The catalog key of an activity type's words, or null for a type without one. */
+export function activityTypeKey(type: string): string | null {
+  if (EXACT_TYPES.has(type)) return `aActivityType.${type}`
+  if (/^boundary/.test(type)) return "aActivityType.boundaryEvent"
+  if (/^intermediate/.test(type)) return "aActivityType.intermediateEvent"
+  if (/^start|StartEvent$/.test(type)) return "aActivityType.startEvent"
+  if (/^endEvent$|EndEvent$/.test(type)) return "aActivityType.endEvent"
+  return null
+}
+
+/** An activity type in the view's words ("Service-Task", "Endereignis"), or as the engine wrote it. */
+export function activityTypeLabel(t: T, type: string): string {
+  const key = activityTypeKey(type)
+  return key ? t(key) : type
+}

package/src/widgets/query-gate.test.tsx

@@ -0,0 +1,57 @@
+// @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 { QueryGate } from "./query-gate.js"
+
+afterEach(cleanup)
+
+/**
+ * The split dashboard widgets' self-fetch gate: a failed query is never a
+ * dead end (U1). The kit words a Prometheus failure itself; the gate's
+ * own title heads only one it cannot classify.
+ */
+describe("QueryGate", () => {
+  function renderGate(error: Error, refetch = vi.fn()) {
+    render(
+      <LocaleProvider locale="de">
+        <QueryGate
+          initialData={null}
+          query={{ data: undefined, isError: true, error, refetch }}
+          skeleton={<div />}
+        >
+          {() => <p>data</p>}
+        </QueryGate>
+      </LocaleProvider>,
+    )
+    return refetch
+  }
+
+  it("says Prometheus is unreachable and what to do, and retries the query", () => {
+    const refetch = renderGate(new Error("Prometheus unreachable (ECONNREFUSED)"))
+    expect(screen.getByRole("heading", { name: "Prometheus ist nicht erreichbar" })).toBeTruthy()
+    expect(screen.getByText("Prüf, ob Prometheus läuft und erreichbar ist.")).toBeTruthy()
+    fireEvent.click(screen.getByRole("button", { name: "Erneut versuchen" }))
+    expect(refetch).toHaveBeenCalledTimes(1)
+  })
+
+  it("heads a failure the kit cannot classify with the module's own words", () => {
+    renderGate(new Error("odd"))
+    expect(
+      screen.getByRole("heading", { name: "Die Kennzahlen konnten nicht geladen werden." }),
+    ).toBeTruthy()
+  })
+
+  it("renders its children once data exists", () => {
+    render(
+      <QueryGate
+        initialData={{ n: 1 }}
+        query={{ data: undefined, isError: false, refetch: vi.fn() }}
+        skeleton={<div />}
+      >
+        {(data) => <p>n = {data.n}</p>}
+      </QueryGate>,
+    )
+    expect(screen.getByText("n = 1")).toBeTruthy()
+  })
+})

package/src/widgets/query-gate.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react"
+import { QueryFallback, WidgetShell } from "@miragon/pulse-widget-shell/widgets"
+import { useT } from "../messages/use-t.js"
+
+/** The slice of a self-fetch query result the gate needs (tanstack-shaped). */
+interface GateQuery<T> {
+  data: T | null | undefined
+  isError: boolean
+  error?: unknown
+  /** Re-runs the query: the error state's retry (a failed load is never a dead end). */
+  refetch: () => unknown
+}
+
+/**
+ * Shared self-fetch gate for the split dashboard widgets: resolves pipeline
+ * data against the fallback query and renders the loading/error shell until
+ * data exists. `children` is a render prop so the happy path only runs with
+ * resolved data; `header` keeps a widget's static header visible while loading.
+ */
+export function QueryGate<T>({
+  initialData,
+  query,
+  skeleton,
+  header,
+  children,
+}: {
+  initialData: T | null
+  query: GateQuery<T>
+  skeleton: ReactNode
+  header?: ReactNode
+  children: (data: T) => ReactNode
+}) {
+  const t = useT()
+  const data = initialData ?? query.data ?? null
+  if (!data) {
+    return (
+      <WidgetShell>
+        {header}
+        <QueryFallback
+          isError={query.isError}
+          error={query.error}
+          errorTitle={t("aCommon.loadError")}
+          onRetry={() => void query.refetch()}
+          skeleton={skeleton}
+        />
+      </WidgetShell>
+    )
+  }
+  return <>{children(data)}</>
+}

package/src/widgets/settings-section.test.tsx

@@ -0,0 +1,174 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeAll, describe, expect, it } from "vitest"
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"
+import { LocaleProvider, queryClient, ToastProvider } from "@miragon/mcp-toolkit-ui"
+import { WidgetFixtureHost } from "@miragon/mcp-toolkit-ui/app"
+import { ANALYTICS_SAVE_SETTINGS, ANALYTICS_SETTINGS_DATA } from "../tool-names.js"
+import { AnalyticsSettingsWidget, parseMinBucketSize } from "./settings-section.js"
+
+/**
+ * The settings section's own error state: when its feed fails it says the
+ * SETTINGS could not be loaded, not the figures a data view loads.
+ */
+
+beforeAll(() => {
+  // One attempt: the error state is what this suite reads, not the retries.
+  queryClient.setQueryDefaults(["analytics:settings"], { retry: false })
+})
+afterEach(() => {
+  cleanup()
+  queryClient.clear()
+})
+
+/** The section as the settings page mounts it: no pipeline data, it fetches its feed. */
+const Section = () => <AnalyticsSettingsWidget />
+
+function renderIn(language: "de" | "en") {
+  return render(
+    <LocaleProvider locale={language}>
+      <WidgetFixtureHost
+        widget={Section}
+        tools={{
+          [ANALYTICS_SETTINGS_DATA]: () => {
+            throw new Error("profile store unavailable")
+          },
+        }}
+      />
+    </LocaleProvider>,
+  )
+}
+
+describe("the analytics settings section when its feed fails", () => {
+  // The kit's error state (U1): the section's own title for a failure the
+  // kit cannot classify, what you can do, the raw cause under Details, Retry.
+  it("says the settings could not be loaded, and what you can do (de)", async () => {
+    renderIn("de")
+    expect(
+      await screen.findByRole("heading", {
+        name: "Die Einstellungen konnten nicht geladen werden.",
+      }),
+    ).toBeTruthy()
+    expect(
+      screen.getByText("Versuch es noch mal. Klappt es wieder nicht, frag im Chat nach."),
+    ).toBeTruthy()
+    expect(screen.getByText("profile store unavailable").closest("details")).toBeTruthy()
+    expect(screen.getByRole("button", { name: "Erneut versuchen" })).toBeTruthy()
+    expect(screen.queryByText(/Kennzahlen/)).toBeNull()
+  })
+
+  it("says the same in English", async () => {
+    renderIn("en")
+    expect(
+      await screen.findByRole("heading", { name: "Could not load the settings." }),
+    ).toBeTruthy()
+    expect(screen.getByText("Try again. If it fails again, ask in the chat.")).toBeTruthy()
+    expect(screen.getByRole("button", { name: "Try again" })).toBeTruthy()
+    expect(screen.queryByText(/figures/)).toBeNull()
+  })
+})
+
+describe("the analytics settings section when it saves (U9: a save is never silent)", () => {
+  const VIEW = { settings: { defaultPeriod: "7d", minBucketSize: 5 }, canSave: true }
+
+  function renderSaving(save: () => unknown) {
+    return render(
+      <LocaleProvider locale="en">
+        <ToastProvider>
+          <WidgetFixtureHost
+            widget={Section}
+            tools={{ [ANALYTICS_SETTINGS_DATA]: () => VIEW, [ANALYTICS_SAVE_SETTINGS]: save }}
+          />
+        </ToastProvider>
+      </LocaleProvider>,
+    )
+  }
+
+  const toast = () => document.querySelector(`[data-slot="toast"]`)
+
+  it("confirms the save in a toast — the polite live region a screen reader hears", async () => {
+    renderSaving(() => ({ success: true }))
+    fireEvent.click(await screen.findByRole("button", { name: "Save" }))
+    await waitFor(() => expect(toast()?.textContent).toContain("Settings saved"))
+    expect(toast()?.getAttribute("data-tone")).toBe("success")
+    expect(toast()?.closest(`[aria-live="polite"]`)).toBeTruthy()
+  })
+
+  it("says why a save failed, in a danger toast", async () => {
+    renderSaving(() => {
+      throw new Error("Tool analytics_save_settings not found")
+    })
+    fireEvent.click(await screen.findByRole("button", { name: "Save" }))
+    await waitFor(() => expect(toast()?.textContent).toContain("Couldn't save the settings"))
+    expect(toast()?.getAttribute("data-tone")).toBe("danger")
+    expect(toast()?.textContent).toContain("This data isn't available on this server.")
+  })
+
+  // U25: an entry that is no valid size is said to be wrong, never turned into 1.
+  it.each(["abc", "0", "2.5", " ", "-3"])("refuses %j inline and saves nothing", async (entry) => {
+    const saves: unknown[] = []
+    renderSaving((args?: unknown) => {
+      saves.push(args)
+      return { success: true }
+    })
+    const field = await screen.findByRole("textbox", { name: "Minimum size for comparisons" })
+    fireEvent.change(field, { target: { value: entry } })
+    expect(field.getAttribute("aria-invalid")).toBe("true")
+    const error = screen.getByText("Enter a whole number of 1 or more.")
+    expect(field.getAttribute("aria-describedby")).toContain(error.closest("[id]")!.id)
+    fireEvent.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(document.activeElement).toBe(field))
+    expect(saves).toEqual([])
+    expect(toast()).toBeNull()
+  })
+
+  it("saves a valid size as the number you typed", async () => {
+    const saves: unknown[] = []
+    renderSaving((args?: unknown) => {
+      saves.push(args)
+      return { success: true }
+    })
+    const field = await screen.findByRole("textbox", { name: "Minimum size for comparisons" })
+    fireEvent.change(field, { target: { value: " 25 " } })
+    expect(field.getAttribute("aria-invalid")).toBeNull()
+    fireEvent.click(screen.getByRole("button", { name: "Save" }))
+    await waitFor(() => expect(saves).toEqual([{ defaultPeriod: "7d", minBucketSize: 25 }]))
+  })
+})
+
+describe("the analytics settings section without the right to save (U25)", () => {
+  const READ_ONLY = { settings: { defaultPeriod: "7d", minBucketSize: 5 }, canSave: false }
+
+  it("says why first, above the fields it cannot change, and offers no Save (de)", async () => {
+    render(
+      <LocaleProvider locale="de">
+        <WidgetFixtureHost
+          widget={Section}
+          tools={{ [ANALYTICS_SETTINGS_DATA]: () => READ_ONLY }}
+        />
+      </LocaleProvider>,
+    )
+    const notice = await screen.findByText("Nur lesen")
+    expect(
+      screen.getByText(
+        "Diese Verbindung kann keine Einstellungen speichern. Ändern kannst du sie, wenn du dich über eine Verbindung mit dem Analytics-Toolset standard anmeldest.",
+      ),
+    ).toBeTruthy()
+    const field = screen.getByRole("textbox", { name: "Mindestgröße für Vergleiche" })
+    expect(field.hasAttribute("disabled")).toBe(true)
+    // The reason comes before the fields in reading order.
+    expect(notice.compareDocumentPosition(field) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+    expect(screen.queryByRole("button", { name: "Speichern" })).toBeNull()
+    // A notice in the first paint, not an announcement.
+    expect(screen.queryByRole("alert")).toBeNull()
+  })
+})
+
+describe("parseMinBucketSize", () => {
+  it("takes a whole number of 1 or more, nothing else", () => {
+    expect(parseMinBucketSize("10")).toBe(10)
+    expect(parseMinBucketSize(" 3 ")).toBe(3)
+    for (const raw of ["", "0", "-1", "1.5", "1e3", "abc", "99999999999999999999"]) {
+      expect(parseMinBucketSize(raw), raw).toBeNull()
+    }
+  })
+})

package/src/widgets/settings-section.tsx

@@ -0,0 +1,244 @@
+import { useRef, useState } from "react"
+import {
+  Alert,
+  AlertDescription,
+  Button,
+  ErrorState,
+  Skeleton,
+  useToolMutation,
+  useToolQuery,
+} from "@miragon/mcp-toolkit-ui"
+import { HostModelContext } from "@miragon/mcp-toolkit-ui/app"
+import { Lock } from "lucide-react"
+import {
+  NativeSelect,
+  QueryFallback,
+  SettingsCard,
+  SettingsField,
+  SettingsInput,
+  WidgetShell,
+  formatPeriod,
+  modelContextText,
+  useActionFeedback,
+  useResetOnChange,
+} from "@miragon/pulse-widget-shell/widgets"
+// The leaf, not the barrel: the barrel's value graph carries every tool's zod
+// input schema, which a widget never needs (#344 K50).
+import { PERIODS, type Period } from "@miragon/pulse-analytics-client/prometheus"
+import { ANALYTICS_SAVE_SETTINGS, ANALYTICS_SETTINGS_DATA } from "../tool-names.js"
+import { useT } from "../messages/use-t.js"
+import { describeAnalyticsSettings } from "./model-descriptions.js"
+
+/**
+ * Wire shape of the `analytics_settings_data` feed / `analytics_show_settings`
+ * data (see `settings-tools.ts`). Declared structurally here so the widget
+ * bundle stays free of server-side imports.
+ */
+export interface AnalyticsSettingsViewData {
+  settings: { defaultPeriod: Period; minBucketSize: number }
+  canSave: boolean
+}
+
+/**
+ * The analytics module's settings section — one card the settings page
+ * composes next to the camunda7 profile panel. Self-fetches its app-only feed;
+ * when the feed TOOL is missing (analytics module inactive) the section hides
+ * itself, mirroring the tier-2 graceful degradation of
+ * `process-incidents/flow.tsx`. Any other failure (profile store outage,
+ * network) stays visible as an error state instead of silently vanishing.
+ */
+export function AnalyticsSettingsWidget({
+  data: initialData = null,
+}: {
+  data?: AnalyticsSettingsViewData | null
+}) {
+  const t = useT()
+  const query = useToolQuery<AnalyticsSettingsViewData>(
+    ["analytics:settings"],
+    ANALYTICS_SETTINGS_DATA,
+    {},
+    { enabled: !initialData },
+  )
+  const view = initialData ?? query.data ?? null
+
+  if (!view) {
+    if (query.isError) {
+      const message = query.error instanceof Error ? query.error.message : String(query.error)
+      // The unknown-tool rejection = module inactive → hide the section.
+      if (message.includes(ANALYTICS_SETTINGS_DATA) && /not found/i.test(message)) return null
+    }
+    return (
+      <WidgetShell>
+        <QueryFallback
+          isError={query.isError}
+          error={query.error}
+          errorTitle={t("aSettings.loadError")}
+          onRetry={() => void query.refetch()}
+          skeleton={<Skeleton className="h-24 w-full rounded-md" />}
+        />
+      </WidgetShell>
+    )
+  }
+
+  return (
+    <WidgetShell>
+      <SettingsPanel view={view} />
+    </WidgetShell>
+  )
+}
+
+/** Raw form state — free typing, checked as you type and once more on save. */
+interface FormState {
+  defaultPeriod: Period
+  minBucketSize: string
+}
+
+/**
+ * The minimum size as the save tool takes it — a whole number of 1 or more —
+ * or null for anything else ("abc", "0", "2.5", ""). Never clamped: an entry
+ * that is not a valid size is said to be wrong, not silently turned into 1.
+ */
+export function parseMinBucketSize(raw: string): number | null {
+  const text = raw.trim()
+  if (!/^\d+$/.test(text)) return null
+  const value = Number(text)
+  return Number.isSafeInteger(value) && value >= 1 ? value : null
+}
+
+/**
+ * Why the section cannot save, above everything else (U25): the reader meets
+ * the reason before the fields it disables, and the way to change them.
+ */
+function ReadOnlyNotice() {
+  const t = useT()
+  return (
+    <ErrorState
+      variant="inline"
+      tone="info"
+      role="none"
+      icon={Lock}
+      title={t("aSettings.readOnlyTitle")}
+      description={t("aSettings.readOnly")}
+    />
+  )
+}
+
+function SettingsPanel({ view }: { view: AnalyticsSettingsViewData }) {
+  const t = useT()
+  // invalidateKeys: after a save the feed refetches, so a remounted section
+  // seeds from the saved server truth instead of the stale cache entry.
+  const save = useToolMutation(ANALYTICS_SAVE_SETTINGS, {
+    invalidateKeys: [["analytics:settings"]],
+  })
+  const [form, setForm] = useState<FormState>({
+    defaultPeriod: view.settings.defaultPeriod,
+    minBucketSize: String(view.settings.minBucketSize),
+  })
+  const bucketRef = useRef<HTMLInputElement>(null)
+  // The save confirms in a toast (the toolkit's polite live region), a
+  // failure says why there too — and stays in the panel next to the entries.
+  const feedback = useActionFeedback()
+  const minBucketSize = parseMinBucketSize(form.minBucketSize)
+
+  // Re-sync the baseline when server truth changes (feed refetch after save,
+  // refreshCockpitData from the camunda7 panel, another session's write) —
+  // mirrors user-profile.tsx; the feed carries no updatedAt, so the values
+  // themselves are the stamp.
+  const settingsStamp = `${view.settings.defaultPeriod}|${view.settings.minBucketSize}`
+  useResetOnChange(settingsStamp, () =>
+    setForm({
+      defaultPeriod: view.settings.defaultPeriod,
+      minBucketSize: String(view.settings.minBucketSize),
+    }),
+  )
+
+  function handleSave() {
+    // An entry that is no valid size is never saved, and never corrected
+    // behind your back: the field says what is wrong, the focus goes there.
+    if (minBucketSize === null) {
+      bucketRef.current?.focus()
+      return
+    }
+    save.mutate(
+      { defaultPeriod: form.defaultPeriod, minBucketSize },
+      {
+        onSuccess: () => feedback.succeeded(t("aSettings.savedToast")),
+        onError: (error) => feedback.failed(t("aSettings.saveFailedToast"), error),
+      },
+    )
+  }
+
+  return (
+    /* Inline (not via adaptDataWidget): the cockpit settings tab renders this
+       widget without pipeline data, and only the mounted component knows the
+       self-fetched view. HostModelContext renders its children unchanged. */
+    <HostModelContext content={modelContextText(describeAnalyticsSettings(view))}>
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div>
+            <h2 className="text-section">{t("aSettings.heading")}</h2>
+            <p className="text-muted-foreground text-small mt-1">{t("aSettings.subtitle")}</p>
+          </div>
+          {view.canSave && (
+            <Button size="sm" onClick={handleSave} disabled={save.isPending}>
+              {save.isPending ? t("aSettings.saving") : t("aSettings.save")}
+            </Button>
+          )}
+        </div>
+
+        {!view.canSave && <ReadOnlyNotice />}
+
+        {save.isError && (
+          <Alert variant="danger">
+            <AlertDescription>
+              {save.error?.message
+                ? t("aSettings.saveFailed", { reason: save.error.message })
+                : t("aSettings.saveError")}
+            </AlertDescription>
+          </Alert>
+        )}
+      </div>
+
+      <div className="mt-4 grid grid-cols-1 gap-4 lg:grid-cols-2">
+        <SettingsCard title={t("aSettings.section")}>
+          <SettingsField label={t("aSettings.period")} help={t("aSettings.period.help")}>
+            <NativeSelect
+              value={form.defaultPeriod}
+              disabled={!view.canSave}
+              onChange={(e) =>
+                setForm((f) => ({
+                  ...f,
+                  defaultPeriod: (PERIODS as readonly string[]).includes(e.target.value)
+                    ? (e.target.value as Period)
+                    : f.defaultPeriod,
+                }))
+              }
+            >
+              {PERIODS.map((p) => (
+                <option key={p} value={p}>
+                  {formatPeriod(p)}
+                </option>
+              ))}
+            </NativeSelect>
+          </SettingsField>
+          <SettingsField
+            label={t("aSettings.minBucket")}
+            help={t("aSettings.minBucket.help")}
+            error={minBucketSize === null ? t("aSettings.minBucket.invalid") : undefined}
+          >
+            {/* Text, not `type="number"`: a browser empties a number field on a
+                letter, and the entry you typed must stay to be corrected. */}
+            <SettingsInput
+              ref={bucketRef}
+              type="text"
+              inputMode="numeric"
+              disabled={!view.canSave}
+              value={form.minBucketSize}
+              onChange={(e) => setForm((f) => ({ ...f, minBucketSize: e.target.value }))}
+            />
+          </SettingsField>
+        </SettingsCard>
+      </div>
+    </HostModelContext>
+  )
+}

package/src/widgets/version-compare.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest"
+import type { VersionCompareKpi, VersionCompareResult } from "@miragon/pulse-analytics-client"
+import { versionCompareHandOff } from "./version-compare.js"
+import { ANALYTICS_ONLY_SURFACE, bindHandOff } from "./hand-off.js"
+
+const versionKpi = (version: number, incidentRatePct: number): VersionCompareKpi => ({
+  version,
+  bucket: version === 1 ? "versionA" : "versionB",
+  instance_count: 100,
+  completed_count: 90,
+  incident_count: incidentRatePct,
+  incident_rate_pct: incidentRatePct,
+  element_incident_count: null,
+  element_incident_rate_pct: null,
+  avg_duration_sec: 10,
+  p95_duration_sec: 20,
+})
+
+const result: VersionCompareResult = {
+  engines: ["prod-a"],
+  processDefinitionKey: "order",
+  versionA: 1,
+  versionB: 2,
+  windowDays: 14,
+  minBucketSize: 10,
+  suppressed: false,
+  kpis: [versionKpi(1, 2), versionKpi(2, 2.5)],
+  delta: {
+    started_per_day_delta_pct: 0,
+    incident_rate_delta_pp: 0.5,
+    element_incident_rate_delta_pp: null,
+    avg_duration_delta_pct: 25,
+    p95_duration_delta_pct: 40,
+  },
+}
+
+const prompt = (data: VersionCompareResult) =>
+  bindHandOff("en", ANALYTICS_ONLY_SURFACE).ask(versionCompareHandOff(data))!
+
+describe("versionCompareHandOff", () => {
+  it("re-runs the process-wide comparison on the engines on screen — never an element scope", () => {
+    const text = prompt(result)
+
+    expect(text).toContain(
+      'Ids: engine="prod-a", processDefinitionKey="order", versionA=1, versionB=2, windowDays=14\n',
+    )
+    // The tool takes no element scope (#336) — the hand-off must not suggest one.
+    expect(text).not.toContain("activityId")
+  })
+
+  it("carries the measured deltas, the incident rate per version included", () => {
+    const text = prompt(result)
+    expect(text).toContain("incidentRateDeltaPp=0.5")
+    expect(text).toContain("avgDurationDeltaPct=25")
+    expect(text).not.toContain("elementIncidentRateDeltaPp")
+  })
+
+  it("leaves a null delta out instead of sending it as 0", () => {
+    const text = prompt({ ...result, delta: { ...result.delta, p95_duration_delta_pct: null } })
+    expect(text).not.toContain("p95DurationDeltaPct")
+  })
+
+  it("names the confirming comparison and the element ranking", () => {
+    expect(prompt(result)).toContain(
+      "Tools: analytics_version_compare, analytics_element_bottleneck",
+    )
+  })
+})