@cosmicdrift/kumiko-renderer 0.257.0 → 0.258.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.257.0",
+  "version": "0.258.1",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.257.0",
-    "@cosmicdrift/kumiko-headless": "0.257.0",
+    "@cosmicdrift/kumiko-framework": "0.258.1",
+    "@cosmicdrift/kumiko-headless": "0.258.1",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.257.0"
+    "@cosmicdrift/kumiko-locale-de": "0.258.1"
   },
   "repository": {
     "type": "git",

package/src/__tests__/merge-search-params-into-initial.test.ts

@@ -5,7 +5,11 @@ type FieldDef = {
   type?: string;
   default?: unknown;
   sensitive?: boolean;
+  format?: string;
   options?: readonly string[];
+  multiple?: boolean;
+  schema?: Record<string, { type?: string; options?: readonly string[] }>;
+  maxItems?: number;
 };
 
 describe("mergeSearchParamsIntoInitial", () => {
@@ -39,6 +43,14 @@ describe("mergeSearchParamsIntoInitial", () => {
     expect(result["password"]).toBe("");
   });
 
+  test("password-format field is skipped even when a matching searchParam exists (fw#2548)", () => {
+    const fields: Record<string, FieldDef> = {
+      apiToken: { type: "text", format: "password", default: "unset" },
+    };
+    const result = mergeSearchParamsIntoInitial(fields, { apiToken: "kpat_leak" });
+    expect(result["apiToken"]).toBe("unset");
+  });
+
   test("field with no matching searchParam keeps its buildInitialValues default", () => {
     const fields: Record<string, FieldDef> = { total: { type: "number", default: 100 } };
     const result = mergeSearchParamsIntoInitial(fields, {});
@@ -196,4 +208,142 @@ describe("mergeSearchParamsIntoInitial", () => {
       warnSpy.mockRestore();
     }
   });
+
+  describe("embeddedList prefill (fw#2764)", () => {
+    const linesField = (extra: Partial<FieldDef> = {}): Record<string, FieldDef> => ({
+      lines: {
+        type: "embedded",
+        multiple: true,
+        schema: {
+          accountId: { type: "text" },
+          amount: { type: "money" },
+          qty: { type: "number" },
+          posted: { type: "boolean" },
+          kind: { type: "select", options: ["debit", "credit"] },
+        },
+        ...extra,
+      },
+    });
+
+    test("a JSON row list from params.map arrives complete in the field", () => {
+      const rows = [
+        { accountId: "bank", amount: 1299, qty: 2, posted: true, kind: "debit" },
+        { accountId: "cash", amount: -1299, qty: 1, posted: false, kind: "credit" },
+      ];
+      const result = mergeSearchParamsIntoInitial(linesField(), { lines: JSON.stringify(rows) });
+      expect(result["lines"]).toEqual(rows);
+    });
+
+    test("money cells stay signed minor-unit integers", () => {
+      const result = mergeSearchParamsIntoInitial(linesField(), {
+        lines: JSON.stringify([{ accountId: "bank", amount: -4200 }]),
+      });
+      expect(result["lines"]).toEqual([{ accountId: "bank", amount: -4200 }]);
+    });
+
+    test("a fractional money cell rejects the whole prefill and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField(), {
+          lines: JSON.stringify([{ accountId: "bank", amount: 12.99 }]),
+        });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+        expect(warnSpy.mock.calls[0]?.[0]).toContain("lines");
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("a non-JSON param leaves the field empty and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField(), { lines: "not-json-at-all" });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("a JSON object instead of an array leaves the field empty and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField(), {
+          lines: JSON.stringify({ accountId: "bank" }),
+        });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("a row that is not an object leaves the field empty and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField(), {
+          lines: JSON.stringify([1, 2]),
+        });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("a select cell outside the declared options rejects the prefill and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField(), {
+          lines: JSON.stringify([{ accountId: "bank", kind: "sudo" }]),
+        });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("undeclared row keys are dropped instead of reaching the form", () => {
+      const result = mergeSearchParamsIntoInitial(linesField(), {
+        lines: JSON.stringify([{ accountId: "bank", secretFlag: "yes" }]),
+      });
+      expect(result["lines"]).toEqual([{ accountId: "bank" }]);
+    });
+
+    test("a __proto__ key in a row pollutes nothing", () => {
+      const result = mergeSearchParamsIntoInitial(linesField(), {
+        lines: '[{"accountId":"bank","__proto__":{"polluted":true}}]',
+      });
+      expect(result["lines"]).toEqual([{ accountId: "bank" }]);
+      expect(({} as Record<string, unknown>)["polluted"]).toBeUndefined();
+      expect(Object.getPrototypeOf((result["lines"] as unknown[])[0])).toBe(Object.prototype);
+    });
+
+    test("more rows than maxItems leaves the field empty and warns", () => {
+      const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const result = mergeSearchParamsIntoInitial(linesField({ maxItems: 2 }), {
+          lines: JSON.stringify([{ accountId: "a" }, { accountId: "b" }, { accountId: "c" }]),
+        });
+        expect(result["lines"]).toEqual([]);
+        expect(warnSpy).toHaveBeenCalled();
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    test("an embedded list without a matching param defaults to an empty array", () => {
+      const result = mergeSearchParamsIntoInitial(linesField(), {});
+      expect(result["lines"]).toEqual([]);
+    });
+
+    test("a sensitive embedded list ignores the param", () => {
+      const result = mergeSearchParamsIntoInitial(linesField({ sensitive: true }), {
+        lines: JSON.stringify([{ accountId: "bank" }]),
+      });
+      expect(result["lines"]).toEqual([]);
+    });
+  });
 });

package/src/app/__tests__/action-form-shim.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "../action-form-shim";
+import {
+  synthesizeActionFormEntity,
+  synthesizeActionFormScreen,
+  synthesizeSecretMintConfirmScreen,
+} from "../action-form-shim";
 
 describe("synthesizeActionFormEntity", () => {
   test("wraps inline fields as minimal EntityDefinition", () => {
@@ -45,3 +49,47 @@ describe("synthesizeActionFormScreen", () => {
     expect("description" in withoutDescription).toBe(false);
   });
 });
+
+describe("synthesizeSecretMintConfirmScreen (fw#2838)", () => {
+  test("maps a secretMint's confirm step to the entityEdit shape RenderEdit expects, with a distinct id", () => {
+    const screen = synthesizeSecretMintConfirmScreen(
+      {
+        id: "mint-token",
+        type: "secretMint",
+        handler: "shop:write:token:mint",
+        fields: { label: { type: "text" } },
+        layout: { sections: [{ title: "Mint", fields: ["label"] }] },
+        reveal: { fields: [{ field: "token", label: "Token" }] },
+      },
+      {
+        handler: "shop:write:token:confirm",
+        fields: { code: { type: "text" } },
+        layout: { sections: [{ title: "Confirm", fields: ["code"] }] },
+      },
+    );
+    expect(screen.id).toBe("mint-token:confirm");
+    expect(screen.type).toBe("entityEdit");
+    expect(screen.entity).toBe("__action-form__");
+    expect(screen.layout).toEqual({ sections: [{ title: "Confirm", fields: ["code"] }] });
+  });
+
+  test("carries the mint screen's access rule through to the confirm form", () => {
+    const screen = synthesizeSecretMintConfirmScreen(
+      {
+        id: "mint-token",
+        type: "secretMint",
+        handler: "shop:write:token:mint",
+        fields: { label: { type: "text" } },
+        layout: { sections: [{ title: "Mint", fields: ["label"] }] },
+        reveal: { fields: [{ field: "token", label: "Token" }] },
+        access: { roles: ["admin"] },
+      },
+      {
+        handler: "shop:write:token:confirm",
+        fields: { code: { type: "text" } },
+        layout: { sections: [{ title: "Confirm", fields: ["code"] }] },
+      },
+    );
+    expect(screen.access).toEqual({ roles: ["admin"] });
+  });
+});

package/src/app/__tests__/secret-mint-body.test.tsx

@@ -0,0 +1,396 @@
+// fw#2548: secretMint mints a one-time secret from a write-handler's own
+// success payload. This renders the real path (KumikoScreen → SecretMintBody
+// → RenderEdit) under a stub dispatcher, proving: (1) the secret is absent
+// before submit, (2) only the whitelisted reveal.fields survive the submit —
+// a stray "id" in the payload never leaks, (3) confirming clears the reveal
+// from the DOM, (4) no query call ever runs that could reload the secret.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  SecretMintScreenDefinition,
+  TextFieldDef,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { fireEvent, render, screen as rtlScreen, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type BannerProps,
+  type CorePrimitives,
+  PrimitivesProvider,
+  type SecretRevealProps,
+  type SectionProps,
+  type TextProps,
+} from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import { NavProvider, type NavTarget } from "../nav";
+
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+const noop = () => null;
+
+const testButton: ComponentType<{
+  children?: ReactNode;
+  onClick?: () => void;
+  testId?: string;
+  type?: "button" | "submit";
+  disabled?: boolean;
+}> = ({ children, onClick, testId, type, disabled }) => (
+  <button type={type ?? "button"} data-testid={testId} onClick={onClick} disabled={disabled}>
+    {children}
+  </button>
+);
+
+const testForm: ComponentType<{
+  children?: ReactNode;
+  actions?: ReactNode;
+  secondaryActions?: ReactNode;
+  onSubmit?: () => void;
+}> = ({ children, actions, secondaryActions, onSubmit }) => (
+  <form
+    onSubmit={(e) => {
+      e.preventDefault();
+      onSubmit?.();
+    }}
+  >
+    {children}
+    {secondaryActions}
+    {actions}
+  </form>
+);
+
+const testInput: ComponentType<{
+  name?: string;
+  value?: unknown;
+  onChange?: (v: unknown) => void;
+}> = ({ name = "field", value, onChange }) => (
+  <input
+    aria-label={name}
+    data-testid={`input-${name}`}
+    value={typeof value === "string" ? value : ""}
+    onChange={(e) => onChange?.(e.target.value)}
+  />
+);
+
+const testSection: ComponentType<SectionProps> = ({ testId, children }) => (
+  <div data-testid={testId}>{children}</div>
+);
+const testBanner: ComponentType<BannerProps> = ({ children, testId }) => (
+  <div data-testid={testId}>{children}</div>
+);
+const testText: ComponentType<TextProps> = ({ children, testId }) => (
+  <span data-testid={testId}>{children}</span>
+);
+// Renders every value's raw text plus a `data-qr` marker — lets tests assert
+// both DOM-leak absence (no query needed to find rendered text) and that
+// display: "qr" reaches the primitive as `qr: true`.
+const testSecretReveal: ComponentType<SecretRevealProps> = ({ values, testId }) => (
+  <div data-testid={testId}>
+    {values.map((v) => (
+      <div key={v.label} data-testid={`secret-value-${v.label}`} data-qr={String(v.qr === true)}>
+        {v.value}
+      </div>
+    ))}
+  </div>
+);
+
+const testPrimitives: CorePrimitives = {
+  Button: testButton,
+  Banner: testBanner,
+  Field: passChildren,
+  Input: testInput,
+  DataTable: noop,
+  Form: testForm,
+  Section: testSection,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: testText,
+  Heading: passChildren,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+  SecretReveal: testSecretReveal,
+} as unknown as CorePrimitives;
+
+const mintScreen: SecretMintScreenDefinition = {
+  id: "mint-token",
+  type: "secretMint",
+  handler: "shop:write:token:mint",
+  fields: { label: { type: "text" } as TextFieldDef },
+  layout: { sections: [{ title: "Mint", fields: ["label"] }] },
+  reveal: { fields: [{ field: "token", label: "Token" }] },
+};
+
+function buildSchema(screen: SecretMintScreenDefinition): FeatureSchema {
+  return {
+    featureName: "shop",
+    entities: {},
+    screens: [screen],
+  } as FeatureSchema;
+}
+
+function stubDispatcher(writeData: unknown): {
+  dispatcher: Dispatcher;
+  queryCalls: unknown[];
+} {
+  const queryCalls: unknown[] = [];
+  const dispatcher: Dispatcher = {
+    write: (async () => ({ isSuccess: true, data: writeData })) as unknown as Dispatcher["write"],
+    query: (async (type: string, payload: unknown) => {
+      queryCalls.push({ type, payload });
+      return { isSuccess: true, data: {} };
+    }) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+  return { dispatcher, queryCalls };
+}
+
+// Keyed stub — one write-response per handler QN, and every write call
+// recorded with its full payload — for scenarios with more than one
+// write-handler in play (mint + confirm).
+function stubMultiWriteDispatcher(responses: Readonly<Record<string, unknown>>): {
+  dispatcher: Dispatcher;
+  writeCalls: Array<{ readonly command: string; readonly payload: unknown }>;
+} {
+  const writeCalls: Array<{ readonly command: string; readonly payload: unknown }> = [];
+  const dispatcher: Dispatcher = {
+    write: (async (command: string, payload: unknown) => {
+      writeCalls.push({ command, payload });
+      return { isSuccess: true, data: responses[command] ?? {} };
+    }) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+  return { dispatcher, writeCalls };
+}
+
+function renderMintScreen(
+  dispatcher: Dispatcher,
+  screen: SecretMintScreenDefinition = mintScreen,
+  navigate: (target: NavTarget) => void = () => {},
+) {
+  const qn = `shop:screen:${screen.id}`;
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={dispatcher}>
+        <NavProvider
+          value={{
+            route: { screenId: qn },
+            navigate,
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: () => {},
+          }}
+        >
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={buildSchema(screen)} qn={qn} />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("SecretMintBody (fw#2548)", () => {
+  test("before submit: the secret is not in the DOM", () => {
+    const { dispatcher } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    renderMintScreen(dispatcher);
+    expect(rtlScreen.queryByText("kpat_secret")).toBeNull();
+  });
+
+  test("after a successful submit: only the whitelisted reveal field appears — not the payload's other fields", async () => {
+    const { dispatcher } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    renderMintScreen(dispatcher);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+    expect(rtlScreen.queryByText("x")).toBeNull();
+  });
+
+  test("confirming the reveal clears the secret from the DOM", async () => {
+    const { dispatcher } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    renderMintScreen(dispatcher);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    fireEvent.click(rtlScreen.getByTestId("kumiko-screen-secret-mint-confirm"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).toBeNull());
+  });
+
+  test("the secret is never fetched via a query — it only ever comes from the write result", async () => {
+    const { dispatcher, queryCalls } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    renderMintScreen(dispatcher);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    expect(queryCalls.length).toBe(0);
+  });
+
+  test("acknowledging without a confirm step and without a redirect shows the done banner", async () => {
+    const { dispatcher } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    renderMintScreen(dispatcher);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    fireEvent.click(rtlScreen.getByTestId("kumiko-screen-secret-mint-confirm"));
+    await waitFor(() =>
+      expect(rtlScreen.queryByTestId("kumiko-screen-secret-mint-done")).not.toBeNull(),
+    );
+  });
+
+  test("acknowledging with a redirect navigates instead of showing the done banner", async () => {
+    const { dispatcher } = stubDispatcher({ token: "kpat_secret", id: "x" });
+    const navigateCalls: NavTarget[] = [];
+    renderMintScreen(dispatcher, { ...mintScreen, redirect: "after-mint" }, (target) =>
+      navigateCalls.push(target),
+    );
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    fireEvent.click(rtlScreen.getByTestId("kumiko-screen-secret-mint-confirm"));
+    await waitFor(() => expect(navigateCalls.length).toBe(1));
+    expect(navigateCalls[0]).toEqual({ screenId: "after-mint" });
+    expect(rtlScreen.queryByTestId("kumiko-screen-secret-mint-done")).toBeNull();
+  });
+
+  test("a reveal field with display 'qr' reaches the SecretReveal primitive with qr: true", async () => {
+    const qrScreen: SecretMintScreenDefinition = {
+      ...mintScreen,
+      reveal: { fields: [{ field: "token", label: "Token", display: "qr" }] },
+    };
+    const { dispatcher } = stubDispatcher({ token: "otpauth://totp/x?secret=ABC", id: "x" });
+    renderMintScreen(dispatcher, qrScreen);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+
+    await waitFor(() =>
+      expect(rtlScreen.getByTestId("secret-value-Token").getAttribute("data-qr")).toBe("true"),
+    );
+  });
+
+  test("an input-less secretMint (no fields) has an active submit button and dispatches the mint handler on click", async () => {
+    const inputLessScreen: SecretMintScreenDefinition = {
+      id: "mint-token",
+      type: "secretMint",
+      handler: "shop:write:token:mint",
+      fields: {},
+      layout: { sections: [] },
+      reveal: { fields: [{ field: "token", label: "Token" }] },
+    };
+    const { dispatcher, writeCalls } = stubMultiWriteDispatcher({
+      "shop:write:token:mint": { token: "kpat_secret" },
+    });
+    renderMintScreen(dispatcher, inputLessScreen);
+
+    const submit = rtlScreen.getByTestId("render-edit-submit") as HTMLButtonElement;
+    expect(submit.disabled).toBe(false);
+    fireEvent.click(submit);
+
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+    expect(writeCalls.map((c) => c.command)).toEqual(["shop:write:token:mint"]);
+  });
+});
+
+describe("SecretMintBody confirm step (fw#2838)", () => {
+  const mintScreenWithConfirm: SecretMintScreenDefinition = {
+    ...mintScreen,
+    confirm: {
+      handler: "shop:write:token:confirm",
+      fields: { code: { type: "text" } as TextFieldDef },
+      layout: { sections: [{ title: "Confirm", fields: ["code"] }] },
+      carry: ["setupToken"],
+    },
+  };
+
+  test("renders the confirm form instead of the acknowledge button, and submits the confirm form's own values merged with the carried mint-payload field", async () => {
+    const { dispatcher, writeCalls } = stubMultiWriteDispatcher({
+      "shop:write:token:mint": { token: "kpat_secret", id: "x", setupToken: "stok_123" },
+      "shop:write:token:confirm": {},
+    });
+    renderMintScreen(dispatcher, mintScreenWithConfirm);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    // No bare acknowledge button — the confirm form takes its place.
+    expect(rtlScreen.queryByTestId("kumiko-screen-secret-mint-confirm")).toBeNull();
+
+    fireEvent.change(rtlScreen.getByLabelText(/code/i), { target: { value: "123456" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+
+    await waitFor(() =>
+      expect(writeCalls.some((c) => c.command === "shop:write:token:confirm")).toBe(true),
+    );
+    const confirmCall = writeCalls.find((c) => c.command === "shop:write:token:confirm");
+    expect(confirmCall?.payload).toEqual({ code: "123456", setupToken: "stok_123" });
+  });
+
+  test("a carried field that is not in reveal.fields never appears in the DOM", async () => {
+    const { dispatcher } = stubMultiWriteDispatcher({
+      "shop:write:token:mint": { token: "kpat_secret", id: "x", setupToken: "stok_123" },
+    });
+    renderMintScreen(dispatcher, mintScreenWithConfirm);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    expect(rtlScreen.queryByText("stok_123")).toBeNull();
+  });
+
+  test("without a redirect, a successful confirm shows the done banner", async () => {
+    const { dispatcher } = stubMultiWriteDispatcher({
+      "shop:write:token:mint": { token: "kpat_secret", id: "x", setupToken: "stok_123" },
+      "shop:write:token:confirm": {},
+    });
+    renderMintScreen(dispatcher, mintScreenWithConfirm);
+
+    fireEvent.change(rtlScreen.getByLabelText(/label/i), { target: { value: "My token" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+    await waitFor(() => expect(rtlScreen.queryByText("kpat_secret")).not.toBeNull());
+
+    fireEvent.change(rtlScreen.getByLabelText(/code/i), { target: { value: "123456" } });
+    fireEvent.click(rtlScreen.getByTestId("render-edit-submit"));
+
+    await waitFor(() =>
+      expect(rtlScreen.queryByTestId("kumiko-screen-secret-mint-done")).not.toBeNull(),
+    );
+    expect(rtlScreen.queryByText("kpat_secret")).toBeNull();
+  });
+});