@cosmicdrift/kumiko-renderer 0.245.0 → 0.247.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.245.0",
+  "version": "0.247.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.245.0",
-    "@cosmicdrift/kumiko-headless": "0.245.0",
+    "@cosmicdrift/kumiko-framework": "0.247.0",
+    "@cosmicdrift/kumiko-headless": "0.247.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.245.0"
+    "@cosmicdrift/kumiko-locale-de": "0.247.0"
   },
   "repository": {
     "type": "git",

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

@@ -23,4 +23,25 @@ describe("synthesizeActionFormScreen", () => {
     expect(screen.entity).toBe("__action-form__");
     expect(screen.layout).toEqual({ sections: [{ title: "Invite", fields: ["email"] }] });
   });
+
+  test("carries description through so RenderEdit can render it as the form subtitle (fw#2723)", () => {
+    const withDescription = synthesizeActionFormScreen({
+      id: "invite-user",
+      type: "actionForm",
+      description: "Invite a new team member by email.",
+      handler: "users:write:invite-user",
+      layout: { sections: [{ title: "Invite", fields: ["email"] }] },
+      fields: { email: { type: "text" } },
+    });
+    expect(withDescription.description).toBe("Invite a new team member by email.");
+
+    const withoutDescription = synthesizeActionFormScreen({
+      id: "invite-user",
+      type: "actionForm",
+      handler: "users:write:invite-user",
+      layout: { sections: [{ title: "Invite", fields: ["email"] }] },
+      fields: { email: { type: "text" } },
+    });
+    expect("description" in withoutDescription).toBe(false);
+  });
 });

package/src/app/__tests__/entity-list-row-action-entity-target.test.tsx

@@ -292,8 +292,17 @@ const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) =
   </button>
 );
 
-const FormWithActions: ComponentType<FormProps> = ({ children, actions, secondaryActions }) => (
+// headerRegion carries projectionDetail's header actions since fw#2713 — a
+// stub that only forwards children/actions/secondaryActions drops them
+// silently, as this test's own action button did until it grew this slot.
+const FormWithActions: ComponentType<FormProps> = ({
+  children,
+  actions,
+  secondaryActions,
+  headerRegion,
+}) => (
   <>
+    {headerRegion !== undefined && <div data-testid="form-header">{headerRegion}</div>}
     <div data-testid="form-body">{children}</div>
     <div data-testid="form-actions">
       {secondaryActions}

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

@@ -43,13 +43,19 @@ const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) =
   </button>
 );
 
-// Form's `actions`/`secondaryActions` slots carry the header buttons under
-// test — passChildren alone would drop them. Wrapped in distinct testid'd
-// containers so a test can assert a banner rendered as a Form CHILD
-// (formError/actionError region) rather than inside the actions row — the
-// review finding this proves.
-const FormWithActions: ComponentType<FormProps> = ({ children, actions, secondaryActions }) => (
+// Header actions (and their error banner) now render inside ProjectionDetail's
+// own head Card, passed through as `headerRegion` (fw#2713) rather than
+// through Form's `actions`/`secondaryActions` slots — wrapped in a distinct
+// testid'd container so a test can assert both live there, not in the
+// actions/body regions Form itself owns.
+const FormWithActions: ComponentType<FormProps> = ({
+  children,
+  actions,
+  secondaryActions,
+  headerRegion,
+}) => (
   <>
+    {headerRegion !== undefined && <div data-testid="form-header">{headerRegion}</div>}
     <div data-testid="form-body">{children}</div>
     <div data-testid="form-actions">
       {secondaryActions}
@@ -410,7 +416,7 @@ describe("projectionDetail default edit action (fw#2166)", () => {
     expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
   });
 
-  test("a failed writeHandler action shows its error in the shared error region, NOT inside the action button row", async () => {
+  test("a failed writeHandler action shows its error in the head region, alongside the action button, NOT in Form's own actions/body regions (fw#2713)", async () => {
     const schema: FeatureSchema = {
       featureName: "app",
       entities: {},
@@ -441,13 +447,17 @@ describe("projectionDetail default edit action (fw#2166)", () => {
 
     const errorBanner = await waitFor(() => getByTestId("render-edit-action-error"));
     expect(errorBanner.textContent).toBe("archive failed: rent is still active");
-    // The banner must be a Form child (formError-adjacent region), not a
-    // descendant of the actions row — a full-width Banner inside the
-    // `justify-end` button row breaks its layout (fw#2166 review finding 5).
-    expect(errorBanner.closest('[data-testid="form-body"]')).not.toBeNull();
+    // Header actions (and their failure banner) render in the head Card via
+    // `headerRegion` now (fw#2713) — not through Form's own actions/body
+    // slots, so both a tab switch and Form's own footer leave them untouched.
+    expect(errorBanner.closest('[data-testid="form-header"]')).not.toBeNull();
+    expect(errorBanner.closest('[data-testid="form-body"]')).toBeNull();
     expect(errorBanner.closest('[data-testid="form-actions"]')).toBeNull();
     expect(
-      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-header"]'),
     ).not.toBeNull();
+    expect(
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+    ).toBeNull();
   });
 });

package/src/app/__tests__/projection-detail-shim.test.ts

@@ -40,4 +40,23 @@ describe("synthesizeProjectionDetailScreen", () => {
     }
     expect(writeFormSection.fields[0]).toEqual({ field: "note", readOnly: false });
   });
+
+  test("carries description through so RenderEdit can render it as the form subtitle (fw#2723)", () => {
+    const withDescription = synthesizeProjectionDetailScreen({
+      id: "order-detail",
+      type: "projectionDetail",
+      description: "Read-only view of a placed order.",
+      query: "orders:query:order:detail",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    });
+    expect(withDescription.description).toBe("Read-only view of a placed order.");
+
+    const withoutDescription = synthesizeProjectionDetailScreen({
+      id: "order-detail",
+      type: "projectionDetail",
+      query: "orders:query:order:detail",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    });
+    expect("description" in withoutDescription).toBe(false);
+  });
 });

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

@@ -45,6 +45,7 @@ export function synthesizeActionFormScreen(
     type: "entityEdit",
     entity: ACTION_FORM_PSEUDO_ENTITY,
     layout: screen.layout,
+    ...(screen.description !== undefined && { description: screen.description }),
     ...(screen.access !== undefined && { access: screen.access }),
   };
 }

package/src/app/kumiko-screen.tsx

@@ -28,6 +28,7 @@ import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog";
 import { RenderEdit, type RenderEditAction } from "../components/render-edit";
+import { RenderEditActionButton } from "../components/render-edit-action-button";
 import { RenderList, type ToolbarActionButton } from "../components/render-list";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context";
 import { useUserRoles } from "../context/user-roles-context";
@@ -37,6 +38,7 @@ import { useTranslation } from "../i18n";
 import {
   type DataTableFacet,
   type DataTableRowAction,
+  shouldRenderActionsIconOnly,
   statusToneForValue,
   usePrimitives,
 } from "../primitives";
@@ -2174,7 +2176,7 @@ function ProjectionDetailBody({
   readonly translate?: Translate;
   readonly entityId?: string;
 }): ReactNode {
-  const { Banner, Text, Heading, Grid, GridCell, Card, Tabs, StatusBadge, Metric } =
+  const { Banner, Button, Dialog, Text, Heading, Grid, GridCell, Card, Tabs, StatusBadge, Metric } =
     usePrimitives();
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
@@ -2229,6 +2231,11 @@ function ProjectionDetailBody({
     setReloadNonce((n) => n + 1);
   }, [detailQuery.refetch]);
 
+  // Header actions render directly via RenderEditActionButton (fw#2713,
+  // headerActions moved out of RenderEdit's footer) — this component owns
+  // the failure-surfacing state RenderEdit used to own for them.
+  const [actionError, setActionError] = useState<string | null>(null);
+
   // Default edit action (fw#2166): resolved cross-feature over ALL mounted
   // features, not just this feature's own schema — detailFor itself is
   // resolved cross-feature by the boot-validator (detail-screens.ts), and
@@ -2455,6 +2462,30 @@ function ProjectionDetailBody({
   const hasHeader = screen.header !== undefined;
   const hasMetrics = screen.metrics !== undefined && screen.metrics.length > 0;
   const hasTabs = isTabsMode && Tabs !== undefined && activeSection !== undefined;
+  // ?? [] rather than threading `headerActions !== undefined` through every
+  // use below — an empty array is a safe no-op for .map/.length/icon-collapse.
+  const headerActionsList = headerActions ?? [];
+  const hasHeaderActions = headerActionsList.length > 0;
+  const headerActionsIconOnly = shouldRenderActionsIconOnly(headerActionsList);
+  // Grouped into the head Card alongside title/status/metrics (fw#2713):
+  // these are actions on the record the head shows, not on whichever tab is
+  // open, so they must stay in place across tab switches instead of
+  // trailing the active tab's content in the card footer.
+  const headerActionsContent = hasHeaderActions && (
+    <Grid columns="auto" testId="kumiko-screen-projection-detail-actions">
+      {headerActionsList.map((action) => (
+        <RenderEditActionButton
+          key={action.id}
+          action={action}
+          iconOnly={headerActionsIconOnly}
+          Button={Button}
+          Dialog={Dialog}
+          onError={setActionError}
+        />
+      ))}
+    </Grid>
+  );
+  const hasHeaderCard = hasHeader || hasMetrics || hasHeaderActions;
   // Rendered as RenderEdit's headerRegion (not as JSX siblings before it) so
   // this shares the same page padding/width as the record's edit card below
   // it, instead of sitting flush against the screen edge (fw record-screen
@@ -2462,7 +2493,7 @@ function ProjectionDetailBody({
   const header = screen.header;
   const headerContent = (
     <>
-      {(hasHeader || hasMetrics) && (
+      {hasHeaderCard && (
         <Card>
           {header !== undefined && (
             <>
@@ -2515,6 +2546,12 @@ function ProjectionDetailBody({
               })}
             </Grid>
           )}
+          {headerActionsContent}
+          {actionError !== null && (
+            <Banner variant="error" testId="render-edit-action-error">
+              {actionError}
+            </Banner>
+          )}
         </Card>
       )}
       {hasTabs && activeSection !== undefined && (
@@ -2542,10 +2579,9 @@ function ProjectionDetailBody({
         customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
         onReload={reloadDetail}
         onRelatedListDrawerAction={openDrawer}
-        {...(headerActions !== undefined && { actions: headerActions })}
         {...(translate !== undefined && { translate })}
         {...(hasTabs && { hideSectionTitles: true })}
-        {...((hasHeader || hasMetrics || hasTabs) && { headerRegion: headerContent })}
+        {...((hasHeaderCard || hasTabs) && { headerRegion: headerContent })}
         valueDisplay={screen.valueDisplay ?? "text"}
       />
       <DrawerHost

package/src/app/projection-detail-shim.ts

@@ -67,6 +67,7 @@ export function synthesizeProjectionDetailScreen(
     layout: { sections, ...(screen.layout.width !== undefined && { width: screen.layout.width }) },
     allowCreate: false,
     allowDelete: false,
+    ...(screen.description !== undefined && { description: screen.description }),
     ...(screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),
     ...(screen.slots !== undefined && { slots: screen.slots }),
     ...(screen.access !== undefined && { access: screen.access }),

package/src/app/row-actions.ts

@@ -159,6 +159,21 @@ type OpenDrawer = (
   initialValues: Readonly<Record<string, unknown>> | undefined,
 ) => void;
 
+// buildProjectionRowActions runs inside a useMemo (re-evaluated on every dep
+// change), so this dedupes the "openDrawer not wired" warning per action id
+// instead of firing on every recompute.
+const warnedDrawerRowActionIds = new Set<string>();
+
+function warnDrawerActionDropped(actionId: string): void {
+  // skip: already warned for this id — suppresses the repeat, not the warning itself.
+  if (warnedDrawerRowActionIds.has(actionId)) return;
+  warnedDrawerRowActionIds.add(actionId);
+  // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
+  console.warn(
+    `[kumiko] rowAction "${actionId}" is kind:"drawer", but the host did not wire openDrawer (RelatedListSection: pass onOpenDrawer) — it will not render.`,
+  );
+}
+
 function buildDrawerRowAction(
   action: RowActionDrawer,
   translate: Translate,
@@ -193,7 +208,8 @@ export function buildProjectionRowActions(options: {
   readonly nav: NavApi;
   readonly refetch: () => Promise<unknown>;
   /** Opens the drawer-kind action's target actionForm, prefilled from the
-   *  clicked row. Omitted callers (none today) simply drop drawer actions —
+   *  clicked row. Omitted callers (e.g. RelatedListSection embedded directly
+   *  without onOpenDrawer) drop drawer actions and get a dev warning —
    *  mirrors the `dispatcher === undefined` skip below for writeHandler. */
   readonly openDrawer?: OpenDrawer;
 }): readonly DataTableRowAction[] | undefined {
@@ -206,7 +222,10 @@ export function buildProjectionRowActions(options: {
       continue;
     }
     if (action.kind === "drawer") {
-      if (openDrawer === undefined) continue;
+      if (openDrawer === undefined) {
+        warnDrawerActionDropped(action.id);
+        continue;
+      }
       out.push(buildDrawerRowAction(action, translate, openDrawer));
       continue;
     }

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

@@ -1,7 +1,7 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 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 { fireEvent, render, screen as rtlScreen, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { type NavApi, NavProvider } from "../../app/nav";
 import { DispatcherProvider } from "../../context/dispatcher-context";
@@ -79,7 +79,10 @@ function testPrimitives(): CorePrimitives {
   } as unknown as CorePrimitives;
 }
 
-function stubDispatcher(rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }]): {
+function stubDispatcher(
+  rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }],
+  nextCursor: string | null = null,
+): {
   dispatcher: Dispatcher;
   writes: Array<{ type: string; payload: unknown }>;
   queryCount: () => number;
@@ -93,7 +96,7 @@ function stubDispatcher(rows: readonly Record<string, unknown>[] = [{ id: "r1",
     }) as Dispatcher["write"],
     query: (async () => {
       queryCalls += 1;
-      return { isSuccess: true, data: { rows, nextCursor: null } };
+      return { isSuccess: true, data: { rows, nextCursor } };
     }) as Dispatcher["query"],
     batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
     statusStore: {
@@ -167,6 +170,77 @@ function renderRelatedList(
   );
 }
 
+describe("RelatedListSection — tabs-mode card chrome (fw#2722)", () => {
+  test("hideTitle (tabs mode) renders the list without a Section wrapper and marks the table chromeless + scrollBody", async () => {
+    const { dispatcher } = stubDispatcher();
+    let capturedChromeless: boolean | undefined;
+    let capturedScrollBody: boolean | undefined;
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedChromeless = props.chromeless;
+      capturedScrollBody = props.scrollBody;
+      return testDataTable(props);
+    };
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: capturingDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={historySection}
+                parentId="order-1"
+                featureName="orders"
+                hideTitle
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId(`related-list-${historySection.title}`)).toBeNull();
+    expect(capturedChromeless).toBe(true);
+    expect(capturedScrollBody).toBe(true);
+  });
+
+  test("without hideTitle (stacked mode), the same section keeps its Section wrapper and an un-chromeless, unbounded-height table", async () => {
+    const { dispatcher } = stubDispatcher();
+    let capturedChromeless: boolean | undefined;
+    let capturedScrollBody: boolean | undefined;
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedChromeless = props.chromeless;
+      capturedScrollBody = props.scrollBody;
+      return testDataTable(props);
+    };
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: capturingDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={historySection}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId(`related-list-${historySection.title}`)).toBeTruthy();
+    expect(capturedChromeless).toBeUndefined();
+    expect(capturedScrollBody).toBeUndefined();
+  });
+});
+
 describe("RelatedListSection — rowActions", () => {
   test("clicking a row action dispatches through the configured write-handler with the extracted payload, then refetches", async () => {
     const { dispatcher, writes, queryCount } = stubDispatcher();
@@ -313,4 +387,254 @@ describe("RelatedListSection — rowActions drawer-kind (fw#2710)", () => {
     await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
     expect(rtlScreen.queryByTestId("action-adjust-rent-item-7")).toBeNull();
   });
+
+  test("a dropped drawer rowAction without onOpenDrawer logs a dev warning naming the action id (fw#2733)", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      renderRelatedList(dispatcher, {
+        kind: "relatedList",
+        title: "Positions",
+        query: "lease:query:items:list",
+        columns: [{ field: "name" }],
+        rowActions: [
+          {
+            kind: "drawer",
+            id: "adjust-rent-warn-only-2733",
+            label: "actions.adjustRent",
+            screen: "adjust-rent-form",
+          },
+        ],
+      });
+
+      await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0]?.[0]).toContain("adjust-rent-warn-only-2733");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("a drawer rowAction with onOpenDrawer wired renders without a dev warning (fw#2733)", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      render(
+        <LocaleProvider
+          resolver={createStaticLocaleResolver({ locale: "en-US" })}
+          fallbackBundles={[kumikoDefaultTranslations]}
+        >
+          <DispatcherProvider dispatcher={dispatcher}>
+            <PrimitivesProvider value={testPrimitives()}>
+              <NavProvider value={stubNav().nav}>
+                <RelatedListSection
+                  section={{
+                    kind: "relatedList",
+                    title: "Positions",
+                    query: "lease:query:items:list",
+                    columns: [{ field: "name" }],
+                    rowActions: [
+                      {
+                        kind: "drawer",
+                        id: "adjust-rent-warn-wired-2733",
+                        label: "actions.adjustRent",
+                        screen: "adjust-rent-form",
+                      },
+                    ],
+                  }}
+                  parentId="order-1"
+                  featureName="orders"
+                  onOpenDrawer={noop}
+                />
+              </NavProvider>
+            </PrimitivesProvider>
+          </DispatcherProvider>
+        </LocaleProvider>,
+      );
+
+      await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
+      expect(rtlScreen.getByTestId("action-adjust-rent-warn-wired-2733-item-7")).toBeTruthy();
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
+
+// A DataTable stub that renders one row per query row (DOM order == passed
+// `rows` order, so a re-sort is observable as a re-ordered row list) plus a
+// button that calls `onSortChange` the same way a real SortableHeader click
+// would — enough to prove RelatedListSection actually re-orders rows, not
+// just that a header is clickable.
+const orderedDataTable: ComponentType<DataTableProps> = ({ rows, onSortChange }) => (
+  <div>
+    <table>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={row.id} data-testid={`row-${row.id}`} />
+        ))}
+      </tbody>
+    </table>
+    {onSortChange !== undefined && (
+      <button
+        type="button"
+        data-testid="sort-amount-desc"
+        onClick={() => onSortChange({ field: "amount", dir: "desc" })}
+      >
+        sort
+      </button>
+    )}
+  </div>
+);
+
+function renderedRowOrder(): string[] {
+  return rtlScreen
+    .getAllByTestId(/^row-/)
+    .map((el) => el.getAttribute("data-testid")?.replace("row-", "") ?? "");
+}
+
+describe("RelatedListSection — sorting (fw#2722)", () => {
+  const unsortedRows = [
+    { id: "r1", name: "Charlie", amount: 300 },
+    { id: "r2", name: "Alice", amount: 100 },
+    { id: "r3", name: "Bob", amount: 200 },
+  ];
+
+  test("defaultSort sorts the already-loaded rows client-side, independent of query response order", async () => {
+    const { dispatcher } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount", sortable: true }],
+                  defaultSort: { field: "amount", dir: "asc" },
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r2", "r3", "r1"]);
+  });
+
+  test("toggling sort via onSortChange re-orders rows without a refetch", async () => {
+    const { dispatcher, queryCount } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount", sortable: true }],
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r1", "r2", "r3"]);
+
+    fireEvent.click(rtlScreen.getByTestId("sort-amount-desc"));
+
+    await waitFor(() => expect(renderedRowOrder()).toEqual(["r1", "r3", "r2"]));
+    expect(queryCount()).toBe(1);
+  });
+
+  test("a section without defaultSort renders rows in the original query order (unchanged behavior)", async () => {
+    const { dispatcher } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount" }],
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r1", "r2", "r3"]);
+  });
+});
+
+describe("RelatedListSection — truncation banner (fw#2722 review)", () => {
+  test("nextCursor !== null renders a truncation banner", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], "cursor-abc");
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    const banner = rtlScreen.getByTestId("related-list-truncated");
+    expect(banner).toBeTruthy();
+    // Proves {count} actually interpolates (single-brace, the renderer's own
+    // i18n.tsx interpolate() syntax) rather than rendering as literal braces.
+    expect(banner.textContent).toContain("Showing the first 1 entries.");
+  });
+
+  test("nextCursor === null renders no truncation banner", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], null);
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("related-list-truncated")).toBeNull();
+  });
+
+  test("the banner shows regardless of an active sort — an unsorted truncated list is equally misleading", async () => {
+    const { dispatcher } = stubDispatcher(
+      [
+        { id: "r1", name: "Charlie", amount: 300 },
+        { id: "r2", name: "Alice", amount: 100 },
+      ],
+      "cursor-abc",
+    );
+    renderRelatedList(dispatcher, {
+      kind: "relatedList",
+      title: "Positions",
+      query: "lease:query:items:list",
+      columns: [{ field: "amount", sortable: true }],
+      defaultSort: { field: "amount", dir: "asc" },
+    });
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("related-list-truncated")).toBeTruthy();
+  });
 });

package/src/components/__tests__/render-edit-screen-description.test.tsx

@@ -0,0 +1,132 @@
+// Regression coverage for kumiko-framework#2723: `EntityEditScreenDefinition.
+// description` / `ActionFormScreenDefinition.description` existed in the type
+// but was never rendered anywhere — used only as agent/API metadata
+// (packages/framework/src/api/server.ts). RenderEdit now renders it as the
+// form's subtitle, same visual slot section.description already fills for a
+// section (render-edit.tsx's `Section`), falling back to it only when no
+// `screen:<id>.subtitle` i18n override is set. `description` is run through
+// translate(): an i18n key (the established convention, e.g.
+// user-data-rights/feature.ts) resolves to its translation, plain prose
+// passes through unchanged (review finding on this PR).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { render } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider, type TranslationsByLocale } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import { type CorePrimitives, type FormProps, PrimitivesProvider } from "../../primitives";
+import { RenderEdit } from "../render-edit";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+function buildEntity(): EntityDefinition {
+  return {
+    fields: {
+      name: { type: "text", maxLength: 200, required: false, searchable: false, sortable: false },
+    },
+  };
+}
+
+function renderEditCapturingForm(
+  screen: EntityEditScreenDefinition,
+  extraTranslations?: TranslationsByLocale,
+): {
+  captured: FormProps | undefined;
+} {
+  let captured: FormProps | undefined;
+  const capturingForm = (props: FormProps): ReactNode => {
+    captured = props;
+    return props.children;
+  };
+  const primitives: CorePrimitives = {
+    Button: noop,
+    Banner: noop,
+    Field: passChildren,
+    Input: noop,
+    DataTable: noop,
+    Form: capturingForm,
+    Section: passChildren,
+    Card: passChildren,
+    Grid: passChildren,
+    GridCell: passChildren,
+    Text: passChildren,
+    Heading: noop,
+    Dialog: noop,
+    Modal: noop,
+    Lightbox: noop,
+    ConfigSourceBadge: noop,
+    ConfigCascadeView: noop,
+    Link: noop,
+  };
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={
+        extraTranslations !== undefined
+          ? [extraTranslations, kumikoDefaultTranslations]
+          : [kumikoDefaultTranslations]
+      }
+    >
+      <PrimitivesProvider value={primitives}>
+        <RenderEdit
+          screen={screen}
+          entity={buildEntity()}
+          featureName="widgets"
+          initial={{ name: "" }}
+        />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+  return { captured };
+}
+
+describe("RenderEdit — screen.description as form subtitle (fw#2723)", () => {
+  test("a screen with description renders it as the form's subtitle", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      description: "Edit the widget's basic details.",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen);
+
+    expect(captured?.subtitle).toBe("Edit the widget's basic details.");
+  });
+
+  test("a description that is a known i18n key renders translated, not as the raw key", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      description: "widgets:widget-edit.explainer",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen, {
+      "en-US": { "widgets:widget-edit.explainer": "Every field here is optional." },
+    });
+
+    expect(captured?.subtitle).toBe("Every field here is optional.");
+  });
+
+  test("a screen without description renders no subtitle prop at all (no empty placeholder)", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen);
+
+    expect(captured).toBeDefined();
+    expect(captured && "subtitle" in captured).toBe(false);
+  });
+});

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

@@ -10,7 +10,7 @@ import type {
   ListRowViewModel,
   Translate,
 } from "@cosmicdrift/kumiko-headless";
-import { type ReactNode, useMemo } from "react";
+import { type ReactNode, useMemo, useState } from "react";
 import { useNav } from "../app/nav";
 import {
   buildProjectionRowActions,
@@ -19,9 +19,11 @@ import {
 } from "../app/row-actions";
 import { dispatcherErrorText } from "../app/write-failed-error";
 import { useOptionalDispatcher } from "../context/dispatcher-context";
+import type { ListSort } from "../hooks/use-list-url-state";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { sortByAccessor } from "../sort-by-accessor";
 import { RenderList } from "./render-list";
 
 const RELATED_LIST_PSEUDO_ENTITY = "__related-list__";
@@ -36,14 +38,16 @@ type PagedRows = {
 };
 
 // Minimal EntityDefinition from the section's own columns — same shape as
-// projection-list-shim's synthesizeProjectionEntity, but relatedList columns
-// aren't sortable (no sort UI on this section, see RelatedListSection below).
+// projection-list-shim's synthesizeProjectionEntity, but sortable is read
+// per-column (ListColumnSpec.sortable) instead of screen-wide, since a
+// relatedList section has no single Zod schema to derive it from.
 function synthesizeRelatedListEntity(
   columns: EditRelatedListSectionViewModel["columns"],
 ): EntityDefinition {
-  const fields: Record<string, { type: "text" }> = {};
+  const fields: Record<string, { type: "text"; sortable: boolean }> = {};
   for (const col of columns) {
-    fields[normalizeListColumn(col).field] = { type: "text" };
+    const normalized = normalizeListColumn(col);
+    fields[normalized.field] = { type: "text", sortable: normalized.sortable === true };
   }
   return { fields } as unknown as EntityDefinition;
 }
@@ -69,7 +73,7 @@ export function RelatedListSection({
     initialValues: Readonly<Record<string, unknown>> | undefined,
   ) => void;
 }): ReactNode {
-  const { Banner, Section } = usePrimitives();
+  const { Banner, Section, FillContainer } = usePrimitives();
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
@@ -100,6 +104,28 @@ export function RelatedListSection({
 
   const rowsQuery = useQuery<PagedRows>(section.query, payload);
 
+  // Sorted client-side over the already-loaded rows — this section has no
+  // pager (see `payload` above: a one-shot fetch, no cursor/offset), so the
+  // loaded set already IS the full display set and there is no "other page"
+  // a client-side sort could misleadingly hide (fw#2722).
+  const [sort, setSort] = useState<ListSort | null>(section.defaultSort ?? null);
+  const sortAccessors = useMemo(() => {
+    const accessors: Record<string, (row: Readonly<Record<string, unknown>>) => string | number> =
+      {};
+    for (const col of section.columns) {
+      const field = normalizeListColumn(col).field;
+      accessors[field] = (row) => {
+        const value = row[field];
+        return typeof value === "number" ? value : String(value ?? "");
+      };
+    }
+    return accessors;
+  }, [section.columns]);
+  const sortedRows = useMemo(
+    () => sortByAccessor(rowsQuery.data?.rows ?? [], sort, sortAccessors),
+    [rowsQuery.data, sort, sortAccessors],
+  );
+
   const rowClick = section.rowClick;
   // A row-body click target comes from EITHER the legacy `rowClick` field OR
   // a `rowActions` entry marked rowClick:true — the boot-validator rejects
@@ -136,6 +162,14 @@ export function RelatedListSection({
   );
   const rowActionMode = rowActionModeFor(rowActions);
 
+  // A truncated fetch means `sortedRows` is a sort of a partial set, not of
+  // the full related-row set — the client-side sort above (or even plain
+  // unsorted display) would silently claim "these are the top N" when they
+  // are really just "the first N in the server's own order" (fw#2722 review).
+  // `nextCursor` is exactly how the paged envelope marks that: non-null means
+  // more rows exist server-side beyond what was fetched.
+  const truncated = rowsQuery.data !== null && rowsQuery.data.nextCursor !== null;
+
   const content =
     rowsQuery.loading && rowsQuery.data === null ? (
       <Banner padded variant="loading" testId="related-list-loading">
@@ -146,24 +180,47 @@ export function RelatedListSection({
         {dispatcherErrorText(rowsQuery.error, effectiveTranslate)}
       </Banner>
     ) : (
-      <RenderList
-        screen={listScreen}
-        entity={entity}
-        rows={rowsQuery.data?.rows ?? []}
-        featureName={featureName}
-        translate={effectiveTranslate}
-        {...(onRowClick !== undefined && { onRowClick })}
-        {...(rowActions !== undefined && { rowActions })}
-        {...(rowActionMode !== undefined && { rowActionMode })}
-      />
+      <>
+        {truncated && (
+          <Banner variant="info" testId="related-list-truncated">
+            {effectiveTranslate("kumiko.list.related-list-truncated", {
+              count: sortedRows.length,
+            })}
+          </Banner>
+        )}
+        <RenderList
+          screen={listScreen}
+          entity={entity}
+          rows={sortedRows}
+          featureName={featureName}
+          translate={effectiveTranslate}
+          sort={sort}
+          onSortChange={setSort}
+          {...(onRowClick !== undefined && { onRowClick })}
+          {...(rowActions !== undefined && { rowActions })}
+          {...(rowActionMode !== undefined && { rowActionMode })}
+          {...(hideTitle === true && { chromeless: true, scrollBody: true })}
+        />
+      </>
     );
 
-  // hideTitle (tabs mode) → this section carries no header content of its
-  // own, and RenderList's DataTable already draws its own card frame — a
-  // Section wrapper here would only add a second, nested card (fw record-
-  // screen-type polish). Stacked (non-tabs) sections keep their Section
-  // card since they render a visible title.
-  if (hideTitle) return content;
+  // hideTitle (tabs mode) → the tab panel is already the boundary: no
+  // Section card wrapper here, `chromeless` above drops the table's own
+  // card frame too, and `scrollBody` fills this wrapper's height so a long
+  // Akte tab scrolls internally instead of stretching the page (fw#2722) —
+  // the list sits directly in the tab. `FillContainer` is this section's
+  // link in RenderEdit's `fillHeight` chain (see render-edit.tsx): it is
+  // always this section's own root whenever hideTitle is set, since tabs
+  // mode narrows RenderEdit to exactly this one active section. A platform
+  // primitive (not a raw `<div>`) because `renderer` stays DOM-free —
+  // `Section`/`Card` were rejected for this spot in favor of a dedicated
+  // chromeless primitive; see `FillContainerProps` in primitives.tsx.
+  // Stacked (non-tabs) sections keep the card frame and document-flow
+  // height since they render a visible title and aren't confined to a tab
+  // panel.
+  if (hideTitle) {
+    return FillContainer !== undefined ? <FillContainer>{content}</FillContainer> : content;
+  }
 
   return (
     <Section title={section.title} testId={`related-list-${section.title}`}>

package/src/components/render-edit.tsx

@@ -628,6 +628,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // true when editable fields exist or an extension opted into composed submit (fw#2359).
   const isFormEditable = hasEditableSection(filteredSections);
 
+  // A lone relatedList tab (hideSectionTitles is only ever set by the tabs
+  // layout, which also narrows filteredSections to that one active section)
+  // needs its own tab panel to fill the available height so its table
+  // scrolls inside the panel instead of the whole page stretching to the
+  // row count (fw#2722). Any other layout — multiple sections, a non-
+  // relatedList tab, stacked (non-tabs) forms — keeps normal document-flow
+  // height untouched.
+  const fillHeight = hideSectionTitles === true && filteredSections[0]?.kind === "relatedList";
+
   // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
   // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
   // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
@@ -1036,7 +1045,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
   //   screen:<id>.<mode>.title / .<mode>.subtitle
   // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
-  // title falls back to screenId; subtitle to undefined (no subtitle).
+  // title falls back to screenId; subtitle falls back to screen.description,
+  // itself run through translate() so an i18n key (the established
+  // convention for description, e.g. bundled-features) resolves instead of
+  // showing the raw key — translate() returns the input unchanged for plain
+  // prose, same as it does for an unknown key (fw#2723 review). Same slot
+  // section.description already fills for a section. Falls back to
+  // undefined (no subtitle) when neither is set.
   const isCreate = (() => {
     const id = resolveExtensionEntityId(entityIdProp, vm.id);
     return id == null || id === "";
@@ -1053,7 +1068,9 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     return undefined;
   };
   const formTitle = resolveScreenText("title") ?? screen.id;
-  const formSubtitle = resolveScreenText("subtitle");
+  const formSubtitle =
+    resolveScreenText("subtitle") ??
+    (screen.description !== undefined ? translate(screen.description) : undefined);
 
   return (
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>
@@ -1069,6 +1086,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
         {...(headerRegion !== undefined && { headerRegion })}
+        {...(fillHeight && { fillHeight })}
       >
         {draftCandidates !== null && (
           <Banner

package/src/components/render-list.tsx

@@ -110,6 +110,14 @@ export type RenderListProps = {
   readonly onFilterChange?: (field: string, values: readonly string[]) => void;
   /** Reset aller aktiven Facets. */
   readonly onFilterReset?: () => void;
+  /** Forwarded to `DataTableProps.chromeless` — drops the table's own card
+   *  frame for a host that already provides one (relatedList in a tabs-mode
+   *  section, fw#2722). Default false. */
+  readonly chromeless?: boolean;
+  /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and
+   *  scrolls rows internally instead of growing the page (relatedList in a
+   *  tabs-mode section, fw#2722). Default false. */
+  readonly scrollBody?: boolean;
 };
 
 // Resolved-Form einer Toolbar-Action: KumikoScreen baut das aus dem
@@ -158,6 +166,8 @@ export function RenderList(props: RenderListProps): ReactNode {
     filterValues,
     onFilterChange,
     onFilterReset,
+    chromeless,
+    scrollBody,
   } = props;
   // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
   // wären Column-Header raw i18n-Keys.
@@ -372,6 +382,8 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(filterValues !== undefined && { filterValues })}
         {...(onFilterChange !== undefined && { onFilterChange })}
         {...(onFilterReset !== undefined && { onFilterReset })}
+        {...(chromeless !== undefined && { chromeless })}
+        {...(scrollBody !== undefined && { scrollBody })}
         testId="render-list-table"
       />
     </>

package/src/i18n-defaults.ts

@@ -64,6 +64,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.end-of-list": "— End of list —",
     "kumiko.list.sort.label": "Sort",
     "kumiko.list.sort.unsorted": "Unsorted",
+    "kumiko.list.related-list-truncated":
+      "Showing the first {count} entries. More are available but not loaded — this list does not paginate.",
     "kumiko.reference.system-tenant": "System",
 
     "kumiko.pager.status": "{from}–{to} of {total}",

package/src/index.ts

@@ -184,6 +184,7 @@ export type {
   EmbeddedListInputProps,
   EmbeddedListTotal,
   FieldProps,
+  FillContainerProps,
   FormProps,
   FormWidth,
   GridCellProps,

package/src/primitives.tsx

@@ -618,6 +618,20 @@ export type DataTableProps = {
   readonly getRowTestId?: (row: ListRowViewModel) => string;
   /** Overrides the cell `data-testid` (default `cell-${row.id}-${field}`). */
   readonly getCellTestId?: (row: ListRowViewModel, field: string) => string;
+  /** Drops the table's own rounded/border/card background — for a host
+   *  that already provides the surrounding boundary (a tab panel, fw#2722)
+   *  and would otherwise show a card nested inside that boundary. Default
+   *  false: unchanged card-framed table. */
+  readonly chromeless?: boolean;
+  /** Fills the available height of its flex container and scrolls rows
+   *  internally instead of growing with row count — for a host that would
+   *  otherwise have a long table stretch the whole page, or a short table
+   *  leave dead space below it (a tab panel, fw#2722). Requires the same
+   *  flex-fill chain FormProps.fillHeight sets up above it; without that
+   *  ancestor chain this collapses to zero height (Web: `flex-1 min-h-0`
+   *  has no effect outside a sized flex-col ancestor). Default false:
+   *  unchanged document-flow table that grows with its content. */
+  readonly scrollBody?: boolean;
 };
 
 // ---- EmbeddedListInput (createEmbeddedListField widget) ----
@@ -750,6 +764,14 @@ export type FormProps = {
    *  instead of rendering as unpadded siblings before it. Native impls may
    *  ignore this prop. */
   readonly headerRegion?: ReactNode;
+  /** Sizes the form to fill its container's height (instead of the page's
+   *  natural content height) so a single scrolling child — a lone
+   *  relatedList tab's table — can scroll internally instead of stretching
+   *  the whole page (fw#2722). Only set by RenderEdit for a lone relatedList
+   *  tab section; every other caller leaves it unset and keeps normal
+   *  document-flow height. Native impls may ignore this prop (already a
+   *  bounded viewport there). */
+  readonly fillHeight?: boolean;
 };
 
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
@@ -779,6 +801,21 @@ export type SectionProps = {
   readonly icon?: IconKey;
 };
 
+/** Chromeless flex-fill layout host — no title, no card frame, no padding,
+ *  just a container that sizes to fill its parent and lets one scrolling
+ *  child scroll internally instead of the page growing (fw#2722). Web:
+ *  `<div className="flex flex-1 min-h-0 flex-col">`. Native: Views are
+ *  already flex-column and the parent is already a bounded viewport there,
+ *  so a native impl may render this as a bare Fragment. Used only as the
+ *  terminal link in `RenderEdit`'s `fillHeight` chain (`RelatedListSection`'s
+ *  `hideTitle` branch) — `Section`/`Card` were rejected here because both
+ *  carry title/padding/border chrome this spot doesn't want and would double
+ *  up with the table's own padding. */
+export type FillContainerProps = {
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
 /** Columns-basiertes Layout. Web: CSS grid, Native: Flex-Wrap mit
  *  Width-%, oder react-native-grid. Jedes direkte Child kann eine
  *  `GridCell`-Wrapping bekommen für span-Kontrolle.
@@ -1134,6 +1171,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 JsonView?: ComponentType<JsonViewProps>;
+  /** 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 FillContainer?: ComponentType<FillContainerProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern