@cosmicdrift/kumiko-renderer 0.201.0 → 0.203.0

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";
@@ -49,6 +50,7 @@ import {
 } from "./projection-detail-shim";
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim";
 import { lastSegment, toKebab } from "./qn";
+import { qualifyScreenId } from "./qualify-screen-id";
 import { screenAccessAllows } from "./screen-access";
 import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
 
@@ -100,19 +102,10 @@ export type KumikoScreenProps = {
   readonly onCopyLink?: () => Promise<void> | void;
 };
 
-// Build the qualified name the registry would stamp on screen ingest:
-// <feature>:screen:<short-id>. Matches the rule in
-// packages/framework/src/engine/qualified-name.ts so client lookups
-// line up with server-side registry state.
-export function qualifyScreenId(featureName: string, screenId: string): string {
-  return `${featureName}:screen:${screenId}`;
-}
+export { qualifyScreenId };
 
-/** Symmetrisch zu qualifyScreenId für Nav-QNs. NavDefinition-IDs in der
- *  Registry haben die Form `<feature>:nav:<short-id>`; Code der QNs
- *  baut (z.B. WorkspaceShell-Resolver) sollte das hier durchreichen statt
- *  String-Concat damit ein zukünftiger QN-Schema-Wechsel an einer Stelle
- *  greift. */
+/** Mirrors qualifyScreenId for nav QNs (registry form `<feature>:nav:<short-id>`).
+ *  Callers building QNs (e.g. the WorkspaceShell resolver) should use this instead of string-concat, so a QN-schema change only touches one place. */
 export function qualifyNavId(featureName: string, navId: string): string {
   return `${featureName}:nav:${navId}`;
 }
@@ -831,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,
@@ -943,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
@@ -963,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,
@@ -1345,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,
@@ -1366,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) => {
@@ -1515,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 })}
@@ -1548,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 {
@@ -1569,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">
@@ -1608,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/nav.tsx

@@ -1,4 +1,6 @@
 import { createContext, type ReactNode, useContext } from "react";
+import type { FeatureSchema } from "./feature-schema";
+import { qualifyScreenId } from "./qualify-screen-id";
 
 // Navigation-Contract, plattform-neutral. Types + Context + Hook leben
 // hier; die konkrete Implementation (window.history im Web,
@@ -20,7 +22,7 @@ export type NavRoute = {
   readonly entityId?: string;
 };
 
-export type NavTarget = {
+export type ScreenTarget = {
   // Optional in workspace-aware navigate calls. Omit for cross-workspace
   // navigation (current workspace stays); set to switch workspaces in the
   // same call as picking a screen — e.g. WorkspaceSwitcher does this.
@@ -29,6 +31,23 @@ export type NavTarget = {
   readonly entityId?: string;
 };
 
+// Object-based nav target — callers name WHAT they want to see (an entity's
+// row) instead of WHICH screen shows it. resolveTarget() below turns this
+// into a ScreenTarget by looking up the screen with matching `detailFor`.
+// No edit-form resolution here: an entity can have several entityEdit
+// screens (e.g. solon's "property" has three), so "the" edit screen isn't
+// well-defined — callers that want a form still name its screenId directly.
+export type ObjectTarget = {
+  readonly workspaceId?: string;
+  readonly entity: string;
+  readonly id: string;
+};
+
+// No `kind` tag: `"screenId" in target` narrows cleanly, and a tag would
+// force every existing NavTarget literal (every navigate/hrefFor call in
+// every app) to add one for an additive ticket. See resolveTarget().
+export type NavTarget = ScreenTarget | ObjectTarget;
+
 export type NavApi = {
   /** Current route — `undefined` when the URL is at the root / there's
    *  no route selected. Caller's initial fallback kicks in then. */
@@ -89,7 +108,7 @@ export function parsePath(pathname: string, hasWorkspaces?: boolean): NavRoute |
   return { screenId, ...(entityId !== undefined && { entityId }) };
 }
 
-export function formatPath(target: NavTarget): string {
+export function formatPath(target: ScreenTarget): string {
   // Workspace-Mode: prefix the workspace short id. Order matters —
   // workspace before screen mirrors parsePath's segment order.
   const segments: string[] = [];
@@ -99,6 +118,28 @@ export function formatPath(target: NavTarget): string {
   return `/${segments.join("/")}`;
 }
 
+// Resolves a NavTarget to the ScreenTarget form navigate/replace/hrefFor
+// operate on. Pure — no context, no I/O — so callers can use it outside
+// React too (see resolve-at-NavApi-build alternative in renderer-web).
+export function resolveTarget(features: readonly FeatureSchema[], target: NavTarget): ScreenTarget {
+  if ("screenId" in target) return target;
+
+  for (const feature of features) {
+    for (const screen of feature.screens) {
+      if (screen.detailFor !== target.entity) continue;
+      return {
+        ...(target.workspaceId !== undefined && { workspaceId: target.workspaceId }),
+        screenId: qualifyScreenId(feature.featureName, screen.id),
+        entityId: target.id,
+      };
+    }
+  }
+
+  throw new Error(
+    `resolveTarget: no detail screen for entity "${target.entity}". Add detailFor: "${target.entity}" to the screen that shows it.`,
+  );
+}
+
 // Context + Hook. Default ist `undefined` damit fehlender Provider
 // laut kracht statt ein silent-no-op NavApi mit toten navigate()
 // Aufrufen anzubieten.