@cosmicdrift/kumiko-renderer 0.202.0 → 0.203.0

package/package.json

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

package/src/app/__tests__/build-list-query-payload.test.ts

@@ -0,0 +1,107 @@
+// fw#2165: buildListQueryPayload was extracted out of EntityListBody's
+// queryPayload useMemo so ProjectionListBody could reuse it without
+// duplicating the branch logic. This pins the extracted function against
+// exactly what EntityListBody built before the extraction — the regression
+// floor both list types now sit on.
+import { describe, expect, test } from "bun:test";
+import { buildListQueryPayload } from "../kumiko-screen";
+
+const base = {
+  limit: 50,
+  search: "",
+  sort: null,
+  usePager: false,
+  page: 1,
+  useInfinite: false,
+  cursor: undefined,
+} as const;
+
+describe("buildListQueryPayload", () => {
+  test("bare state: only limit, no search/sort/pager/infinite keys", () => {
+    expect(buildListQueryPayload(base)).toEqual({ limit: 50 });
+  });
+
+  test("empty search term is omitted, not sent as an empty string", () => {
+    expect(buildListQueryPayload({ ...base, search: "" })).toEqual({ limit: 50 });
+  });
+
+  test("non-empty search lands in the payload", () => {
+    expect(buildListQueryPayload({ ...base, search: "acme" })).toEqual({
+      limit: 50,
+      search: "acme",
+    });
+  });
+
+  test("no sort: neither sort nor sortDirection appear", () => {
+    expect(buildListQueryPayload({ ...base, sort: null })).toEqual({ limit: 50 });
+  });
+
+  test("sort carries both field and direction", () => {
+    expect(buildListQueryPayload({ ...base, sort: { field: "createdAt", dir: "desc" } })).toEqual({
+      limit: 50,
+      sort: "createdAt",
+      sortDirection: "desc",
+    });
+  });
+
+  test("pager mode, page 1: totalCount is sent, offset is omitted (not offset: 0)", () => {
+    expect(buildListQueryPayload({ ...base, usePager: true, page: 1 })).toEqual({
+      limit: 50,
+      totalCount: true,
+    });
+  });
+
+  test("pager mode, page 3: offset is (page - 1) * limit", () => {
+    expect(buildListQueryPayload({ ...base, usePager: true, page: 3 })).toEqual({
+      limit: 50,
+      offset: 100,
+      totalCount: true,
+    });
+  });
+
+  test("infinite mode without a cursor yet: no cursor key", () => {
+    expect(buildListQueryPayload({ ...base, useInfinite: true, cursor: undefined })).toEqual({
+      limit: 50,
+    });
+  });
+
+  test("infinite mode with a cursor: cursor lands in the payload", () => {
+    expect(buildListQueryPayload({ ...base, useInfinite: true, cursor: "row-42" })).toEqual({
+      limit: 50,
+      cursor: "row-42",
+    });
+  });
+
+  test("pager wins over infinite when both flags are true (usePager gates first)", () => {
+    expect(
+      buildListQueryPayload({ ...base, usePager: true, useInfinite: true, cursor: "row-42" }),
+    ).toEqual({ limit: 50, totalCount: true });
+  });
+
+  test("pagination=false (neither pager nor infinite): no pagination keys at all", () => {
+    expect(
+      buildListQueryPayload({ ...base, usePager: false, useInfinite: false, cursor: "row-42" }),
+    ).toEqual({ limit: 50 });
+  });
+
+  test("full combination: search + sort + pager", () => {
+    expect(
+      buildListQueryPayload({
+        limit: 25,
+        search: "acme",
+        sort: { field: "name", dir: "asc" },
+        usePager: true,
+        page: 2,
+        useInfinite: false,
+        cursor: undefined,
+      }),
+    ).toEqual({
+      limit: 25,
+      search: "acme",
+      sort: "name",
+      sortDirection: "asc",
+      offset: 25,
+      totalCount: true,
+    });
+  });
+});

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

@@ -0,0 +1,449 @@
+// fw#2166: projectionDetail screens can declare header `actions`, and get a
+// default "edit" action for free when `detailFor` names an entity that has a
+// visible entityEdit screen somewhere in the app (not just this feature —
+// the motivating case is a projectionDetail whose query belongs to one
+// feature while the entity's entityEdit screen lives in another). This
+// renders the real path (KumikoScreen → ProjectionDetailBody → RenderEdit)
+// under a stub dispatcher + AppFeaturesProvider, and proves the default-edit
+// resolution rules from the boot-validator's detailFor doc (cross-feature
+// lookup, access-gating, id: "edit" declared-action suppression).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  AccessRule,
+  EntityEditScreenDefinition,
+  ProjectionDetailScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, fireEvent, render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { UserRolesProvider } from "../../context/user-roles-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type BannerProps,
+  type ButtonProps,
+  type CorePrimitives,
+  type FormProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { AppFeaturesProvider } from "../app-features-context";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi, ScreenTarget } from "../nav";
+import { NavProvider } from "../nav";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) => (
+  <button type="button" data-testid={testId} onClick={() => void onClick?.()}>
+    {children}
+  </button>
+);
+
+// Form's `actions` slot carries the header buttons under test — passChildren
+// alone would drop it. 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 }) => (
+  <>
+    <div data-testid="form-body">{children}</div>
+    <div data-testid="form-actions">{actions}</div>
+  </>
+);
+
+// passChildren would drop testId — this test asserts on Banner structure/
+// placement, so it needs a real (if minimal) wrapper element.
+const TestBanner: ComponentType<BannerProps> = ({ children, testId }) => (
+  <div data-testid={testId}>{children}</div>
+);
+
+const testPrimitives: CorePrimitives = {
+  Button: TestButton,
+  Banner: TestBanner,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: FormWithActions,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function stubDispatcher(
+  record: Readonly<Record<string, unknown>>,
+  writeErrorMessage?: string,
+): Dispatcher {
+  const writeResult =
+    writeErrorMessage !== undefined
+      ? {
+          isSuccess: false,
+          error: {
+            code: "write-failed",
+            httpStatus: 500,
+            i18nKey: "kumiko.errors.does-not-exist-in-any-bundle",
+            message: writeErrorMessage,
+          },
+        }
+      : { isSuccess: true, data: {} };
+  return {
+    write: (async () => writeResult) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: record })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function detailScreen(
+  overrides?: Partial<ProjectionDetailScreenDefinition & { readonly detailFor?: string }>,
+): FeatureSchema["screens"][number] {
+  return {
+    id: "rent-detail",
+    type: "projectionDetail",
+    query: "app:query:rent:detail",
+    layout: { sections: [{ title: "s", fields: ["description"] }] },
+    detailFor: "rent",
+    ...overrides,
+  } as FeatureSchema["screens"][number];
+}
+
+// Registry-qualified id ("<feature>:screen:<short>"), matching real schema
+// output — a bare short id here would hide the QN-vs-short-form bug this
+// test suite exists to catch (fw#2166 review finding 1/4).
+function editScreen(
+  entity: string,
+  access?: AccessRule,
+  featureName = "app",
+): EntityEditScreenDefinition {
+  return {
+    id: `${featureName}:screen:rent-edit`,
+    type: "entityEdit",
+    entity,
+    layout: { sections: [{ columns: 1, fields: ["name"] }] },
+    ...(access !== undefined && { access }),
+  };
+}
+
+function renderDetail(opts: {
+  readonly primarySchema: FeatureSchema;
+  readonly features: readonly FeatureSchema[];
+  readonly userRoles?: readonly string[];
+  readonly record?: Readonly<Record<string, unknown>>;
+  readonly onNavigate?: (target: ScreenTarget) => void;
+  readonly writeErrorMessage?: string;
+}): ReturnType<typeof render> {
+  const navApi: NavApi = {
+    route: { screenId: "app:screen:rent-detail" },
+    // Header actions only ever navigate with a ScreenTarget (screenId +
+    // entityId) — same narrowing idiom as nav.tsx's resolveTarget.
+    navigate: (target) => {
+      if ("screenId" in target) opts.onNavigate?.(target);
+    },
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: () => {},
+  };
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider
+        dispatcher={stubDispatcher(
+          opts.record ?? { id: "rent-1", description: "Rent for April" },
+          opts.writeErrorMessage,
+        )}
+      >
+        <AppFeaturesProvider features={opts.features}>
+          <UserRolesProvider roles={opts.userRoles}>
+            <NavProvider value={navApi}>
+              <PrimitivesProvider value={testPrimitives}>
+                <KumikoScreen
+                  schema={opts.primarySchema}
+                  qn="app:screen:rent-detail"
+                  entityId="rent-1"
+                />
+              </PrimitivesProvider>
+            </NavProvider>
+          </UserRolesProvider>
+        </AppFeaturesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionDetail default edit action (fw#2166)", () => {
+  test("detailFor + matching entityEdit in the SAME feature → edit button navigates with the record id", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), editScreen("rent")],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    // trigger() is async (busy-state bookkeeping around onPress), so the
+    // click's state updates land after this tick — act() flushes them.
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
+  });
+
+  test("edit screen access denied → no edit button", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), editScreen("rent", { roles: ["admin"] })],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-edit")).toBeNull();
+  });
+
+  test("no entityEdit screen for the detailFor entity → no edit button", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen()],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-edit")).toBeNull();
+  });
+
+  test('a declared actions entry with id: "edit" wins — exactly one edit button, the declared one', async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            { kind: "navigate", id: "edit", label: "custom-edit-label", screen: "rent-edit" },
+          ],
+        }),
+        editScreen("rent"),
+      ],
+    };
+    const { getAllByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    const editButtons = getAllByTestId("render-edit-action-edit");
+    expect(editButtons).toHaveLength(1);
+    // "custom-edit-label" has no translation registered, so translate()
+    // returns the raw key — proving this is the declared action, not the
+    // default (which renders the translated "kumiko.actions.edit").
+    expect(editButtons[0]?.textContent).toBe("custom-edit-label");
+  });
+
+  test("two entityEdit screens for the same entity, only the second accessible → button still renders, targeting the second (review finding 2)", async () => {
+    const lockedEdit: EntityEditScreenDefinition = {
+      id: "app:screen:rent-edit-locked",
+      type: "entityEdit",
+      entity: "rent",
+      layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      access: { roles: ["admin"] },
+    };
+    const openEdit: EntityEditScreenDefinition = {
+      id: "app:screen:rent-edit-open",
+      type: "entityEdit",
+      entity: "rent",
+      layout: { sections: [{ columns: 1, fields: ["name"] }] },
+    };
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen(), lockedEdit, openEdit],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit-open", entityId: "rent-1" });
+  });
+
+  test("declared navigate action without entityId, targeting an entityEdit of the SAME entity → auto-fills the record id (review finding 3)", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "navigate",
+              id: "open-record",
+              label: "actions.openRecord",
+              screen: "rent-edit",
+            },
+          ],
+        }),
+        editScreen("rent"),
+      ],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-open-record"));
+    });
+    expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
+  });
+
+  test("declared action with a non-matching visible condition → no button rendered", async () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "navigate",
+              id: "archive",
+              label: "actions.archive",
+              screen: "rent-edit",
+              visible: { field: "status", eq: "closed" },
+            },
+          ],
+        }),
+      ],
+    };
+    const { queryByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      record: { id: "rent-1", description: "Rent for April", status: "open" },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    expect(queryByTestId("render-edit-action-archive")).toBeNull();
+  });
+
+  test("entityEdit screen lives in ANOTHER feature → edit button is still there (cross-feature resolution)", async () => {
+    const appSchema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [detailScreen()],
+    };
+    const billingSchema: FeatureSchema = {
+      featureName: "billing",
+      entities: {},
+      screens: [editScreen("rent", undefined, "billing")],
+    };
+    let navigated: ScreenTarget | undefined;
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: appSchema,
+      features: [appSchema, billingSchema],
+      userRoles: [],
+      onNavigate: (target) => {
+        navigated = target;
+      },
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    // trigger() is async (busy-state bookkeeping around onPress), so the
+    // click's state updates land after this tick — act() flushes them.
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-edit"));
+    });
+    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 () => {
+    const schema: FeatureSchema = {
+      featureName: "app",
+      entities: {},
+      screens: [
+        detailScreen({
+          actions: [
+            {
+              kind: "writeHandler",
+              id: "archive",
+              label: "actions.archive",
+              handler: "app:write:archive",
+            },
+          ],
+        }),
+      ],
+    };
+    const { getByTestId, queryByText } = renderDetail({
+      primarySchema: schema,
+      features: [schema],
+      userRoles: [],
+      writeErrorMessage: "archive failed: rent is still active",
+    });
+    await waitFor(() => expect(queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(getByTestId("render-edit-action-archive"));
+    });
+
+    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();
+    expect(errorBanner.closest('[data-testid="form-actions"]')).toBeNull();
+    expect(
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+    ).not.toBeNull();
+  });
+});

package/src/app/__tests__/projection-list-search-sort.test.tsx

@@ -0,0 +1,212 @@
+// fw#2165: ProjectionListBody used to fetch with a hardcoded empty payload —
+// search/sort/pagination were rendered but had no effect. This renders the
+// real path (KumikoScreen → ProjectionListScreen → ProjectionListBody →
+// RenderList) under a stub dispatcher that records every query() call, and a
+// stateful NavProvider so setSearchParams actually re-renders — proving the
+// URL-state → payload wiring for the two capabilities buildAppSchema derives
+// per-screen (searchable, sortable).
+
+import { describe, expect, test } from "bun:test";
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, render, waitFor } from "@testing-library/react";
+import { type ComponentType, type ReactNode, useState } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import { type CorePrimitives, type DataTableProps, PrimitivesProvider } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi } from "../nav";
+import { NavProvider } from "../nav";
+
+let capturedProps: DataTableProps | undefined;
+const captureDataTable: ComponentType<DataTableProps> = (props) => {
+  capturedProps = props;
+  return null;
+};
+// Indirection defeats TS narrowing `capturedProps` to `undefined` at read
+// sites — the compiler can't see that `captureDataTable` (a React render
+// callback) reassigns it between the reset and the read.
+const getCapturedProps = (): DataTableProps | undefined => capturedProps;
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: captureDataTable,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+let queryCalls: Array<{ readonly type: string; readonly payload: unknown }> = [];
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string, payload: unknown) => {
+      queryCalls.push({ type, payload });
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function buildSchema(screen: ProjectionListScreenDefinition): FeatureSchema {
+  return {
+    featureName: "ledger",
+    entities: {},
+    screens: [screen],
+  } as FeatureSchema;
+}
+
+// Stateful nav so setSearchParams (called by useListUrlState) actually
+// re-renders the tree — a plain mock object wouldn't trigger React.
+function StatefulNav({
+  initialParams,
+  children,
+}: {
+  readonly initialParams: Record<string, string>;
+  readonly children: ReactNode;
+}): ReactNode {
+  const [params, setParams] = useState<Record<string, string>>(initialParams);
+  const value: NavApi = {
+    route: { screenId: "ledger:screen:schedule-list" },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: params,
+    setSearchParams: (updates) => {
+      setParams((prev) => {
+        const next = { ...prev };
+        for (const [k, v] of Object.entries(updates)) {
+          if (v === null) delete next[k];
+          else next[k] = v;
+        }
+        return next;
+      });
+    },
+  };
+  return <NavProvider value={value}>{children}</NavProvider>;
+}
+
+function renderProjectionList(
+  screen: ProjectionListScreenDefinition,
+  initialParams: Record<string, string> = {},
+): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <StatefulNav initialParams={initialParams}>
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={buildSchema(screen)} qn="ledger:screen:schedule-list" />
+          </PrimitivesProvider>
+        </StatefulNav>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("ProjectionListBody — search/sort capability wiring (fw#2165)", () => {
+  test("search-capable screen: a URL search term lands in the query payload", async () => {
+    queryCalls = [];
+    renderProjectionList(
+      {
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: true,
+      },
+      { "schedule-list.q": "acme" },
+    );
+
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(0));
+    expect(queryCalls[0]?.payload).toMatchObject({ search: "acme" });
+  });
+
+  test("non-search-capable screen: the same URL search term is NOT sent (schema doesn't accept it)", async () => {
+    queryCalls = [];
+    renderProjectionList(
+      {
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+      },
+      { "schedule-list.q": "acme" },
+    );
+
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(0));
+    expect(queryCalls[0]?.payload).not.toHaveProperty("search");
+  });
+
+  test("sort-capable screen: the column is rendered sortable, and a header click updates state and payload", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    renderProjectionList({
+      id: "schedule-list",
+      type: "projectionList",
+      query: "ledger:query:schedule:list",
+      columns: ["description"],
+      sortable: true,
+      defaultSort: { field: "description", dir: "asc" },
+    });
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const sortableProps = getCapturedProps();
+    if (sortableProps === undefined) throw new Error("DataTable was not rendered");
+    // Column-click affordance is only wired when the query schema accepts
+    // sort — DefaultDataTable gates the header click on col.sortable.
+    expect(sortableProps.columns.find((c) => c.field === "description")?.sortable).toBe(true);
+
+    const countBeforeClick = queryCalls.length;
+    await act(async () => {
+      capturedProps?.onSortChange?.({ field: "description", dir: "desc" });
+    });
+
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(countBeforeClick));
+    const lastPayload = queryCalls[queryCalls.length - 1]?.payload;
+    expect(lastPayload).toMatchObject({ sort: "description", sortDirection: "desc" });
+  });
+
+  test("non-sort-capable screen: the column is rendered NOT sortable", async () => {
+    capturedProps = undefined;
+    renderProjectionList({
+      id: "schedule-list",
+      type: "projectionList",
+      query: "ledger:query:schedule:list",
+      columns: ["description"],
+    });
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const notSortableProps = getCapturedProps();
+    if (notSortableProps === undefined) throw new Error("DataTable was not rendered");
+    expect(notSortableProps.columns.find((c) => c.field === "description")?.sortable).toBe(false);
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -27,15 +27,16 @@ import type {
 import { fieldLabelKey } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId } from "../components/reference-create-dialog";
-import { RenderEdit } from "../components/render-edit";
+import { RenderEdit, type RenderEditAction } from "../components/render-edit";
 import { RenderList, type ToolbarActionButton } from "../components/render-list";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context";
 import { useUserRoles } from "../context/user-roles-context";
-import { useListUrlState } from "../hooks/use-list-url-state";
+import { type ListSort, useListUrlState } from "../hooks/use-list-url-state";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
 import { type DataTableFacet, type DataTableRowAction, usePrimitives } from "../primitives";
 import { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./action-form-shim";
+import { useAppFeatures } from "./app-features-context";
 import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config-edit-shim";
 import { useCustomScreenComponent } from "./custom-screens";
 import { useDashboardBody } from "./dashboard-body";
@@ -823,6 +824,40 @@ type PagedRows = {
   readonly total?: number;
 };
 
+// Payload for the server-side list query handler (LIST_PAYLOAD_SCHEMA):
+// search/sort/sortDirection/limit + offset/totalCount for pager mode OR
+// cursor for infinite scroll. Shared by EntityListBody and
+// ProjectionListBody so the two branches can't drift on this shape
+// (fw#2165) — entity-only additions (screen.filter, faceted filters) are
+// layered on top by the caller instead of living in here.
+export function buildListQueryPayload(state: {
+  readonly limit: number;
+  readonly search: string;
+  readonly sort: ListSort | null;
+  readonly usePager: boolean;
+  readonly page: number;
+  readonly useInfinite: boolean;
+  readonly cursor: string | undefined;
+}): Record<string, unknown> {
+  const payload: Record<string, unknown> = { limit: state.limit };
+  if (state.search !== "") payload["search"] = state.search;
+  if (state.sort !== null) {
+    payload["sort"] = state.sort.field;
+    payload["sortDirection"] = state.sort.dir;
+  }
+  if (state.usePager) {
+    // page=1 → offset=0, page=2 → offset=limit, etc. Server clamps itself
+    // when offset >= total.
+    const offset = (state.page - 1) * state.limit;
+    if (offset > 0) payload["offset"] = offset;
+    // totalCount: extra COUNT(*) so the pager can render "Page X of Y".
+    payload["totalCount"] = true;
+  } else if (state.useInfinite && state.cursor !== undefined) {
+    payload["cursor"] = state.cursor;
+  }
+  return payload;
+}
+
 function EntityListScreen({
   schema,
   screen,
@@ -935,16 +970,18 @@ function EntityListBody({
     return out;
   }, [urlState.filters, entity.fields]);
 
-  // Payload für den Server-Query-Handler (LIST_PAYLOAD_SCHEMA):
-  // search/sort/sortDirection/limit + offset/totalCount für Pager-Mode
-  // ODER cursor für Infinite-Scroll.
+  // Entity-only additions (screen.filter, faceted filters) layer on top of
+  // the shared buildListQueryPayload — projectionList has neither.
   const queryPayload = useMemo(() => {
-    const payload: Record<string, unknown> = { limit };
-    if (urlState.q !== "") payload["search"] = urlState.q;
-    if (effectiveSort !== null) {
-      payload["sort"] = effectiveSort.field;
-      payload["sortDirection"] = effectiveSort.dir;
-    }
+    const payload = buildListQueryPayload({
+      limit,
+      search: urlState.q,
+      sort: effectiveSort,
+      usePager,
+      page: urlState.page,
+      useInfinite,
+      cursor,
+    });
     // Screen-Filter (Tier 2.7c) — vom Author am Schema deklariert,
     // unabhängig vom User-q-Search. Mehrere Buckets derselben Entity
     // ("Upcoming" / "Active" / "Past") nutzen unterschiedliche filter
@@ -955,18 +992,6 @@ function EntityListBody({
     if (filterPayload.length > 0) {
       payload["filters"] = filterPayload;
     }
-    if (usePager) {
-      // page=1 → offset=0, page=2 → offset=limit, etc. Server
-      // clampt selbst wenn offset >= total.
-      const offset = (urlState.page - 1) * limit;
-      if (offset > 0) payload["offset"] = offset;
-      // totalCount: extra COUNT(*) damit der Pager "Page X of Y"
-      // rendern kann. Bei pagination=false oder "infinite" sparen wir
-      // den Roundtrip.
-      payload["totalCount"] = true;
-    } else if (useInfinite && cursor !== undefined) {
-      payload["cursor"] = cursor;
-    }
     return payload;
   }, [
     limit,
@@ -1337,11 +1362,13 @@ function EntityListBody({
 
 // ---- projection-list ----
 
-// Wie entityList, aber die List-Query kommt DIREKT aus `screen.query` (statt aus
-// der Entity abgeleitet) — dadurch cross-feature-fähig. v1 bewusst schlank:
-// rendert die Query-Rows mit den (explizit gelabelten) Columns + navigate-
-// RowActions/Row-Klick. Kein Server-Sort/-Pagination/-Facetten (eine Projection-
-// Query hat dafür keinen garantierten Contract) — die kommen bei Bedarf später.
+// Like entityList, but the list query comes DIRECTLY from `screen.query`
+// (instead of being derived from an entity) — cross-feature capable.
+// search/sort/pagination reuse the same URL-state + buildListQueryPayload
+// wiring as EntityListBody; which of them are actually offered is derived
+// from the query handler's Zod schema at buildAppSchema time (fw#2165), not
+// declared here. Pages-mode pagination only — infinite-scroll accumulation
+// isn't wired for projectionList.
 function ProjectionListBody({
   schema,
   screen,
@@ -1358,9 +1385,44 @@ function ProjectionListBody({
   const nav = useNav();
   const dispatcher = useOptionalDispatcher();
   const effectiveTranslate = translate ?? t;
-  const entity = useMemo(() => synthesizeProjectionEntity(screen.columns), [screen.columns]);
+
+  // searchable/sortable/paginated are derived at buildAppSchema time from the
+  // query handler's Zod schema (fw#2165) — not authored on the screen.
+  const searchable = screen.searchable ?? false;
+  const sortable = screen.sortable ?? false;
+  const paginated = screen.paginated ?? false;
+  const entity = useMemo(
+    () => synthesizeProjectionEntity(screen.columns, sortable),
+    [screen.columns, sortable],
+  );
   const listScreen = useMemo(() => synthesizeProjectionScreen(screen), [screen]);
-  const rowsQuery = useQuery<PagedRows>(screen.query, {}, { live: true });
+
+  const urlState = useListUrlState(screen.id);
+  // Gated on the derived capability, not just on whether URL-state happens to
+  // carry a value — a stale/hand-crafted URL (?…q=x on a non-searchable
+  // screen) must not smuggle a param the query's Zod schema doesn't accept.
+  const activeSearch = searchable ? urlState.q : "";
+  const activeSort = sortable ? (urlState.sort ?? screen.defaultSort ?? null) : null;
+  const limit = screen.pageSize ?? 50;
+  // Pages-mode only (see header comment) — an author-set pagination:
+  // "infinite" on a paginated projectionList is silently a no-op today.
+  const usePager = paginated && (screen.pagination ?? "pages") === "pages";
+
+  const queryPayload = useMemo(
+    () =>
+      buildListQueryPayload({
+        limit,
+        search: activeSearch,
+        sort: activeSort,
+        usePager,
+        page: urlState.page,
+        useInfinite: false,
+        cursor: undefined,
+      }),
+    [limit, activeSearch, activeSort, usePager, urlState.page],
+  );
+
+  const rowsQuery = useQuery<PagedRows>(screen.query, queryPayload, { live: true });
 
   const runNavigate = useCallback(
     (action: RowActionNavigate, row: ListRowViewModel) => {
@@ -1507,14 +1569,27 @@ function ProjectionListBody({
       ? (row: ListRowViewModel) => onRowClick(row, listScreen.entity)
       : undefined;
 
+  // Same pager-construction as EntityListBody: no Pager UI until the
+  // server-provided `total` arrives (guards pagination="pages" without
+  // totalCount support, see fw#2165 report on solon's leaseOverviewHandler).
+  const total = rowsQuery.data?.total;
+  const pager =
+    usePager && total !== undefined
+      ? { page: urlState.page, limit, total, onPageChange: urlState.setPage }
+      : undefined;
+
   return (
     <RenderList
       screen={listScreen}
       entity={entity}
       rows={rowsQuery.data?.rows ?? []}
       featureName={schema.featureName}
-      searchable={screen.searchable ?? false}
-      sort={screen.defaultSort ?? null}
+      searchable={searchable}
+      searchValue={urlState.q}
+      onSearchChange={urlState.setQ}
+      sort={activeSort}
+      onSortChange={urlState.setSort}
+      {...(pager !== undefined && { pager })}
       {...(rowActions !== undefined && { rowActions })}
       {...(toolbarActions !== undefined && { toolbarActions })}
       {...(translate !== undefined && { translate })}
@@ -1540,7 +1615,10 @@ function ProjectionDetailBody({
   entityId,
 }: {
   readonly schema: FeatureSchema;
-  readonly screen: ProjectionDetailScreenDefinition;
+  // detailFor sits on the ScreenDefinition intersection, not on the
+  // projectionDetail variant itself (screen.ts:832) — widen the prop type
+  // to keep reading it here instead of re-deriving it from schema.screens.
+  readonly screen: ProjectionDetailScreenDefinition & { readonly detailFor?: string };
   readonly translate?: Translate;
   readonly entityId?: string;
 }): ReactNode {
@@ -1561,6 +1639,144 @@ function ProjectionDetailBody({
     nav.navigate({ screenId: screen.listScreenId });
   }, [nav, screen.listScreenId]);
 
+  // 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
+  // the motivating case is a projectionDetail whose query belongs to one
+  // feature while the entity's entityEdit screen lives in another. Unlike
+  // useNavigateToCreateFor this must NOT filter on allowCreate/singleton —
+  // those gate create-targets, we're resolving an update-target by a
+  // known id.
+  const appFeatures = useAppFeatures();
+  const userRoles = useUserRoles();
+  const dispatcher = useOptionalDispatcher();
+  const editScreen = useMemo(() => {
+    const detailFor = screen.detailFor;
+    if (detailFor === undefined) return undefined;
+    for (const feature of appFeatures) {
+      // Access-check is part of the find predicate, not a filter applied
+      // after the first match — two entityEdit screens for the same entity
+      // where the first is role-gated must not hide an accessible second one.
+      const match = feature.screens.find(
+        (s): s is EntityEditScreenDefinition =>
+          s.type === "entityEdit" &&
+          s.entity === detailFor &&
+          screenAccessAllows(s.access, userRoles),
+      );
+      if (match !== undefined) return match;
+    }
+    return undefined;
+  }, [appFeatures, screen.detailFor, userRoles]);
+  const defaultEditAction = useMemo((): RenderEditAction | undefined => {
+    if (editScreen === undefined) return undefined;
+    // editScreen.id is registry-qualified ("feature:screen:contact-edit");
+    // nav.navigate expects the short form (see useNavigateToCreateFor above).
+    const targetScreenId = lastSegment(editScreen.id);
+    return {
+      id: "edit",
+      label: effectiveTranslate("kumiko.actions.edit"),
+      onPress: () =>
+        nav.navigate({ screenId: targetScreenId, ...(entityId !== undefined && { entityId }) }),
+    };
+  }, [editScreen, effectiveTranslate, nav, entityId]);
+
+  const headerActions = useMemo((): readonly RenderEditAction[] | undefined => {
+    const record = detailQuery.data ?? {};
+    const declaredHasEdit = screen.actions?.some((a) => a.id === "edit") === true;
+    const out: RenderEditAction[] = [];
+    if (defaultEditAction !== undefined && !declaredHasEdit) {
+      out.push(defaultEditAction);
+    }
+    for (const action of screen.actions ?? []) {
+      if (action.visible !== undefined && !evalFieldCondition(action.visible, record)) {
+        continue;
+      }
+      if (action.kind === "navigate") {
+        // Default entityId for an entityEdit target of the SAME entity
+        // (screen.detailFor plays entity's role here, like screen.entity
+        // does for entityList's runNavigate) — without this fallback the
+        // target opens an empty create-form instead of the shown record,
+        // silently. Searched cross-feature, consistent with editScreen above.
+        const explicit =
+          action.entityId !== undefined ? String(record[action.entityId] ?? "") : undefined;
+        const targetIsEntityEditSameEntity =
+          screen.detailFor !== undefined &&
+          appFeatures.some((feature) =>
+            feature.screens.some(
+              (s) =>
+                s.type === "entityEdit" &&
+                s.entity === screen.detailFor &&
+                lastSegment(s.id) === action.screen,
+            ),
+          );
+        const fallback = targetIsEntityEditSameEntity ? String(record["id"] ?? "") : undefined;
+        const navEntityId = explicit ?? fallback;
+        const targetScreen = action.screen;
+        out.push({
+          id: action.id,
+          label: effectiveTranslate(action.label),
+          ...(action.style !== undefined && { style: action.style }),
+          onPress: () => {
+            nav.navigate({
+              screenId: targetScreen,
+              ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
+            });
+            const params =
+              action.params !== undefined ? evalRowExtractor(action.params, record) : undefined;
+            if (params !== undefined) {
+              const stringified: Record<string, string | null> = {};
+              for (const [k, v] of Object.entries(params)) {
+                stringified[k] = v === null || v === undefined ? null : String(v);
+              }
+              nav.setSearchParams(stringified);
+            }
+          },
+        });
+        continue;
+      }
+      // writeHandler — same dispatch/refetch/failure-surfacing pattern as
+      // ProjectionListBody's rowActions/toolbarActions above.
+      if (dispatcher === undefined) continue;
+      const writeAction = action;
+      out.push({
+        id: writeAction.id,
+        label: effectiveTranslate(writeAction.label),
+        ...(writeAction.style !== undefined && { style: writeAction.style }),
+        ...(writeAction.confirm !== undefined && {
+          confirm: effectiveTranslate(writeAction.confirm),
+        }),
+        ...(writeAction.confirmLabel !== undefined && {
+          confirmLabel: effectiveTranslate(writeAction.confirmLabel),
+        }),
+        onPress: async () => {
+          const payload =
+            writeAction.payload !== undefined
+              ? evalRowExtractor(writeAction.payload, record)
+              : { id: record["id"] };
+          const result = await dispatcher.write(writeAction.handler, payload);
+          if (!result.isSuccess) {
+            throw new WriteFailedError(
+              result.error,
+              dispatcherErrorText(result.error, effectiveTranslate),
+            );
+          }
+          await detailQuery.refetch();
+        },
+      });
+    }
+    return out.length > 0 ? out : undefined;
+  }, [
+    screen.actions,
+    screen.detailFor,
+    appFeatures,
+    defaultEditAction,
+    effectiveTranslate,
+    nav,
+    dispatcher,
+    detailQuery.data,
+    detailQuery.refetch,
+  ]);
+
   if (entityId === undefined) {
     return (
       <Banner padded variant="error" testId="kumiko-screen-projection-detail-missing-id">
@@ -1600,6 +1816,7 @@ function ProjectionDetailBody({
       entityId={entityId}
       customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
       onCancel={screen.listScreenId !== undefined ? navigateToList : undefined}
+      {...(headerActions !== undefined && { actions: headerActions })}
       {...(translate !== undefined && { translate })}
     />
   );

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

@@ -24,14 +24,19 @@ import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
 
 const PROJECTION_PSEUDO_ENTITY = "__projection__";
 
-/** Minimale EntityDefinition aus den Column-Feldern: jedes Feld ein Text-Feld,
- *  nicht sortierbar (eine Projection-Query hat keinen garantierten Server-Sort).
- *  computeListViewModel liest nur `fields[<col>].type` → Text reicht; die
- *  Präsentation kommt aus dem Column-Renderer + explizitem Label. */
-export function synthesizeProjectionEntity(columns: readonly ListColumnSpec[]): EntityDefinition {
-  const fields: Record<string, { type: "text"; sortable: false }> = {};
+/** Minimal EntityDefinition from the column list: every field is a text
+ *  field. `sortable` applies uniformly to all columns — buildAppSchema
+ *  derives it from the query's Zod schema (`screen.sortable`, fw#2165); the
+ *  query itself has no per-field server-sort guarantee.
+ *  computeListViewModel only reads `fields[<col>].type` — text is enough,
+ *  presentation comes from the column renderer + explicit label. */
+export function synthesizeProjectionEntity(
+  columns: readonly ListColumnSpec[],
+  sortable: boolean,
+): EntityDefinition {
+  const fields: Record<string, { type: "text"; sortable: boolean }> = {};
   for (const col of columns) {
-    fields[normalizeListColumn(col).field] = { type: "text", sortable: false };
+    fields[normalizeListColumn(col).field] = { type: "text", sortable };
   }
   return { fields } as unknown as EntityDefinition;
 }

package/src/components/render-edit.tsx

@@ -136,6 +136,12 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  platform-neutrale Package darf kein `navigator`/`window` anfassen,
    *  siehe guard-renderer-boundaries). undefined = kein Button. */
   readonly onCopyLink?: () => Promise<void> | void;
+  /** Header action buttons, rendered before the built-in copy-link/
+   *  delete/cancel/save controls. Each callback is already fully
+   *  bound (screen-type/nav/dispatcher resolution happens in the caller,
+   *  same split as `onCopyLink`) — RenderEdit only wires the button, its
+   *  busy state and its confirm dialog. */
+  readonly actions?: readonly RenderEditAction[];
   /** i18n-key für den Submit-Button. Default: "kumiko.actions.save".
    *  Action-Forms (Tier 2.7d) übergeben hier ihren screen.submitLabel,
    *  damit "Speichern" durch domain-spezifischere Strings ersetzt
@@ -205,6 +211,15 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly hideActions?: boolean;
 };
 
+export type RenderEditAction = {
+  readonly id: string;
+  readonly label: string;
+  readonly onPress: () => void | Promise<void>;
+  readonly style?: "primary" | "secondary" | "danger";
+  readonly confirm?: string;
+  readonly confirmLabel?: string;
+};
+
 export type RenderEditChangeState<TValues extends FormValues> = {
   readonly values: TValues;
   readonly changes: Partial<TValues>;
@@ -314,6 +329,72 @@ function ExtensionSectionMount({
   );
 }
 
+// One header action + its own busy/confirm state — same pattern as
+// render-list.tsx's ToolbarActionView (each RenderEditAction is
+// independently bound by the caller, there is no shared trigger pipeline
+// to hook into like the built-in onDelete/onSubmit paths have).
+function RenderEditActionButton({
+  action,
+  Button,
+  Dialog,
+  onError,
+}: {
+  readonly action: RenderEditAction;
+  readonly Button: ReturnType<typeof usePrimitives>["Button"];
+  readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+  readonly onError: (text: string | null) => void;
+}): ReactNode {
+  const [busy, setBusy] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+
+  const trigger = async (): Promise<void> => {
+    setBusy(true);
+    onError(null);
+    try {
+      await action.onPress();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const variant = action.style ?? "secondary";
+  // Same rule as RowActionWriteHandler: "danger" forces a confirm even
+  // without an explicit confirm key.
+  const needsConfirm = action.confirm !== undefined || action.style === "danger";
+
+  return (
+    <>
+      <Button
+        type="button"
+        variant={variant}
+        loading={busy}
+        onClick={() => {
+          if (needsConfirm) {
+            setConfirmOpen(true);
+          } else {
+            void trigger();
+          }
+        }}
+        testId={`render-edit-action-${action.id}`}
+      >
+        {action.label}
+      </Button>
+      <Dialog
+        open={confirmOpen}
+        onOpenChange={setConfirmOpen}
+        title={action.label}
+        {...(action.confirm !== undefined && { description: action.confirm })}
+        confirmLabel={action.confirmLabel ?? action.label}
+        {...(action.style === "danger" && { variant: "danger" as const })}
+        onConfirm={trigger}
+        testId={`render-edit-action-${action.id}-dialog`}
+      />
+    </>
+  );
+}
+
 export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   props: RenderEditProps<TValues, TCtx>,
 ): ReactNode {
@@ -333,6 +414,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     onCancel,
     onReload,
     onCopyLink,
+    actions,
     submitLabel,
     labelAppendix,
     fieldAppendix,
@@ -362,6 +444,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const [linkCopied, setLinkCopied] = useState(false);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [formError, setFormError] = useState<DispatcherError | null>(null);
+  // One state for all header actions (actions?), not per-button — only one
+  // action can be in flight at a time, and this keeps the error surfaced in
+  // the shared formError-adjacent banner region instead of inside the
+  // button row (fw#2166 review: a full-width Banner there breaks the
+  // flex justify-end action bar).
+  const [actionError, setActionError] = useState<string | null>(null);
   const [rawStep, setRawStep] = useState(0);
   // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
   // on mount so a same-tab reload finds the right one of several parallel
@@ -985,6 +1073,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // gegen Fehlklicks. Save bleibt rechts (primary affordance).
   const formActions = (
     <>
+      {actions?.map((action) => (
+        <RenderEditActionButton
+          key={action.id}
+          action={action}
+          Button={Button}
+          Dialog={Dialog}
+          onError={setActionError}
+        />
+      ))}
       {onCopyLink !== undefined && (
         <Button
           type="button"
@@ -1282,6 +1379,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             <Text testId="render-edit-extension-error-key">{translate(extensionErrorKey)}</Text>
           </Banner>
         )}
+        {actionError !== null && (
+          <Banner variant="error" testId="render-edit-action-error">
+            {actionError}
+          </Banner>
+        )}
         {onDelete !== undefined && (
           <Dialog
             open={confirmDeleteOpen}

package/src/index.ts

@@ -78,6 +78,7 @@ export type { VariableChipsProps } from "./app/variable-chips";
 export { VariableChips } from "./app/variable-chips";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error";
 export type {
+  RenderEditAction,
   RenderEditChangeState,
   RenderEditControls,
   RenderEditProps,