@cosmicdrift/kumiko-renderer-web 0.225.0 → 0.227.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.225.0",
+  "version": "0.227.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.225.0",
-    "@cosmicdrift/kumiko-headless": "0.225.0",
-    "@cosmicdrift/kumiko-renderer": "0.225.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.227.0",
+    "@cosmicdrift/kumiko-headless": "0.227.0",
+    "@cosmicdrift/kumiko-renderer": "0.227.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -64,7 +64,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.225.0"
+    "@cosmicdrift/kumiko-locale-de": "0.227.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/kumiko-screen-singleton-entity-edit.test.tsx

@@ -0,0 +1,237 @@
+import { describe, expect, mock, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import type { FeatureSchema } from "@cosmicdrift/kumiko-renderer";
+import {
+  DispatcherProvider,
+  KumikoScreen,
+  kumikoDefaultTranslations,
+} from "@cosmicdrift/kumiko-renderer";
+import { createMockDispatcher, fireEvent, render, screen, waitFor } from "./test-utils";
+
+// Split out of kumiko-screen.test.tsx (#2495): the create->update submit
+// test below fires fireEvent.change immediately followed by fireEvent.click
+// right after an async data-load settles — exactly the pattern that trips
+// the #457 shared single-process happy-dom event-delegation corruption once
+// enough prior DOM test files have mounted/unmounted in the same process.
+// Isolating just this describe block (not the whole 2600+ line parent file)
+// keeps the coverage/dom blast radius small while still using the codebase's
+// established remedy (bunfig.ci-dom.toml, pathIgnorePatterns in
+// bunfig.dom.toml) for that bug class.
+
+const taskEntity = {
+  fields: {
+    title: { type: "text", required: true },
+    count: { type: "number" },
+    done: { type: "boolean" },
+  },
+} as unknown as EntityDefinition;
+
+function makeDispatcher(overrides: Partial<Dispatcher> = {}): Dispatcher {
+  const base = createMockDispatcher({
+    query: (async () => ({
+      isSuccess: true,
+      data: { rows: [], nextCursor: null },
+    })) as unknown as Dispatcher["query"],
+  });
+  return { ...base, ...overrides };
+}
+
+describe("KumikoScreen: singleton entityEdit", () => {
+  const singletonEdit: EntityEditScreenDefinition = {
+    id: "task-edit",
+    type: "entityEdit",
+    entity: "task",
+    singleton: true,
+    layout: { sections: [{ title: "Basics", fields: ["title"] }] },
+  };
+  const singletonSchema: FeatureSchema = {
+    featureName: "tasks",
+    entities: { task: taskEntity },
+    screens: [singletonEdit],
+  };
+
+  test("kein vorhandener Record → rendert leeres Create-Form", async () => {
+    const queryCalls: { type: string; payload: unknown }[] = [];
+    const dispatcher = makeDispatcher({
+      query: (async (type: string, payload: unknown) => {
+        queryCalls.push({ type, payload });
+        return { isSuccess: true, data: { rows: [], nextCursor: null } };
+      }) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
+    expect(screen.getByTestId("render-edit-form")).toBeTruthy();
+    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+    expect(titleInput.value).toBe("");
+    expect(queryCalls).toEqual([{ type: "tasks:query:task:list", payload: { limit: 1 } }]);
+  });
+
+  test("vorhandener Record → lädt ihn (Update-Form, prefilled) statt Create", async () => {
+    const queryCalls: { type: string; payload: unknown }[] = [];
+    const dispatcher = makeDispatcher({
+      query: (async (type: string, payload: unknown) => {
+        queryCalls.push({ type, payload });
+        if (type.endsWith(":list")) {
+          return {
+            isSuccess: true,
+            data: { rows: [{ id: "task-1", title: "loaded-title" }], nextCursor: null },
+          };
+        }
+        return {
+          isSuccess: true,
+          data: { id: "task-1", version: 1, title: "loaded-title", count: 0, done: false },
+        };
+      }) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
+      </DispatcherProvider>,
+    );
+    // Two sequential loading cycles (list, then detail once the singleton
+    // wrapper hands off to EntityEditUpdateBody) — default waitFor timeout
+    // can be too tight under CI's shared-process test load.
+    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull(), {
+      timeout: 5000,
+    });
+    expect(screen.getByTestId("render-edit-form")).toBeTruthy();
+    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+    expect(titleInput.value).toBe("loaded-title");
+    // Anchor: the id resolved from list(limit:1) reaches the detail query —
+    // otherwise the form would render empty/create-mode instead of loading it.
+    expect(queryCalls).toContainEqual({
+      type: "tasks:query:task:detail",
+      payload: { id: "task-1" },
+    });
+  });
+
+  test("allowCreate:false + leere Tabelle → Fehler-Banner statt Create-Form", async () => {
+    const disabledSchema: FeatureSchema = {
+      featureName: "tasks",
+      entities: { task: taskEntity },
+      screens: [{ ...singletonEdit, allowCreate: false }],
+    };
+    const dispatcher = makeDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: { rows: [], nextCursor: null },
+      })) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={disabledSchema} qn="tasks:screen:task-edit" />
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
+    expect(screen.getByTestId("kumiko-screen-create-disabled")).toBeTruthy();
+    expect(screen.queryByTestId("render-edit-form")).toBeNull();
+  });
+
+  // The singleton wrapper fires its own list(limit:1) query up front — a
+  // screen whose `list` handler has stricter access.roles than its `edit`
+  // handler used to render fine (no query ran before this feature) and now
+  // flips to an error banner instead. No test caught that regression.
+  test("list-Query schlägt fehl → Fehler-Banner statt Create-Form", async () => {
+    const dispatcher = makeDispatcher({
+      query: (async () => ({
+        isSuccess: false,
+        error: {
+          code: "access_denied",
+          httpStatus: 403,
+          i18nKey: "errors.access.denied",
+          message: "",
+        },
+      })) as unknown as Dispatcher["query"],
+    });
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
+    const bannerText = screen.getByTestId("kumiko-screen-error").textContent;
+    expect(bannerText).toBe(kumikoDefaultTranslations["en"]?.["errors.access.denied"] ?? "");
+    expect(screen.queryByTestId("render-edit-form")).toBeNull();
+  });
+
+  // kumiko-screen#1944: EntityEditSingletonBody runs without a wrapping
+  // entityList screen, so the create-body's default "navigate back to the
+  // list" success handler is a silent no-op — a successful create used to
+  // leave the form stuck on the just-submitted create values, and a second
+  // submit created a duplicate record ("exactly one record per tenant"
+  // broken). Create on an empty table must now switch straight to the
+  // update form of the newly created record.
+  test("erfolgreicher Create bei leerer Tabelle wechselt in Update-Form des neuen Records (kein zweiter Create möglich)", async () => {
+    let created = false;
+    const write = mock(async (type: string) => {
+      if (type === "tasks:write:task:create") {
+        created = true;
+        return { isSuccess: true, data: { id: "task-1" } };
+      }
+      return { isSuccess: true, data: {} };
+    });
+    const query = mock(async (type: string) => {
+      if (type === "tasks:query:task:list") {
+        return created
+          ? { isSuccess: true, data: { rows: [{ id: "task-1", title: "Created title" }] } }
+          : { isSuccess: true, data: { rows: [], nextCursor: null } };
+      }
+      if (type === "tasks:query:task:detail") {
+        return {
+          isSuccess: true,
+          data: { id: "task-1", version: 1, title: "Created title", count: 0, done: false },
+        };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    });
+    const dispatcher = makeDispatcher({
+      write: write as unknown as Dispatcher["write"],
+      query: query as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
+      </DispatcherProvider>,
+    );
+    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
+
+    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+    fireEvent.change(titleInput, { target: { value: "Created title" } });
+    fireEvent.click(screen.getByTestId("render-edit-submit"));
+
+    await waitFor(() => expect(write).toHaveBeenCalledTimes(1));
+    // The singleton wrapper refetches its list(limit:1) query after the
+    // create succeeds, sees the new row, and switches from the create body
+    // to the update body — which loads the record via its own detail
+    // query, landing on the same title through a different data path.
+    await waitFor(() => {
+      const input = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+      expect(input.value).toBe("Created title");
+    });
+    expect(query).toHaveBeenCalledWith(
+      "tasks:query:task:detail",
+      { id: "task-1" },
+      expect.anything(),
+    );
+
+    // A second submit on the (now update-mode) form must dispatch an
+    // update, never a second create.
+    fireEvent.change(screen.getByTestId("field-title").querySelector("input") as HTMLInputElement, {
+      target: { value: "Edited again" },
+    });
+    fireEvent.click(screen.getByTestId("render-edit-submit"));
+    // Exactly one create (the first submit) followed by an update, never a
+    // second create — the singleton wrapper must have flipped branches.
+    await waitFor(() => expect(write).toHaveBeenCalledTimes(2));
+    expect(write).toHaveBeenLastCalledWith("tasks:write:task:update", expect.anything());
+  });
+});

package/src/__tests__/kumiko-screen.test.tsx

@@ -2387,201 +2387,10 @@ describe("KumikoScreen: update-only entityEdit (allowCreate/allowDelete)", () =>
 // Singleton entities (exactly one record per tenant) have no nav path
 // that supplies an entityId. `singleton: true` resolves the existing
 // record via list(limit:1) before deciding create vs update.
-describe("KumikoScreen: singleton entityEdit", () => {
-  const singletonEdit: EntityEditScreenDefinition = {
-    id: "task-edit",
-    type: "entityEdit",
-    entity: "task",
-    singleton: true,
-    layout: { sections: [{ title: "Basics", fields: ["title"] }] },
-  };
-  const singletonSchema: FeatureSchema = {
-    featureName: "tasks",
-    entities: { task: taskEntity },
-    screens: [singletonEdit],
-  };
-
-  test("kein vorhandener Record → rendert leeres Create-Form", async () => {
-    const queryCalls: { type: string; payload: unknown }[] = [];
-    const dispatcher = makeDispatcher({
-      query: (async (type: string, payload: unknown) => {
-        queryCalls.push({ type, payload });
-        return { isSuccess: true, data: { rows: [], nextCursor: null } };
-      }) as unknown as Dispatcher["query"],
-    });
-    render(
-      <DispatcherProvider dispatcher={dispatcher}>
-        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
-      </DispatcherProvider>,
-    );
-    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
-    expect(screen.getByTestId("render-edit-form")).toBeTruthy();
-    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
-    expect(titleInput.value).toBe("");
-    expect(queryCalls).toEqual([{ type: "tasks:query:task:list", payload: { limit: 1 } }]);
-  });
-
-  test("vorhandener Record → lädt ihn (Update-Form, prefilled) statt Create", async () => {
-    const queryCalls: { type: string; payload: unknown }[] = [];
-    const dispatcher = makeDispatcher({
-      query: (async (type: string, payload: unknown) => {
-        queryCalls.push({ type, payload });
-        if (type.endsWith(":list")) {
-          return {
-            isSuccess: true,
-            data: { rows: [{ id: "task-1", title: "loaded-title" }], nextCursor: null },
-          };
-        }
-        return {
-          isSuccess: true,
-          data: { id: "task-1", version: 1, title: "loaded-title", count: 0, done: false },
-        };
-      }) as unknown as Dispatcher["query"],
-    });
-    render(
-      <DispatcherProvider dispatcher={dispatcher}>
-        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
-      </DispatcherProvider>,
-    );
-    // Two sequential loading cycles (list, then detail once the singleton
-    // wrapper hands off to EntityEditUpdateBody) — default waitFor timeout
-    // can be too tight under CI's shared-process test load.
-    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull(), {
-      timeout: 5000,
-    });
-    expect(screen.getByTestId("render-edit-form")).toBeTruthy();
-    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
-    expect(titleInput.value).toBe("loaded-title");
-    // Anchor: the id resolved from list(limit:1) reaches the detail query —
-    // otherwise the form would render empty/create-mode instead of loading it.
-    expect(queryCalls).toContainEqual({
-      type: "tasks:query:task:detail",
-      payload: { id: "task-1" },
-    });
-  });
-
-  test("allowCreate:false + leere Tabelle → Fehler-Banner statt Create-Form", async () => {
-    const disabledSchema: FeatureSchema = {
-      featureName: "tasks",
-      entities: { task: taskEntity },
-      screens: [{ ...singletonEdit, allowCreate: false }],
-    };
-    const dispatcher = makeDispatcher({
-      query: (async () => ({
-        isSuccess: true,
-        data: { rows: [], nextCursor: null },
-      })) as unknown as Dispatcher["query"],
-    });
-    render(
-      <DispatcherProvider dispatcher={dispatcher}>
-        <KumikoScreen schema={disabledSchema} qn="tasks:screen:task-edit" />
-      </DispatcherProvider>,
-    );
-    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
-    expect(screen.getByTestId("kumiko-screen-create-disabled")).toBeTruthy();
-    expect(screen.queryByTestId("render-edit-form")).toBeNull();
-  });
-
-  // The singleton wrapper fires its own list(limit:1) query up front — a
-  // screen whose `list` handler has stricter access.roles than its `edit`
-  // handler used to render fine (no query ran before this feature) and now
-  // flips to an error banner instead. No test caught that regression.
-  test("list-Query schlägt fehl → Fehler-Banner statt Create-Form", async () => {
-    const dispatcher = makeDispatcher({
-      query: (async () => ({
-        isSuccess: false,
-        error: {
-          code: "access_denied",
-          httpStatus: 403,
-          i18nKey: "errors.access.denied",
-          message: "",
-        },
-      })) as unknown as Dispatcher["query"],
-    });
-    render(
-      <DispatcherProvider dispatcher={dispatcher}>
-        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
-      </DispatcherProvider>,
-    );
-    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
-    const bannerText = screen.getByTestId("kumiko-screen-error").textContent;
-    expect(bannerText).toBe(kumikoDefaultTranslations["en"]?.["errors.access.denied"] ?? "");
-    expect(screen.queryByTestId("render-edit-form")).toBeNull();
-  });
-
-  // kumiko-screen#1944: EntityEditSingletonBody runs without a wrapping
-  // entityList screen, so the create-body's default "navigate back to the
-  // list" success handler is a silent no-op — a successful create used to
-  // leave the form stuck on the just-submitted create values, and a second
-  // submit created a duplicate record ("exactly one record per tenant"
-  // broken). Create on an empty table must now switch straight to the
-  // update form of the newly created record.
-  test("erfolgreicher Create bei leerer Tabelle wechselt in Update-Form des neuen Records (kein zweiter Create möglich)", async () => {
-    let created = false;
-    const write = mock(async (type: string) => {
-      if (type === "tasks:write:task:create") {
-        created = true;
-        return { isSuccess: true, data: { id: "task-1" } };
-      }
-      return { isSuccess: true, data: {} };
-    });
-    const query = mock(async (type: string) => {
-      if (type === "tasks:query:task:list") {
-        return created
-          ? { isSuccess: true, data: { rows: [{ id: "task-1", title: "Created title" }] } }
-          : { isSuccess: true, data: { rows: [], nextCursor: null } };
-      }
-      if (type === "tasks:query:task:detail") {
-        return {
-          isSuccess: true,
-          data: { id: "task-1", version: 1, title: "Created title", count: 0, done: false },
-        };
-      }
-      return { isSuccess: true, data: { rows: [], nextCursor: null } };
-    });
-    const dispatcher = makeDispatcher({
-      write: write as unknown as Dispatcher["write"],
-      query: query as unknown as Dispatcher["query"],
-    });
-
-    render(
-      <DispatcherProvider dispatcher={dispatcher}>
-        <KumikoScreen schema={singletonSchema} qn="tasks:screen:task-edit" />
-      </DispatcherProvider>,
-    );
-    await waitFor(() => expect(screen.queryByTestId("kumiko-screen-loading")).toBeNull());
-
-    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
-    fireEvent.change(titleInput, { target: { value: "Created title" } });
-    fireEvent.click(screen.getByTestId("render-edit-submit"));
-
-    await waitFor(() => expect(write).toHaveBeenCalledTimes(1));
-    // The singleton wrapper refetches its list(limit:1) query after the
-    // create succeeds, sees the new row, and switches from the create body
-    // to the update body — which loads the record via its own detail
-    // query, landing on the same title through a different data path.
-    await waitFor(() => {
-      const input = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
-      expect(input.value).toBe("Created title");
-    });
-    expect(query).toHaveBeenCalledWith(
-      "tasks:query:task:detail",
-      { id: "task-1" },
-      expect.anything(),
-    );
-
-    // A second submit on the (now update-mode) form must dispatch an
-    // update, never a second create.
-    fireEvent.change(screen.getByTestId("field-title").querySelector("input") as HTMLInputElement, {
-      target: { value: "Edited again" },
-    });
-    fireEvent.click(screen.getByTestId("render-edit-submit"));
-    // Exactly one create (the first submit) followed by an update, never a
-    // second create — the singleton wrapper must have flipped branches.
-    await waitFor(() => expect(write).toHaveBeenCalledTimes(2));
-    expect(write).toHaveBeenLastCalledWith("tasks:write:task:update", expect.anything());
-  });
-});
+// KumikoScreen: singleton entityEdit — moved to
+// kumiko-screen-singleton-entity-edit.test.tsx (#2495): its create->update
+// submit test needs its own isolated bun test process (#457 shared
+// single-process happy-dom event-delegation corruption).
 
 // --- actionForm extension-section (Wave J: Incident-Update-Timeline) ---
 // actionForm hat keinen record — Extension-Sections bekommen stattdessen

package/src/__tests__/projection-detail-record-layout.test.tsx

@@ -6,7 +6,14 @@ import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import type { FeatureSchema, NavApi } from "@cosmicdrift/kumiko-renderer";
 import { DispatcherProvider, KumikoScreen, NavProvider } from "@cosmicdrift/kumiko-renderer";
 import userEvent from "@testing-library/user-event";
-import { createMockDispatcher, render, screen, waitFor } from "./test-utils";
+import { type ReactNode, useState } from "react";
+import {
+  createMockDispatcher,
+  render,
+  renderWithPrimitivesOverride,
+  screen,
+  waitFor,
+} from "./test-utils";
 
 const baseScreen: ProjectionDetailScreenDefinition = {
   id: "rent-detail",
@@ -124,6 +131,57 @@ describe("KumikoScreen / projectionDetail — record header + metrics band", ()
   });
 });
 
+describe("KumikoScreen / projectionDetail — metric tiles render through the Metric primitive", () => {
+  const metricsScreen: ProjectionDetailScreenDefinition = {
+    ...baseScreen,
+    metrics: ["balance"],
+  };
+
+  test("goes through the Metric primitive, not naked Text, when one is registered", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(metricsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // Only the Metric primitive assigns a testid to the tile itself — the
+    // naked-Text fallback below only labels the -label/-value nodes. This
+    // is red against the pre-fix code (naked Text, no tile testid).
+    expect(screen.getByTestId("kumiko-screen-projection-detail-metric-balance")).toBeTruthy();
+    expect(
+      screen.getByTestId("kumiko-screen-projection-detail-metric-balance-value").textContent,
+    ).toBe("120");
+  });
+
+  test("falls back to plain label/value Text when no Metric primitive is registered", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+
+    renderWithPrimitivesOverride(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(metricsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+      { Metric: undefined },
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(
+      screen.getByTestId("kumiko-screen-projection-detail-metric-balance-value").textContent,
+    ).toBe("120");
+    expect(screen.queryByTestId("kumiko-screen-projection-detail-metric-balance")).toBeNull();
+  });
+});
+
 describe("KumikoScreen / projectionDetail — layout.mode: 'tabs'", () => {
   const tabsScreen: ProjectionDetailScreenDefinition = {
     ...baseScreen,
@@ -167,6 +225,92 @@ describe("KumikoScreen / projectionDetail — layout.mode: 'tabs'", () => {
     };
   }
 
+  // Reactive nav stub — navWithTab's searchParams is fixed at mount, so it
+  // can't exercise a real "click a tab, watch the active section change"
+  // flow. Only used by the tab-switch test below.
+  function StatefulTabNav({ children }: { readonly children: ReactNode }): ReactNode {
+    const [tab, setTab] = useState<string | undefined>(undefined);
+    const navApi: NavApi = {
+      route: undefined,
+      navigate: () => {},
+      replace: () => {},
+      hrefFor: () => "",
+      searchParams: tab !== undefined ? { tab } : {},
+      setSearchParams: (updates) => {
+        const next = updates["tab"];
+        setTab(next === null || next === undefined ? undefined : next);
+      },
+    };
+    return <NavProvider value={navApi}>{children}</NavProvider>;
+  }
+
+  test("switching tabs does not remount the body or refire the detail query", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const user = userEvent.setup();
+
+    render(
+      <StatefulTabNav>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </StatefulTabNav>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const detailCallsBefore = dispatcher.calls.filter(
+      (c) => c.type === "rentals:query:rent:detail",
+    ).length;
+    expect(detailCallsBefore).toBe(1);
+
+    const trigger = await waitFor(() =>
+      screen.getByTestId("kumiko-screen-projection-detail-tabs-payments"),
+    );
+    await user.click(trigger);
+    await waitFor(() =>
+      expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:payments")).toBe(true),
+    );
+
+    // A `key` on the record identifier alone (fw#2518 fix) must not also
+    // depend on the active tab — folding tab into the key would remount the
+    // body on every tab click and refire this query. The pre-fix "fires
+    // exactly one query" test above only checks first render and would not
+    // have caught that regression.
+    const detailCallsAfter = dispatcher.calls.filter(
+      (c) => c.type === "rentals:query:rent:detail",
+    ).length;
+    expect(detailCallsAfter).toBe(detailCallsBefore);
+  });
+
+  test("tabs mode suppresses the form's own redundant title, not just section titles", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const { navApi } = navWithTab(undefined);
+
+    render(
+      <NavProvider value={navApi}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // hideSectionTitles used to only blank out each Section's own title —
+    // RenderEdit's own Form-level title (screen id/i18n fallback) rendered
+    // unconditionally regardless, duplicating the active tab's label
+    // whenever the two happened to read the same ("Mietvertrag" above the
+    // table, matching the already-visible tab). This asserts the Form-level
+    // title is gone too, not just the section ones.
+    expect(screen.queryByTestId("render-edit-form-title")).toBeNull();
+  });
+
   test("fires exactly one query on first render — the inactive tabs' relatedList queries never fire", async () => {
     const dispatcher = dispatcherReturning(rowData);
     const { navApi } = navWithTab(undefined);
@@ -301,5 +445,55 @@ describe("KumikoScreen / projectionDetail — unchanged for a solon-shaped scree
       expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:invoices")).toBe(true),
     );
     expect(screen.queryByTestId("kumiko-screen-projection-detail-tabs")).toBeNull();
+    // Contrast for the tabs-mode "form title suppressed" test above — outside
+    // tabs mode (hideSectionTitles unset) the form's own title still renders.
+    expect(screen.getByTestId("render-edit-form-title")).toBeTruthy();
+  });
+});
+
+describe("KumikoScreen / projectionDetail — switching records remounts the body (fw#2518)", () => {
+  test("record A's fields are gone from the DOM after switching to record B", async () => {
+    const dataById: Record<string, Readonly<Record<string, unknown>>> = {
+      "rent-1": { description: "Loft 4B" },
+      "rent-2": { description: "Warehouse 9" },
+    };
+    const query = (async (type: string, payload: unknown) => {
+      if (type === "rentals:query:rent:detail") {
+        const id = (payload as { id?: string }).id ?? "";
+        return { isSuccess: true, data: dataById[id] ?? {} };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) as unknown as Dispatcher["query"];
+    const dispatcher = createMockDispatcher({ query });
+
+    const { rerender } = render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(baseScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByText("Loft 4B"));
+
+    rerender(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(baseScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-2"
+        />
+      </DispatcherProvider>,
+    );
+
+    // Without the key fix, React keeps the old ProjectionDetailBody instance
+    // mounted and briefly renders record A's fields until the new query
+    // resolves. Asserting only the ABSENCE of "Loft 4B" would pass on flaky
+    // timing even without the fix, so this also waits for record B's own
+    // value to confirm the remount actually completed.
+    await waitFor(() => screen.getByText("Warehouse 9"));
+    expect(screen.queryByText("Loft 4B")).toBeNull();
   });
 });

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

@@ -9,7 +9,12 @@ import { describe, expect, test } from "bun:test";
 import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import type { FeatureSchema, NavApi, NavTarget } from "@cosmicdrift/kumiko-renderer";
-import { DispatcherProvider, KumikoScreen, NavProvider } from "@cosmicdrift/kumiko-renderer";
+import {
+  DispatcherProvider,
+  ExtensionSectionsProvider,
+  KumikoScreen,
+  NavProvider,
+} from "@cosmicdrift/kumiko-renderer";
 import { act, createMockDispatcher, fireEvent, render, screen, waitFor } from "./test-utils";
 
 const detailScreen: ProjectionDetailScreenDefinition = {
@@ -470,3 +475,141 @@ describe("KumikoScreen / projectionDetail relatedList section (fw#2166)", () =>
     expect(navigated).toBeUndefined();
   });
 });
+
+// solon#264: a hand-written NotesSection block had no declarative equivalent
+// on projectionDetail. Extension sections without contributesToFormSubmit
+// (self-persisting, e.g. via their own dispatcher writes) are now allowed.
+describe("KumikoScreen / projectionDetail extension section (solon#264)", () => {
+  const SessionNotes = ({
+    entityName,
+    entityId,
+  }: {
+    entityName: string;
+    entityId: string | null;
+  }) => (
+    <div data-testid="session-notes">
+      {entityName}:{entityId ?? "(none)"}
+    </div>
+  );
+
+  test("mounts and receives the route entityId and the section's declared entityName, no submit button", async () => {
+    const extensionScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      layout: {
+        sections: [
+          ...detailScreen.layout.sections,
+          {
+            kind: "extension",
+            title: "Notes",
+            component: { react: { __component: "SessionNotes" } },
+            entityName: "user-session",
+          },
+        ],
+      },
+    };
+    const extensionSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [extensionScreen],
+    };
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+      })) as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <ExtensionSectionsProvider value={{ SessionNotes }}>
+          <KumikoScreen
+            schema={extensionSchema}
+            qn="sessions:screen:session-detail"
+            entityId="sess-1"
+          />
+        </ExtensionSectionsProvider>
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    // Declared entityName ("user-session") must win over the shim's internal
+    // placeholder entity name — otherwise a self-persisting section like
+    // NotesSection would filter/write against the wrong domain entity.
+    expect(screen.getByTestId("session-notes").textContent).toBe("user-session:sess-1");
+    expect(screen.queryByTestId("render-edit-submit")).toBeNull();
+  });
+
+  test("layout.mode: 'tabs' — mounts only when its tab is active, not on first render of another tab", async () => {
+    const tabsExtensionScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      layout: {
+        mode: "tabs",
+        sections: [
+          { id: "overview", title: "Session", fields: ["userId"] },
+          {
+            id: "notes",
+            kind: "extension",
+            title: "Notes",
+            component: { react: { __component: "SessionNotes" } },
+            entityName: "user-session",
+          },
+        ],
+      },
+    };
+    const tabsExtensionSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [tabsExtensionScreen],
+    };
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+      })) as unknown as Dispatcher["query"],
+    });
+    function navWithTab(tab: string | undefined): NavApi {
+      return {
+        route: undefined,
+        navigate: () => {},
+        replace: () => {},
+        hrefFor: () => "",
+        searchParams: tab !== undefined ? { tab } : {},
+        setSearchParams: () => {},
+      };
+    }
+
+    const { unmount } = render(
+      <NavProvider value={navWithTab(undefined)}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <ExtensionSectionsProvider value={{ SessionNotes }}>
+            <KumikoScreen
+              schema={tabsExtensionSchema}
+              qn="sessions:screen:session-detail"
+              entityId="sess-1"
+            />
+          </ExtensionSectionsProvider>
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.queryByTestId("session-notes")).toBeNull();
+    unmount();
+
+    render(
+      <NavProvider value={navWithTab("notes")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <ExtensionSectionsProvider value={{ SessionNotes }}>
+            <KumikoScreen
+              schema={tabsExtensionSchema}
+              qn="sessions:screen:session-detail"
+              entityId="sess-1"
+            />
+          </ExtensionSectionsProvider>
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    await waitFor(() => screen.getByTestId("session-notes"));
+    expect(screen.getByTestId("session-notes").textContent).toBe("user-session:sess-1");
+    expect(screen.queryByTestId("field-userId")).toBeNull();
+  });
+});

package/src/primitives/__tests__/data-table-logic.test.ts

@@ -196,6 +196,22 @@ describe("defaultCellRender", () => {
     expect(defaultCellRender("op-x", "select", { "op-x": "Operativ X" })).toBe("Operativ X");
   });
 
+  test("multiSelect → Werte gejoint mit ', ', optionLabel gewinnt vor humanizeSlug pro Wert (fw#2491)", () => {
+    expect(
+      defaultCellRender(["op-x", "degraded-performance"], "multiSelect", {
+        "op-x": "Operativ X",
+      }),
+    ).toBe("Operativ X, Degraded performance");
+  });
+
+  test("multiSelect → leeres Array liefert leeren String", () => {
+    expect(defaultCellRender([], "multiSelect")).toBe("");
+  });
+
+  test("multiSelect → einzelner Nicht-Array-Wert wird wie select behandelt (defensive)", () => {
+    expect(defaultCellRender("op-x", "multiSelect", { "op-x": "Operativ X" })).toBe("Operativ X");
+  });
+
   test("text → String-Repräsentation", () => {
     expect(defaultCellRender("hallo", "text")).toBe("hallo");
   });

package/src/primitives/index.tsx

@@ -105,6 +105,7 @@ import { EmbeddedListInput } from "./embedded-list-input";
 import { FileUploadInput } from "./file-upload";
 import { DefaultLightbox } from "./lightbox";
 import { LocatedTimestampInput } from "./located-timestamp-input";
+import { DefaultMetric } from "./metric";
 import { DefaultModal } from "./modal";
 import { currencyDecimals, formatMoney, MoneyInput } from "./money-input";
 import { DefaultStatusBadge } from "./status-badge";
@@ -1445,7 +1446,7 @@ function isMoneyValue(value: unknown): value is MoneyCellValue {
 //   - boolean → ✓ / leer
 //   - timestamp/date → locale-formatiert (kein roher ISO-String)
 //   - number/decimal/bigInt → locale-formatted via Intl.NumberFormat (fw#2160)
-//   - select → human-lesbar (kebab-case → Title Case)
+//   - select/multiSelect → human-readable (kebab-case → Title Case), multiSelect values joined with ", "
 //   - money → { amount, currency } formatted via Intl (not "[object Object]")
 //   - text/else → toString
 export function defaultCellRender(
@@ -1473,15 +1474,19 @@ export function defaultCellRender(
     const minor = Math.round(value.amount * 10 ** currencyDecimals(value.currency));
     return formatMoney(minor, value.currency, locale);
   }
-  if (type === "select") {
-    const raw = String(value);
-    // Translated Label aus dem ViewModel-Builder (Convention-Key
-    // `<feature>:entity:<entity>:field:<field>:option:<value>`).
-    // Fallback humanizeSlug wenn kein Label registriert — gleiches
-    // Verhalten wie vor dem optionLabels-Patch.
-    const translated = optionLabels?.[raw];
-    if (translated !== undefined && translated !== raw) return translated;
-    return humanizeSlug(raw);
+  if (type === "select" || type === "multiSelect") {
+    const values = Array.isArray(value) ? value : [value];
+    return values
+      .map((v) => {
+        const raw = String(v);
+        // Translated label from the view-model builder (convention key
+        // `<feature>:entity:<entity>:field:<field>:option:<value>`).
+        // Fallback to humanizeSlug when no label is registered — same
+        // behavior as before the optionLabels patch.
+        const translated = optionLabels?.[raw];
+        return translated !== undefined && translated !== raw ? translated : humanizeSlug(raw);
+      })
+      .join(", ");
   }
   return typeof value === "string" ? value : String(value);
 }
@@ -1621,6 +1626,7 @@ function DefaultForm({
   testId,
   width,
   stickyActions,
+  headerRegion,
 }: FormProps): ReactNode {
   // Eingebettet (AuthCard etc.): nacktes <form>, gestapelte Felder mit gap —
   // der Container trägt Card/Titel selbst, sonst Card-in-Card.
@@ -1660,6 +1666,9 @@ function DefaultForm({
       className="flex flex-col w-full"
     >
       <FormScreenShell {...(width !== undefined && { maxWidth: width })}>
+        {headerRegion !== undefined && (
+          <div className="flex flex-col gap-6 mb-8">{headerRegion}</div>
+        )}
         <div className={cn(cardSurface(), "overflow-hidden")}>
           {(title !== undefined || subtitle !== undefined) && (
             <div className="px-6 pb-2 pt-5">
@@ -1852,6 +1861,16 @@ function DefaultSection({
 }
 
 function DefaultGrid({ columns, children, testId, maxRows }: GridProps): ReactNode {
+  // "auto": content-sized items in a wrapping row (e.g. a metrics band of
+  // self-sized tiles) instead of N equal-width, container-stretched tracks.
+  // maxRows/scrolling don't apply — the row just wraps.
+  if (columns === "auto") {
+    return (
+      <div data-testid={testId} className="flex flex-wrap gap-4">
+        {children}
+      </div>
+    );
+  }
   // Responsive: Mobile (< sm = 640px) bleibt 1-spaltig, ab sm: greift
   // die Author-deklarierte Spaltenzahl. Inline-style schreibt
   // CSS-Variable; Tailwind-Klasse liest die Variable mit
@@ -2094,4 +2113,5 @@ export const defaultPrimitives: CorePrimitives = {
   WizardStepGroup: DefaultWizardStepGroup,
   Tabs: DefaultTabs,
   StatusBadge: DefaultStatusBadge,
+  Metric: DefaultMetric,
 };

package/src/primitives/metric.tsx

@@ -0,0 +1,17 @@
+import type { MetricProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { MiniStat } from "../widgets/stat";
+
+export function DefaultMetric({ label, value, testId }: MetricProps): ReactNode {
+  return (
+    <MiniStat
+      label={label}
+      value={value}
+      testId={testId}
+      {...(testId !== undefined && {
+        labelTestId: `${testId}-label`,
+        valueTestId: `${testId}-value`,
+      })}
+    />
+  );
+}

package/src/widgets/stat.tsx

@@ -157,12 +157,16 @@ export function MiniStat({
   tone = "default",
   emphasize = false,
   testId,
+  labelTestId,
+  valueTestId,
 }: {
   readonly label: string;
   readonly value: string;
   readonly tone?: StatTone;
   readonly emphasize?: boolean;
   readonly testId?: string;
+  readonly labelTestId?: string;
+  readonly valueTestId?: string;
 }): ReactNode {
   const { Card } = usePrimitives();
   return (
@@ -171,13 +175,16 @@ export function MiniStat({
       className={cn("p-3", emphasize && "ring-1 ring-primary/30")}
       testId={testId}
     >
-      <div className="text-xs text-muted-foreground">{label}</div>
+      <div className="text-xs text-muted-foreground" data-testid={labelTestId}>
+        {label}
+      </div>
       <div
         className={cn(
           "mt-0.5 font-semibold tabular-nums",
           TONE_VALUE[tone],
           emphasize ? "text-lg" : "text-sm",
         )}
+        data-testid={valueTestId}
       >
         {value}
       </div>