@cosmicdrift/kumiko-renderer 0.193.1 → 0.195.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.193.1",
+  "version": "0.195.0",
   "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.193.1",
-    "@cosmicdrift/kumiko-headless": "0.193.1",
+    "@cosmicdrift/kumiko-framework": "0.195.0",
+    "@cosmicdrift/kumiko-headless": "0.195.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/__tests__/error-i18n-defaults.test.ts

@@ -12,6 +12,7 @@ import {
   ValidationError,
   VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/errors";
+import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema";
 import { kumikoDefaultTranslations } from "../i18n-defaults";
 
 // Keys are read off LIVE error instances, not a hardcoded list — a copied list
@@ -69,4 +70,12 @@ describe("kumikoDefaultTranslations covers every error i18nKey", () => {
     expect(de?.["dispatcher.errors.aborted"]).toBeTruthy();
     expect(en?.["dispatcher.errors.aborted"]).toBeTruthy();
   });
+
+  // Client-emitted (form-schema.ts required-field presence check) — not
+  // thrown by an error class, applied as a params.i18nKey override on a zod
+  // issue instead; still rendered through this last-resort bundle.
+  test("form-schema's required-field i18nKey has de+en default", () => {
+    expect(de?.[REQUIRED_FIELD_I18N_KEY]).toBeTruthy();
+    expect(en?.[REQUIRED_FIELD_I18N_KEY]).toBeTruthy();
+  });
 });

package/src/app/__tests__/content-editors.test.tsx

@@ -18,7 +18,8 @@ const captureInput: ComponentType<InputProps> = (props) => {
       id={props.id}
       value={props.value}
       disabled={props.disabled}
-      readOnly
+      readOnly={props.readOnly}
+      onChange={() => {}}
     />
   );
 };
@@ -57,7 +58,15 @@ function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
 
 function Probe({ contentFormat }: { readonly contentFormat?: string }): ReactNode {
   const Editor = useContentEditor(contentFormat);
-  return <Editor value="hello" onChange={() => {}} variables={[]} readOnly={false} />;
+  return (
+    <Editor
+      id={CONTENT_EDITOR_ELEMENT_ID}
+      value="hello"
+      onChange={() => {}}
+      variables={[]}
+      readOnly={false}
+    />
+  );
 }
 
 describe("useContentEditor", () => {
@@ -96,13 +105,23 @@ describe("useContentEditor", () => {
 });
 
 describe("TextareaContentEditor", () => {
-  test("passes value + disabled=readOnly through to the primitives Input", () => {
+  test("passes value + readOnly through to the primitives Input as real readOnly, not disabled", () => {
+    // A disabled textarea isn't focusable/selectable in most browsers — a
+    // non-admin viewing read-only content couldn't select/copy it. readOnly
+    // keeps the field focusable and selectable while blocking edits.
     render(
-      <TextareaContentEditor value="draft" onChange={() => {}} variables={[]} readOnly={true} />,
+      <TextareaContentEditor
+        id={CONTENT_EDITOR_ELEMENT_ID}
+        value="draft"
+        onChange={() => {}}
+        variables={[]}
+        readOnly={true}
+      />,
       { wrapper: Wrapper },
     );
     const el = screen.getByTestId("ca-textarea") as HTMLTextAreaElement;
     expect(el.value).toBe("draft");
-    expect(el.disabled).toBe(true);
+    expect(el.readOnly).toBe(true);
+    expect(el.disabled).toBe(false);
   });
 });

package/src/app/__tests__/content-preview.test.tsx

@@ -99,7 +99,8 @@ describe("ContentPreview", () => {
 
     const el = screen.getByTestId("cp-textarea") as HTMLTextAreaElement;
     expect(el.value).toBe("Hi A-1042");
-    expect(el.disabled).toBe(true);
+    expect(el.readOnly).toBe(true);
+    expect(el.disabled).toBe(false);
   });
 
   test("rich format: an example value with markup characters is escaped, not injected as HTML", () => {
@@ -124,6 +125,27 @@ describe("ContentPreview", () => {
     expect(el.textContent).toBe("Preis: <b>0</b> & up");
   });
 
+  // Known limitation: escaping is keyed off the *declared* format, not the
+  // actually-resolved editor. If "rich" is declared but no rich editor is
+  // registered, useContentEditor falls back to the plain textarea and the
+  // markup-safe escaping (only applied for contentFormat === "rich") never
+  // ran for the plain path — entities show up literal instead of rendered.
+  // Pinned here rather than fixed: fixing it needs a per-editor
+  // `rendersHtml` flag threaded through content-editors.tsx.
+  test("rich format with no registered editor → falls back to the textarea, entities shown literally", () => {
+    render(
+      <ContentPreview
+        content="Preis: {{price}}"
+        variables={{ price: "<b>0</b> & up" }}
+        contentFormat="rich"
+      />,
+      { wrapper: Wrapper },
+    );
+
+    const el = screen.getByTestId("cp-textarea") as HTMLTextAreaElement;
+    expect(el.value).toBe("Preis: &lt;b&gt;0&lt;/b&gt; &amp; up");
+  });
+
   test("plain format: an example value with markup characters passes through unescaped", () => {
     render(
       <ContentPreview

package/src/app/__tests__/form-schema.test.ts

@@ -5,7 +5,7 @@ import type {
   EntityEditScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import { createFormController } from "@cosmicdrift/kumiko-headless";
-import { buildFormSchema } from "../form-schema";
+import { buildFormSchema, REQUIRED_FIELD_I18N_KEY } from "../form-schema";
 
 function screenWith(fields: readonly EditFieldSpec[]): EntityEditScreenDefinition {
   return {
@@ -41,10 +41,6 @@ describe("buildFormSchema", () => {
     }
   });
 
-  // kumiko-framework#1927: a bare presence issue used to render as
-  // "Invalid value." — pin the params.i18nKey override so the resolved
-  // FieldIssue points at "kumiko.validation.required" ("Pflichtfeld.")
-  // instead of the generic errors.validation.custom fallback.
   test("required field missing → issue carries the required-field i18nKey override", () => {
     const entity = entityWith({ name: { type: "text", required: true } });
     const screen = screenWith(["name"]);
@@ -54,14 +50,14 @@ describe("buildFormSchema", () => {
     if (result.success) return;
     const issue = result.error.issues[0];
     if (issue?.code !== "custom") throw new Error("expected a custom issue");
-    expect(issue.params).toMatchObject({ i18nKey: "kumiko.validation.required" });
+    expect(issue.params).toMatchObject({ i18nKey: REQUIRED_FIELD_I18N_KEY });
   });
 
-  // kumiko-framework#1927: the seam the bug actually lived in — a schema
-  // built here only round-trips through createFormController's validate(),
-  // which is what feeds FormSnapshot.errors that render-edit.tsx passes to
-  // RenderField. A unit test on buildFormSchema() alone can't catch a break
-  // in that hand-off (e.g. zodErrorToFieldIssues not honoring the override).
+  // The seam the bug actually lived in — a schema built here only round-trips
+  // through createFormController's validate(), which is what feeds
+  // FormSnapshot.errors that render-edit.tsx passes to RenderField. A unit
+  // test on buildFormSchema() alone can't catch a break in that hand-off
+  // (e.g. zodErrorToFieldIssues not honoring the override).
   test("end-to-end via createFormController: required field left empty → snapshot error carries kumiko.validation.required", () => {
     const entity = entityWith({ name: { type: "text", required: true } });
     const screen = screenWith(["name"]);
@@ -73,7 +69,7 @@ describe("buildFormSchema", () => {
 
     expect(form.validate()).toBe(false);
     const fieldErrors = form.getSnapshot().errors["name"];
-    expect(fieldErrors?.[0]?.i18nKey).toBe("kumiko.validation.required");
+    expect(fieldErrors?.[0]?.i18nKey).toBe(REQUIRED_FIELD_I18N_KEY);
   });
 
   describe("required field present → no issue", () => {

package/src/app/content-editors.tsx

@@ -12,6 +12,12 @@ import { type ComponentType, createContext, type ReactNode, useContext } from "r
 import { usePrimitives } from "../primitives";
 
 export type ContentEditorProps = {
+  /** DOM id every registered editor must render onto its own focusable
+   *  root element. Callers that wrap an editor in a `Field` (label +
+   *  htmlFor) pass a stable id here so the label stays associated with
+   *  whatever element actually renders — a fixed constant would break as
+   *  soon as a registered editor swaps in for the textarea fallback. */
+  readonly id: string;
   readonly value: string;
   readonly onChange: (value: string) => void;
   /** Variable names insertable as chips (from the collection's
@@ -24,10 +30,10 @@ export type ContentEditorProps = {
 
 export type ContentEditorComponent = ComponentType<ContentEditorProps>;
 
-/** Fixed DOM id the fallback textarea renders under. Callers that wrap an
- *  editor in a `Field` (label + htmlFor) use this as the Field's `id` so the
- *  label stays associated — the editor contract has no `id` prop of its own,
- *  every registered editor owns its own focusable element's id. */
+/** Default id value for callers that don't generate their own (e.g. a
+ *  standalone TextareaContentEditor render outside a multi-editor page).
+ *  Registered editors don't apply this automatically — every caller passes
+ *  its own id via ContentEditorProps.id. */
 export const CONTENT_EDITOR_ELEMENT_ID = "content-editor-textarea";
 
 export type ContentEditorsMap = Readonly<Record<string, ContentEditorComponent>>;
@@ -50,6 +56,7 @@ export function ContentEditorsProvider({
  *  Uses the primitives Input like every other form field, so it renders on
  *  every platform without requiring the platform's DOM/native equivalent. */
 export function TextareaContentEditor({
+  id,
   value,
   onChange,
   readOnly,
@@ -58,11 +65,11 @@ export function TextareaContentEditor({
   return (
     <Input
       kind="textarea"
-      id={CONTENT_EDITOR_ELEMENT_ID}
+      id={id}
       name={CONTENT_EDITOR_ELEMENT_ID}
       value={value}
       onChange={onChange}
-      disabled={readOnly}
+      readOnly={readOnly}
       rows={14}
     />
   );

package/src/app/content-preview.tsx

@@ -4,7 +4,7 @@
 // renders formatted HTML and "plain"/"markdown" render as text through the
 // exact same component, no separate render path per format.
 
-import type { ReactNode } from "react";
+import { type ReactNode, useId } from "react";
 import { useContentEditor } from "./content-editors";
 
 const VARIABLE_PATTERN = /\{\{\s*(\w+)\s*\}\}/g;
@@ -36,6 +36,7 @@ export function ContentPreview({
   contentFormat,
 }: ContentPreviewProps): ReactNode {
   const Editor = useContentEditor(contentFormat);
+  const id = useId();
   // "rich" content is HTML (see ContentCollectionDefinition.contentFormat) —
   // an example value substituted in raw could break the markup (`<`) or
   // render as an unescaped entity (`&`). "plain"/"markdown" content is text,
@@ -48,6 +49,7 @@ export function ContentPreview({
       : variables;
   return (
     <Editor
+      id={id}
       value={substituteVariables(content, safeVariables)}
       onChange={noop}
       variables={[]}

package/src/app/extension-sections.tsx

@@ -55,8 +55,11 @@ export type ExtensionSectionProps = {
   readonly values?: Readonly<Record<string, unknown>>;
   /** Sets host RenderEdit form values from outside (e.g. a VIN-decode
    *  roundtrip that fills other fields) — same function as
-   *  `RenderEditControls.patch`, merges only the given keys. Undefined
-   *  outside entityEdit sections. */
+   *  `RenderEditControls.patch`, merges only the given keys. `patch` must
+   *  converge: `setValues` is a no-op only when the merged result is
+   *  reference-equal to the current values, so an unconditional
+   *  `patch(...)` from a `values`-dependent effect loops. Undefined outside
+   *  entityEdit sections. */
   readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
   /** Validates the host form without writing — same function as
    *  `RenderEditControls.validate`; field errors land in

package/src/app/form-schema.ts

@@ -1,8 +1,10 @@
 import type {
   EntityDefinition,
   EntityEditScreenDefinition,
+  FieldDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
 import { z } from "zod";
 import { layoutEditFields } from "./layout-fields";
 
@@ -25,7 +27,15 @@ function isPresent(value: unknown): boolean {
 // packages/framework/src/engine/boot-validator/screens.ts, which mirrors
 // this set (framework can't import renderer, so it can't import this
 // constant directly — keep both in sync).
-const FIELD_TYPES_WITHOUT_WIDGET = new Set(["jsonb", "embedded", "files", "images"]);
+const FIELD_TYPES_WITHOUT_WIDGET: ReadonlySet<FieldDefinition["type"]> = new Set([
+  "jsonb",
+  "embedded",
+  "files",
+  "images",
+]);
+
+// Renders raw to the user without a de+en default in i18n-defaults.ts.
+export const REQUIRED_FIELD_I18N_KEY = "kumiko.validation.required";
 
 // Client-side presence validation for the auto-wired entityEdit path —
 // checks that every rendered required field HAS a value, not that the
@@ -82,8 +92,8 @@ export function buildFormSchema(
           code: "custom",
           path: [spec.field],
           message: `"${spec.field}" is required.`,
-          // `params.i18nKey` override, see packages/headless/src/form/zod-bridge.ts.
-          params: { i18nKey: "kumiko.validation.required" },
+          // I18N_KEY_PARAM override, see packages/headless/src/form/zod-bridge.ts.
+          params: { [I18N_KEY_PARAM]: REQUIRED_FIELD_I18N_KEY },
         });
       }
     });

package/src/app/kumiko-screen.tsx

@@ -26,6 +26,7 @@ import type {
 } from "@cosmicdrift/kumiko-headless";
 import { fieldLabelKey } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { extractCreatedId } from "../components/reference-create-dialog";
 import { RenderEdit } from "../components/render-edit";
 import { RenderList, type ToolbarActionButton } from "../components/render-list";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context";
@@ -461,7 +462,11 @@ function EntityEditCreateBody({
     (result: SubmitResult<unknown>) => {
       if (!result.isSuccess) return;
       if (screen.redirect !== undefined) {
-        nav.navigate({ screenId: lastSegment(screen.redirect) });
+        const entityId = extractCreatedId(result.data);
+        nav.navigate({
+          screenId: lastSegment(screen.redirect),
+          ...(entityId !== undefined && { entityId }),
+        });
         return;
       }
       navigateToList();
@@ -699,7 +704,8 @@ function EntityEditSingletonBody({
       </Banner>
     );
   }
-  const existingId = listQuery.data?.rows[0]?.["id"] as string | undefined;
+  const rawExistingId = listQuery.data?.rows[0]?.["id"];
+  const existingId = typeof rawExistingId === "string" ? rawExistingId : undefined;
   if (existingId !== undefined) {
     return (
       <EntityEditUpdateBody

package/src/components/__tests__/embedded-list-field.test.tsx

@@ -7,7 +7,7 @@
 
 import { describe, expect, test } from "bun:test";
 import type { Dispatcher, EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
-import { render, waitFor } from "@testing-library/react";
+import { act, render, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
@@ -311,6 +311,26 @@ describe("EmbeddedListField — paste coercion", () => {
     ]);
   });
 
+  // kumiko-framework#1972: a hardcoded ×100 in the paste path diverged from
+  // the typed-in path's currencyDecimals-based scaling for any non-2-decimal
+  // currency — JPY (0 decimals) pasted "1234" would have landed on 123400
+  // (100x too large) instead of 1234.
+  test("pastes a money cell for a zero-decimal currency (JPY) without the paste-path ×100 bug", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 0, amount: 0 }];
+    let lastValue: unknown;
+    renderEmbeddedListField(
+      invoiceLinesField({ value: rows, embeddedListCurrency: "JPY" }),
+      (v) => {
+        lastValue = v;
+      },
+    );
+    // Columns in order: product, unit, quantity, unitPrice, amount. Paste
+    // starting at "unitPrice" (index 3).
+    captured?.onPasteCells?.(0, 3, [["1234"]]);
+    const result = lastValue as readonly Record<string, unknown>[];
+    expect(result[0]?.["unitPrice"]).toBe(1234);
+  });
+
   test("paste beyond the current rows appends new rows but never past maxItems", () => {
     const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
     let lastValue: unknown;
@@ -325,6 +345,53 @@ describe("EmbeddedListField — paste coercion", () => {
     const result = lastValue as readonly Record<string, unknown>[];
     expect(result.length).toBe(2);
   });
+
+  test("paste beyond maxItems surfaces a listIssue with the dropped-row count", async () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    renderEmbeddedListField(invoiceLinesField({ value: rows, embeddedListMaxItems: 2 }), () => {});
+    act(() => {
+      captured?.onPasteCells?.(0, 2, [
+        ["1", "100"],
+        ["2", "200"],
+        ["3", "300"],
+      ]);
+    });
+    await waitFor(() => {
+      expect(captured?.listIssues).toEqual([
+        {
+          path: "lines",
+          code: "paste-rows-truncated",
+          i18nKey: "kumiko.field.embedded-list.paste-rows-truncated",
+          params: { count: 1 },
+        },
+      ]);
+    });
+  });
+
+  test("a select paste value with no matching option leaves the cell unchanged and surfaces a listIssue", async () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    // Columns in order: product, unit, quantity, unitPrice, amount. Column
+    // index 1 = "unit" (select, options ["pcs","hours","kg"]) — "not-a-unit"
+    // matches none of them.
+    act(() => {
+      captured?.onPasteCells?.(0, 1, [["not-a-unit"]]);
+    });
+    expect(lastValue).toEqual([rows[0]]);
+    await waitFor(() => {
+      expect(captured?.listIssues).toEqual([
+        {
+          path: "lines",
+          code: "paste-cells-unmatched",
+          i18nKey: "kumiko.field.embedded-list.paste-cells-unmatched",
+          params: { count: 1 },
+        },
+      ]);
+    });
+  });
 });
 
 describe("EmbeddedListField — reference column populated via useQuery", () => {

package/src/components/__tests__/render-field-money-embedded-list-consistency.test.tsx

@@ -0,0 +1,212 @@
+// kumiko-framework#1972: one form, two money contracts. A top-level money
+// field's write payload is `{amount, currency}` in MAJOR units
+// (render-field.tsx's moneyPayload) while an embedded-list row's money
+// sub-field is a bare number in MINOR units (embedded-list-field.tsx passes
+// the widget's minor-unit value straight through — currency lives on the
+// head aggregate, not the row). Both are correct in isolation; the risk is
+// a consumer that reads the combined payload and compares the two amounts
+// without converting units first (exactly the reported solon incident:
+// `linesSum:10000` vs `netTotal:100`).
+//
+// This test drives BOTH real conversion paths — RenderField's moneyPayload
+// for the top-level field, EmbeddedListField's handleCellChange for the
+// list rows — with a crooked amount (not a round number, which can hide a
+// factor-of-100 bug by coincidence), assembles the resulting wire payload
+// exactly like a real form submission would, and validates it against the
+// real server schema (buildInsertSchema + EmbeddedFieldDef.totalsMatch). No
+// hand-built wire-form fixture stands in for either conversion function.
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildInsertSchema,
+  createEmbeddedListField,
+  createEntity,
+  createMoneyField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { computeEditViewModel, type EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import {
+  type CorePrimitives,
+  type EmbeddedListInputProps,
+  type InputProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { RenderField } from "../render-field";
+
+let capturedInput: InputProps | undefined;
+let capturedList: EmbeddedListInputProps | undefined;
+let lastTotalPayload: unknown;
+let lastLinesPayload: unknown;
+
+const captureInput: ComponentType<InputProps> = (props) => {
+  capturedInput = props;
+  return null;
+};
+const captureEmbeddedListInput: ComponentType<EmbeddedListInputProps> = (props) => {
+  capturedList = props;
+  return null;
+};
+const onTotalChange = (v: unknown): void => {
+  lastTotalPayload = v;
+};
+const onLinesChange = (v: unknown): void => {
+  lastLinesPayload = v;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: noop,
+  Field: passChildren,
+  Input: captureInput,
+  EmbeddedListInput: captureEmbeddedListInput,
+  DataTable: noop,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function invoiceEntity(): EntityDefinition {
+  return createEntity({
+    table: "Invoices",
+    fields: {
+      total: createMoneyField({ required: true }),
+      lines: createEmbeddedListField(
+        { amount: { type: "money", required: true } },
+        { totalsMatch: { amount: "total" } },
+      ),
+    },
+    defaultCurrency: "EUR",
+  });
+}
+
+function invoiceScreen(): EntityEditScreenDefinition {
+  return {
+    id: "invoice-edit",
+    type: "entityEdit",
+    entity: "invoice",
+    layout: { sections: [{ columns: 1, fields: ["total", "lines"] }] },
+  } as EntityEditScreenDefinition;
+}
+
+function computeInvoiceFields(
+  entity: EntityDefinition,
+  values: Record<string, unknown>,
+): { readonly total: EditFieldViewModel; readonly lines: EditFieldViewModel } {
+  const vm = computeEditViewModel({
+    screen: invoiceScreen(),
+    entity,
+    values,
+    translate: (key) => key,
+    featureName: "invoices",
+  });
+  const section = vm.sections[0];
+  if (section === undefined || section.kind !== "fields") {
+    throw new Error("expected a fields section");
+  }
+  const total = section.fields.find((f) => f.field === "total");
+  const lines = section.fields.find((f) => f.field === "lines");
+  if (total === undefined || lines === undefined) {
+    throw new Error("expected total + lines fields");
+  }
+  return { total, lines };
+}
+
+// Mounts both fields fresh against the given values and re-captures their
+// widget props. Called again after every simulated edit — a real controlled
+// form re-renders with the previous onChange result fed back in the same
+// way, so this mirrors that instead of mutating one long-lived tree.
+function renderInvoiceForm(entity: EntityDefinition, values: Record<string, unknown>): void {
+  capturedInput = undefined;
+  capturedList = undefined;
+  const { total, lines } = computeInvoiceFields(entity, values);
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
+      <PrimitivesProvider value={testPrimitives}>
+        <RenderField field={total} onChange={onTotalChange} />
+        <RenderField field={lines} onChange={onLinesChange} featureName="invoices" />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+  if (capturedInput === undefined) {
+    throw new Error("total field did not render an Input");
+  }
+  if (capturedList === undefined) {
+    throw new Error("lines field did not render an EmbeddedListInput");
+  }
+}
+
+// Mirrors what MoneyInput actually emits on blur: the widget's minor-units
+// value. `InputProps` is a discriminated union keyed by `kind`, so the
+// money-typed onChange only narrows to a callable signature once `kind` is
+// checked.
+function emitMoneyChange(minorUnits: number): void {
+  if (capturedInput === undefined) throw new Error("no Input captured");
+  if (capturedInput.kind !== "money") throw new Error("expected a money Input");
+  capturedInput.onChange(minorUnits);
+}
+
+describe("RenderField money contract consistency across top-level + embedded-list (kumiko-framework#1972)", () => {
+  test("a crooked invoice total (1234.56 EUR) whose line amounts sum to the same value validates end to end", () => {
+    const entity = invoiceEntity();
+
+    // Two rows, edited one at a time via the widget's real onCellChange
+    // (minor units) — each edit re-renders with the previous result fed
+    // back in as `lines`, exactly like a real controlled form.
+    renderInvoiceForm(entity, { lines: [{}, {}] });
+    capturedList?.onCellChange(0, "amount", 100_000); // 1000.00 EUR
+    expect(lastLinesPayload).toEqual([{ amount: 100_000 }, {}]);
+
+    renderInvoiceForm(entity, { lines: lastLinesPayload as Record<string, unknown>[] });
+    capturedList?.onCellChange(1, "amount", 23_456); // 234.56 EUR
+    expect(lastLinesPayload).toEqual([{ amount: 100_000 }, { amount: 23_456 }]);
+
+    // Top-level total: the widget (MoneyInput) emits minor units on blur;
+    // RenderField's moneyPayload converts that to the wire's major-unit
+    // object.
+    emitMoneyChange(123_456); // 1234.56 EUR, minor units
+    expect(lastTotalPayload).toEqual({ amount: 1234.56, currency: "EUR" });
+
+    const result = buildInsertSchema(entity).safeParse({
+      total: lastTotalPayload,
+      lines: lastLinesPayload,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("a genuinely wrong total (mismatched, not just a unit mixup) is still rejected", () => {
+    const entity = invoiceEntity();
+    renderInvoiceForm(entity, { lines: [{}] });
+    capturedList?.onCellChange(0, "amount", 100_000); // 1000.00 EUR
+    expect(lastLinesPayload).toEqual([{ amount: 100_000 }]);
+
+    emitMoneyChange(50_000); // user enters 500.00 EUR — doesn't match the line
+    expect(lastTotalPayload).toEqual({ amount: 500, currency: "EUR" });
+
+    const result = buildInsertSchema(entity).safeParse({
+      total: lastTotalPayload,
+      lines: lastLinesPayload,
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.some((issue) => issue.path.join(".") === "lines")).toBe(true);
+    }
+  });
+});