@cosmicdrift/kumiko-renderer 0.240.0 → 0.242.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.240.0",
+  "version": "0.242.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.240.0",
-    "@cosmicdrift/kumiko-headless": "0.240.0",
+    "@cosmicdrift/kumiko-framework": "0.242.0",
+    "@cosmicdrift/kumiko-headless": "0.242.0",
     "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.240.0"
+    "@cosmicdrift/kumiko-locale-de": "0.242.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/projection-detail-singleton.test.tsx

@@ -0,0 +1,191 @@
+// fw#2312: `singleton: true` marks a projectionDetail screen whose query
+// determines the shown row from the caller's session/context instead of a
+// row id in the path (a self-service "my profile"/"my data" screen has no
+// row to link to). Before this flag, ProjectionDetailBody always rendered
+// the "needs a row id in the path" error banner when `entityId` was
+// undefined (kumiko-screen.tsx) — both user-profile and user-data-rights'
+// privacy-center screen hit exactly that, unrenderable, until the flag
+// existed (fw#2312 bug report). This proves the fix, the no-flag regression
+// case stays covered, and that a stray/spoofed path id never reaches the
+// query under singleton (renderer-side half of the security requirement —
+// the boot-validator half lives in framework's projection-detail-
+// singleton.test.ts).
+
+import { describe, expect, test } from "bun:test";
+import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { UserRolesProvider } from "../../context/user-roles-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type BannerProps,
+  type CorePrimitives,
+  type FormProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { AppFeaturesProvider } from "../app-features-context";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi } from "../nav";
+import { NavProvider } from "../nav";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const FormWithActions: ComponentType<FormProps> = ({ children }) => (
+  <div data-testid="form-body">{children}</div>
+);
+
+const TestBanner: ComponentType<BannerProps> = ({ children, testId }) => (
+  <div data-testid={testId}>{children}</div>
+);
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: TestBanner,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: FormWithActions,
+  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 stubDispatcher(
+  record: Readonly<Record<string, unknown>> | null,
+  queries: Array<{ type: string; payload: unknown }>,
+): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string, payload: unknown) => {
+      queries.push({ type, payload });
+      return { isSuccess: true, data: record };
+    }) 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: () => [],
+  };
+}
+
+function meScreen(
+  overrides?: Partial<ProjectionDetailScreenDefinition>,
+): FeatureSchema["screens"][number] {
+  return {
+    id: "profile",
+    type: "projectionDetail",
+    query: "app:query:me",
+    layout: { sections: [{ title: "s", fields: ["name"] }] },
+    ...overrides,
+  } as FeatureSchema["screens"][number];
+}
+
+function renderScreen(opts: {
+  readonly screen: FeatureSchema["screens"][number];
+  readonly entityId?: string;
+  readonly queries: Array<{ type: string; payload: unknown }>;
+  readonly record?: Readonly<Record<string, unknown>> | null;
+}): ReturnType<typeof render> {
+  const schema: FeatureSchema = { featureName: "app", entities: {}, screens: [opts.screen] };
+  const navApi: NavApi = {
+    route: { screenId: "app:screen:profile" },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: () => {},
+  };
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider
+        dispatcher={stubDispatcher(
+          opts.record !== undefined ? opts.record : { id: "u1", name: "Ada" },
+          opts.queries,
+        )}
+      >
+        <AppFeaturesProvider features={[schema]}>
+          <UserRolesProvider roles={[]}>
+            <NavProvider value={navApi}>
+              <PrimitivesProvider value={testPrimitives}>
+                <KumikoScreen
+                  schema={schema}
+                  qn="app:screen:profile"
+                  {...(opts.entityId !== undefined && { entityId: opts.entityId })}
+                />
+              </PrimitivesProvider>
+            </NavProvider>
+          </UserRolesProvider>
+        </AppFeaturesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionDetail singleton (fw#2312)", () => {
+  test("singleton + no path id renders the record instead of the missing-id banner", async () => {
+    const queries: Array<{ type: string; payload: unknown }> = [];
+    const { queryByTestId, getByTestId } = renderScreen({
+      screen: meScreen({ singleton: true }),
+      queries,
+    });
+
+    await waitFor(() => expect(getByTestId("form-body")).toBeTruthy());
+    expect(queryByTestId("kumiko-screen-projection-detail-missing-id")).toBeNull();
+    expect(queries).toEqual([{ type: "app:query:me", payload: {} }]);
+  });
+
+  test("no singleton flag + no path id still shows the missing-id banner (no regression)", async () => {
+    const queries: Array<{ type: string; payload: unknown }> = [];
+    const { getByTestId } = renderScreen({ screen: meScreen(), queries });
+
+    await waitFor(() =>
+      expect(getByTestId("kumiko-screen-projection-detail-missing-id")).toBeTruthy(),
+    );
+  });
+
+  test("singleton ignores a stray path id — the query never receives it", async () => {
+    const queries: Array<{ type: string; payload: unknown }> = [];
+    const { getByTestId } = renderScreen({
+      screen: meScreen({ singleton: true }),
+      entityId: "attacker-controlled-id",
+      queries,
+    });
+
+    await waitFor(() => expect(getByTestId("form-body")).toBeTruthy());
+    expect(queries).toEqual([{ type: "app:query:me", payload: {} }]);
+  });
+
+  test("singleton + record-not-found banner never shows the (ignored) path id", async () => {
+    const queries: Array<{ type: string; payload: unknown }> = [];
+    const { getByTestId } = renderScreen({
+      screen: meScreen({ singleton: true }),
+      entityId: "99",
+      record: null,
+      queries,
+    });
+
+    const banner = await waitFor(() => getByTestId("kumiko-screen-record-missing"));
+    expect(banner.textContent).toBe("Record not found.");
+    expect(banner.textContent).not.toContain("99");
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -2076,6 +2076,12 @@ function ProjectionDetailBody({
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
   const idParam = screen.idParam ?? "id";
+  // Singleton screens ignore whatever id the path happens to carry — the
+  // server picks the row from session/context, so forwarding a path id
+  // (even a stray/spoofed one) into the query or into extension sections'
+  // entityId fallback (resolveExtensionEntityId in render-edit.tsx) would
+  // let a client-controlled value leak where none is meant to reach.
+  const effectiveEntityId = screen.singleton === true ? undefined : entityId;
   const isTabsMode = screen.layout.mode === "tabs";
   const activeSection = useMemo(() => {
     if (!isTabsMode || Tabs === undefined) return undefined;
@@ -2104,7 +2110,7 @@ function ProjectionDetailBody({
   }, [screen, activeSection]);
   const detailQuery = useQuery<Readonly<Record<string, unknown>>>(
     screen.query,
-    entityId !== undefined ? { [idParam]: entityId } : {},
+    effectiveEntityId !== undefined ? { [idParam]: effectiveEntityId } : {},
   );
 
   // A writeForm section's handler creates a new record (see EditWriteFormSection's
@@ -2157,9 +2163,12 @@ function ProjectionDetailBody({
       label: effectiveTranslate("kumiko.actions.edit"),
       icon: resolveActionIcon("edit"),
       onPress: () =>
-        nav.navigate({ screenId: targetScreenId, ...(entityId !== undefined && { entityId }) }),
+        nav.navigate({
+          screenId: targetScreenId,
+          ...(effectiveEntityId !== undefined && { entityId: effectiveEntityId }),
+        }),
     };
-  }, [editScreen, effectiveTranslate, nav, entityId]);
+  }, [editScreen, effectiveTranslate, nav, effectiveEntityId]);
 
   const headerActions = useMemo((): readonly RenderEditAction[] | undefined => {
     const record = detailQuery.data ?? {};
@@ -2282,7 +2291,7 @@ function ProjectionDetailBody({
     detailQuery.refetch,
   ]);
 
-  if (entityId === undefined) {
+  if (effectiveEntityId === undefined && screen.singleton !== true) {
     return (
       <Banner padded variant="error" testId="kumiko-screen-projection-detail-missing-id">
         Screen <Text variant="code">{screen.id}</Text> (projectionDetail) needs a row id in the path
@@ -2308,7 +2317,13 @@ function ProjectionDetailBody({
   if (!record) {
     return (
       <Banner padded variant="error" testId="kumiko-screen-record-missing">
-        Record <Text variant="code">{entityId}</Text> not found.
+        {screen.singleton === true ? (
+          "Record not found."
+        ) : (
+          <>
+            Record <Text variant="code">{entityId}</Text> not found.
+          </>
+        )}
       </Banner>
     );
   }
@@ -2397,7 +2412,7 @@ function ProjectionDetailBody({
       entity={entity}
       featureName={schema.featureName}
       initial={record as FormValues}
-      entityId={entityId}
+      entityId={effectiveEntityId}
       customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
       onReload={reloadDetail}
       {...(headerActions !== undefined && { actions: headerActions })}

package/src/components/__tests__/related-list-section.test.tsx

@@ -3,7 +3,7 @@ import type { RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher, EditRelatedListSectionViewModel } from "@cosmicdrift/kumiko-headless";
 import { render, screen as rtlScreen, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
-import { NavProvider } from "../../app/nav";
+import { type NavApi, NavProvider } from "../../app/nav";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
 import { kumikoDefaultTranslations } from "../../i18n-defaults";
@@ -26,22 +26,27 @@ const testSection: ComponentType<SectionProps> = ({ testId, children }) => (
 // wired straight to the action's onTrigger — enough to prove
 // RelatedListSection wires rowActions through to a real dispatch, without
 // needing the production DataTable's sorting/paging/kebab-menu chrome.
+// The isVisible filter mirrors the production DataTable's own row-action
+// filter (renderer-web primitives/index.tsx) so per-row gating is exercised
+// here rather than assumed.
 const testDataTable: ComponentType<DataTableProps> = ({ rows, rowActions }) => (
   <table>
     <tbody>
       {rows.map((row) => (
         <tr key={row.id} data-testid={`row-${row.id}`}>
           <td>
-            {(rowActions ?? []).map((action) => (
-              <button
-                key={action.id}
-                type="button"
-                data-testid={`action-${action.id}-${row.id}`}
-                onClick={() => void action.onTrigger(row)}
-              >
-                {action.label}
-              </button>
-            ))}
+            {(rowActions ?? [])
+              .filter((action) => action.isVisible === undefined || action.isVisible(row))
+              .map((action) => (
+                <button
+                  key={action.id}
+                  type="button"
+                  data-testid={`action-${action.id}-${row.id}`}
+                  onClick={() => void action.onTrigger(row)}
+                >
+                  {action.label}
+                </button>
+              ))}
           </td>
         </tr>
       ))}
@@ -74,7 +79,7 @@ function testPrimitives(): CorePrimitives {
   } as unknown as CorePrimitives;
 }
 
-function stubDispatcher(): {
+function stubDispatcher(rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }]): {
   dispatcher: Dispatcher;
   writes: Array<{ type: string; payload: unknown }>;
   queryCount: () => number;
@@ -88,10 +93,7 @@ function stubDispatcher(): {
     }) as Dispatcher["write"],
     query: (async () => {
       queryCalls += 1;
-      return {
-        isSuccess: true,
-        data: { rows: [{ id: "r1", name: "Alice" }], nextCursor: null },
-      };
+      return { isSuccess: true, data: { rows, nextCursor: null } };
     }) as Dispatcher["query"],
     batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
     statusStore: {
@@ -105,6 +107,28 @@ function stubDispatcher(): {
   return { dispatcher, writes, queryCount: () => queryCalls };
 }
 
+function stubNav(): {
+  nav: NavApi;
+  navigations: unknown[];
+  searchParams: Array<Record<string, string | null>>;
+} {
+  const navigations: unknown[] = [];
+  const searchParams: Array<Record<string, string | null>> = [];
+  const nav: NavApi = {
+    route: undefined,
+    navigate: (target: unknown) => {
+      navigations.push(target);
+    },
+    replace: noop,
+    hrefFor: () => "#",
+    searchParams: {},
+    setSearchParams: (params: Record<string, string | null>) => {
+      searchParams.push(params);
+    },
+  } as unknown as NavApi;
+  return { nav, navigations, searchParams };
+}
+
 const rowActions: readonly RowAction[] = [
   {
     id: "resend",
@@ -122,7 +146,11 @@ const historySection: EditRelatedListSectionViewModel = {
   rowActions,
 };
 
-function renderRelatedList(dispatcher: Dispatcher) {
+function renderRelatedList(
+  dispatcher: Dispatcher,
+  section: EditRelatedListSectionViewModel = historySection,
+  nav: NavApi = stubNav().nav,
+) {
   return render(
     <LocaleProvider
       resolver={createStaticLocaleResolver({ locale: "en-US" })}
@@ -130,17 +158,8 @@ function renderRelatedList(dispatcher: Dispatcher) {
     >
       <DispatcherProvider dispatcher={dispatcher}>
         <PrimitivesProvider value={testPrimitives()}>
-          <NavProvider
-            value={{
-              route: undefined,
-              navigate: noop,
-              replace: noop,
-              hrefFor: () => "#",
-              searchParams: {},
-              setSearchParams: noop,
-            }}
-          >
-            <RelatedListSection section={historySection} parentId="order-1" featureName="orders" />
+          <NavProvider value={nav}>
+            <RelatedListSection section={section} parentId="order-1" featureName="orders" />
           </NavProvider>
         </PrimitivesProvider>
       </DispatcherProvider>
@@ -160,4 +179,61 @@ describe("RelatedListSection — rowActions", () => {
     expect(writes[0]).toEqual({ type: "orders:write:resend", payload: { id: "r1" } });
     await waitFor(() => expect(queryCount()).toBe(2));
   });
+
+  test("a navigate row action targets its screen and carries the clicked row's own values as search params", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
+    const { nav, navigations, searchParams } = stubNav();
+    renderRelatedList(
+      dispatcher,
+      {
+        kind: "relatedList",
+        title: "Positions",
+        query: "lease:query:items:list",
+        columns: [{ field: "name" }],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "adjust-rent",
+            label: "actions.adjustRent",
+            screen: "adjust-rent-form",
+            params: { map: { itemId: "id", currentAmount: "amount" } },
+          },
+        ],
+      },
+      nav,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
+    rtlScreen.getByTestId("action-adjust-rent-item-7").click();
+
+    await waitFor(() => expect(navigations).toHaveLength(1));
+    expect(navigations[0]).toEqual({ screenId: "adjust-rent-form" });
+    expect(searchParams).toEqual([{ itemId: "item-7", currentAmount: "1200" }]);
+  });
+
+  test("a row action with a visible condition renders only on the rows that satisfy it", async () => {
+    const { dispatcher } = stubDispatcher([
+      { id: "active-1", name: "Running", status: "active" },
+      { id: "ended-1", name: "Closed", status: "ended" },
+    ]);
+    renderRelatedList(dispatcher, {
+      kind: "relatedList",
+      title: "Positions",
+      query: "lease:query:items:list",
+      columns: [{ field: "name" }],
+      rowActions: [
+        {
+          id: "end-item",
+          label: "actions.endItem",
+          handler: "lease:write:end-item",
+          payload: { pick: ["id"] },
+          visible: { field: "status", eq: "active" },
+        },
+      ],
+    });
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-ended-1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("action-end-item-active-1")).toBeTruthy();
+    expect(rtlScreen.queryByTestId("action-end-item-ended-1")).toBeNull();
+  });
 });

package/src/components/__tests__/render-field-json-format.test.tsx

@@ -0,0 +1,164 @@
+// fw#2312: readOnly fields with `field.renderer: { format: "json" }` (audit
+// payload/metadata, job logs) must hand the RAW value to a registered
+// JsonView primitive — applyFormatSpec's already-indented string is only
+// the fallback for a primitives-provider without JsonView (e.g. an app
+// predating this rollout). "children contains \n" is not a discriminating
+// assertion here (applyFormatSpec already returns a real newline string
+// today) — the test instead checks that JsonView is actually invoked and
+// receives the structured value, not a flattened string.
+//
+// Capture-primitives instead of real ones, same pattern as
+// render-field-unit-format.test.tsx.
+
+import { describe, expect, test } from "bun:test";
+import 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 JsonViewProps,
+  PrimitivesProvider,
+  type TextProps,
+} from "../../primitives";
+import { RenderField } from "../render-field";
+
+let capturedJsonView: JsonViewProps | undefined;
+const captureJsonView: ComponentType<JsonViewProps> = (props) => {
+  capturedJsonView = props;
+  return null;
+};
+
+let capturedText: TextProps | undefined;
+const captureText: ComponentType<TextProps> = (props) => {
+  capturedText = props;
+  return null;
+};
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const basePrimitives: Omit<CorePrimitives, "Text" | "JsonView"> = {
+  Button: noop,
+  // Passes children through (not noop): the "unsupported jsonb" fallback
+  // path wraps its Text/JsonView content in <Banner>, so a Banner that
+  // swallows children would silently never mount them, making those
+  // captures a no-op regardless of which branch RenderField actually took.
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: noop,
+  Section: noop,
+  Card: noop,
+  Grid: noop,
+  GridCell: noop,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+const primitivesWithJsonView: CorePrimitives = {
+  ...basePrimitives,
+  Text: captureText,
+  JsonView: captureJsonView,
+};
+
+const primitivesWithoutJsonView: CorePrimitives = {
+  ...basePrimitives,
+  Text: captureText,
+};
+
+function payloadField(
+  value: unknown,
+  renderer: EditFieldViewModel["renderer"] = { format: "json" },
+): EditFieldViewModel {
+  return {
+    field: "payload",
+    label: "Payload",
+    type: "jsonb",
+    value,
+    visible: true,
+    readOnly: true,
+    required: false,
+    renderer,
+  };
+}
+
+// No `renderer` key at all (not even `renderer: undefined`, which a default
+// parameter would still override) — this is the "no author-declared
+// FieldRenderer" case that falls through to renderInput's jsonb/embedded/
+// files/images fallback banner instead of FieldRendererOutput.
+function unrenderedJsonbField(value: unknown): EditFieldViewModel {
+  return {
+    field: "payload",
+    label: "Payload",
+    type: "jsonb",
+    value,
+    visible: true,
+    readOnly: true,
+    required: false,
+  };
+}
+
+function renderPayload(primitives: CorePrimitives, field: EditFieldViewModel): void {
+  capturedJsonView = undefined;
+  capturedText = undefined;
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "en-US" })}>
+      <PrimitivesProvider value={primitives}>
+        <RenderField field={field} onChange={() => {}} />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderField — format: json (fw#2312)", () => {
+  test("mit registriertem JsonView bekommt es den rohen, strukturierten Wert — keinen flachen String", () => {
+    const value = { user: { id: 1, roles: ["admin", "billing"] } };
+    renderPayload(primitivesWithJsonView, payloadField(value));
+    expect(capturedJsonView?.value).toBe(value);
+    expect(typeof capturedJsonView?.value).toBe("object");
+    expect(capturedText).toBeUndefined();
+  });
+
+  test("renderer.indent wird an JsonView durchgereicht", () => {
+    renderPayload(primitivesWithJsonView, payloadField({ a: 1 }, { format: "json", indent: 4 }));
+    expect(capturedJsonView?.indent).toBe(4);
+  });
+
+  test("ohne registriertes JsonView fällt es auf Text mit dem von applyFormatSpec formatierten String zurück", () => {
+    const value = { a: 1 };
+    renderPayload(primitivesWithoutJsonView, payloadField(value));
+    expect(capturedJsonView).toBeUndefined();
+    expect(capturedText?.children).toBe(JSON.stringify(value, null, 2));
+  });
+
+  test("ein zirkulärer Wert erreicht JsonView unverändert — die Aufbereitung ist Sache der Primitive-Implementierung, nicht von RenderField", () => {
+    const circular: Record<string, unknown> = { name: "job-1" };
+    circular["self"] = circular;
+    expect(() => renderPayload(primitivesWithJsonView, payloadField(circular))).not.toThrow();
+    expect(capturedJsonView?.value).toBe(circular);
+  });
+});
+
+describe("RenderField — unsupported jsonb/embedded/files/images Fallback-Banner (fw#2312)", () => {
+  test("mit registriertem JsonView zeigt der Banner den Wert strukturiert statt als JSON.stringify-Einzeiler", () => {
+    const value = { assignee: "user-1", tags: ["a", "b"] };
+    renderPayload(primitivesWithJsonView, unrenderedJsonbField(value));
+    expect(capturedJsonView?.value).toBe(value);
+    expect(capturedText).toBeUndefined();
+  });
+
+  test("ohne registriertes JsonView fällt der Banner auf Text variant=code mit dem alten Einzeiler zurück", () => {
+    const value = { assignee: "user-1" };
+    renderPayload(primitivesWithoutJsonView, unrenderedJsonbField(value));
+    expect(capturedJsonView).toBeUndefined();
+    expect(capturedText?.children).toBe(JSON.stringify(value));
+    expect(capturedText?.variant).toBe("code");
+  });
+});

package/src/components/__tests__/write-form-section.test.tsx

@@ -17,8 +17,8 @@ import { WriteFormSection } from "../write-form-section";
 const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
 const noop = () => {};
 
-const testButton: ComponentType<ButtonProps> = ({ children, onClick, testId, disabled }) => (
-  <button type="button" data-testid={testId} onClick={onClick} disabled={disabled}>
+const testButton: ComponentType<ButtonProps> = ({ children, onClick, testId, disabled, icon }) => (
+  <button type="button" data-testid={testId} data-icon={icon} onClick={onClick} disabled={disabled}>
     {children}
   </button>
 );
@@ -40,8 +40,15 @@ const testBanner: ComponentType<BannerProps> = ({ children, testId }) => (
   <div data-testid={testId}>{children}</div>
 );
 
-const testSection: ComponentType<SectionProps> = ({ testId, children }) => (
-  <div data-testid={testId}>{children}</div>
+// Mirrors DefaultSection's real actions slot closely enough to let tests
+// assert the submit button lands in the footer, not the body (fw#2675).
+const testSection: ComponentType<SectionProps> = ({ testId, children, actions }) => (
+  <div data-testid={testId}>
+    <div data-testid={testId !== undefined ? `${testId}-body` : undefined}>{children}</div>
+    {actions !== undefined && (
+      <div data-testid={testId !== undefined ? `${testId}-actions` : undefined}>{actions}</div>
+    )}
+  </div>
 );
 
 function testPrimitives(): CorePrimitives {
@@ -129,6 +136,19 @@ function renderWriteForm(
 }
 
 describe("WriteFormSection", () => {
+  test("submit button renders in the section's actions footer, not the body (fw#2675)", () => {
+    const { dispatcher } = stubDispatcher();
+    renderWriteForm(noteSection, dispatcher, noop);
+
+    const actions = rtlScreen.getByTestId("write-form-Add note-actions");
+    const body = rtlScreen.getByTestId("write-form-Add note-body");
+    const button = rtlScreen.getByTestId("write-form-section-submit");
+
+    expect(actions.contains(button)).toBe(true);
+    expect(body.contains(button)).toBe(false);
+    expect(button.dataset["icon"]).toBe("check");
+  });
+
   test("submit dispatches through the section's configured write handler with the entered values", async () => {
     const { dispatcher, writes } = stubDispatcher();
     let submittedCount = 0;

package/src/components/render-field.tsx

@@ -83,7 +83,7 @@ export function RenderField({
   valueDisplay = "form",
   row,
 }: RenderFieldProps): ReactNode {
-  const { Field, Input, Banner, Text } = usePrimitives();
+  const { Field, Input, Banner, Text, JsonView } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
   // navigator.language (Browser-Sprache) zurück statt der gewählten
   // App-Sprache. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
@@ -137,7 +137,19 @@ export function RenderField({
     ) : readOnlyText && !isComplexFieldType(field.type) ? (
       <Text testId={`field-value-${field.field}`}>{readOnlyDisplayText(field, appLocale)}</Text>
     ) : (
-      renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, t, row })
+      renderInput({
+        field,
+        id,
+        hasError,
+        onChange,
+        Input,
+        appLocale,
+        Banner,
+        Text,
+        JsonView,
+        t,
+        row,
+      })
     );
 
   return (
@@ -351,7 +363,7 @@ function FieldRendererOutput({
   readonly row?: Readonly<Record<string, unknown>>;
   readonly appLocale: string;
 }): ReactNode {
-  const { Text } = usePrimitives();
+  const { Text, JsonView } = usePrimitives();
   const t = useTranslation();
   const componentName =
     !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
@@ -359,6 +371,18 @@ function FieldRendererOutput({
       : undefined;
   const Component = useColumnRenderer(componentName);
   if (isFormatSpec(renderer)) {
+    // format:"json" wants the raw value (JsonView stringifies + highlights
+    // itself) — applyFormatSpec's already-indented string is only the
+    // fallback for primitives-providers without JsonView (fw#2312).
+    if (renderer.format === "json" && JsonView !== undefined) {
+      return (
+        <JsonView
+          value={field.value}
+          indent={renderer.indent}
+          testId={`field-value-${field.field}`}
+        />
+      );
+    }
     // App locale as default when the FormatSpec declares none of its own —
     // otherwise locale-sensitive formats (timestamp/date/number/decimal/
     // bigInt/unit) fell back to Intl's runtime default instead of the app
@@ -495,6 +519,7 @@ function renderInput({
   appLocale,
   Banner,
   Text,
+  JsonView,
   t,
   row,
 }: {
@@ -506,6 +531,7 @@ function renderInput({
   readonly appLocale: string;
   readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
   readonly Text: ReturnType<typeof usePrimitives>["Text"];
+  readonly JsonView: ReturnType<typeof usePrimitives>["JsonView"];
   readonly t: ReturnType<typeof useTranslation>;
   readonly row?: Readonly<Record<string, unknown>>;
 }): ReactNode {
@@ -710,7 +736,12 @@ function renderInput({
       return (
         <Banner id={id} variant="info">
           {t("kumiko.field.unsupported")}
-          {hasValue && <Text variant="code">{JSON.stringify(field.value)}</Text>}
+          {hasValue &&
+            (JsonView !== undefined ? (
+              <JsonView value={field.value} testId={`field-value-${field.field}`} />
+            ) : (
+              <Text variant="code">{JSON.stringify(field.value)}</Text>
+            ))}
         </Banner>
       );
     }

package/src/components/write-form-section.tsx

@@ -129,25 +129,35 @@ export function WriteFormSection({
           {error}
         </Banner>
       )}
-      <Button
-        type="button"
-        variant="primary"
-        disabled={isSubmitting}
-        loading={isSubmitting}
-        onClick={() => void handleSubmit()}
-        testId="write-form-section-submit"
-      >
-        {section.submitLabel ?? effectiveTranslate("kumiko.actions.save")}
-      </Button>
     </>
   );
 
-  if (hideTitle || section.title === undefined) return content;
+  // type="button" (not "submit") is load-bearing: this section is deliberately
+  // NOT a nested <form> (see the component doc above), so a "submit" type
+  // would instead trigger the host RenderEdit's own form submit.
+  const submitButton = (
+    <Button
+      type="button"
+      variant="primary"
+      icon="check"
+      disabled={isSubmitting}
+      loading={isSubmitting}
+      onClick={() => void handleSubmit()}
+      testId="write-form-section-submit"
+    >
+      {section.submitLabel ?? effectiveTranslate("kumiko.actions.save")}
+    </Button>
+  );
+
+  // Routed through Section's `actions` slot (same mechanism render-edit.tsx
+  // uses via Form's `actions`) so the button gets the established right-
+  // aligned footer treatment instead of stretching full-width inline.
   return (
     <Section
-      title={section.title}
+      {...(!hideTitle && section.title !== undefined && { title: section.title })}
       {...(section.icon !== undefined && { icon: section.icon })}
-      testId={`write-form-${section.title}`}
+      actions={submitButton}
+      testId={`write-form-${section.title ?? "section"}`}
     >
       {content}
     </Section>

package/src/index.ts

@@ -190,6 +190,7 @@ export type {
   GridProps,
   HeadingProps,
   InputProps,
+  JsonViewProps,
   LightboxProps,
   LinkProps,
   MetricProps,

package/src/primitives.tsx

@@ -448,8 +448,9 @@ export type InputProps =
       readonly name: string;
       readonly value: string;
       readonly onChange: (v: string) => void;
-      /** Anzahl sichtbarer Zeilen. Default 4 in der Default-Primitive
-       *  — hinreichend für Notes, vertikal-scrollbar drüber. */
+      /** Visible rows. Acts as a minimum height — the field starts this tall
+       *  and still grows with its content. Omitted, the default primitive
+       *  falls back to its own floor (#2677). */
       readonly rows?: number;
       readonly disabled?: boolean;
       readonly required?: boolean;
@@ -1059,6 +1060,17 @@ export type MetricProps = {
   readonly testId?: string;
 };
 
+/** Structured JSON display (audit payload/metadata, job logs, unsupported
+ *  jsonb/embedded field fallback). Takes the raw value, not a pre-stringified
+ *  one — the implementation owns `JSON.stringify` (and must not throw on
+ *  circular refs / BigInt / other non-serializable input). `indent` mirrors
+ *  `JSON.stringify`'s space-count param, default 2. */
+export type JsonViewProps = {
+  readonly value: unknown;
+  readonly indent?: number;
+  readonly testId?: string;
+};
+
 // ---- Core-Registry (Kumiko-eigene Primitives) ----
 
 export type CorePrimitives = {
@@ -1112,6 +1124,10 @@ export type CorePrimitives = {
    *  CorePrimitives mocks in tests keep compiling — additive rollout of
    *  a new primitive shouldn't force every test double to grow a stub. */
   readonly Metric?: ComponentType<MetricProps>;
+  /** Optional (unlike the other Core-Primitives) so existing partial
+   *  CorePrimitives mocks in tests keep compiling — additive rollout of
+   *  a new primitive shouldn't force every test double to grow a stub. */
+  readonly JsonView?: ComponentType<JsonViewProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern