@cosmicdrift/kumiko-renderer-web 0.270.0 → 0.273.0

package/package.json

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

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

@@ -948,7 +948,8 @@ describe("KumikoScreen", () => {
     await waitFor(() => expect(navigateCalls.length).toBe(1));
     expect(navigateCalls[0]).toEqual({ screenId: "task-edit" });
     // params werden zu Strings serialisiert (URL-Layer kennt nur Strings).
-    expect(searchParamUpdates).toEqual([{ taskId: "r1" }]);
+    // returnTo: "task-list" — this KumikoScreen has no outer host, so it becomes its own.
+    expect(searchParamUpdates).toEqual([{ taskId: "r1", returnTo: "task-list" }]);
     // Reihenfolge-Pin: erst navigate, dann setSearchParams.
     expect(calls.map((c) => c.kind)).toEqual(["navigate", "setSearchParams"]);
   });
@@ -1072,7 +1073,9 @@ describe("KumikoScreen", () => {
     await user.click(screen.getByTestId("row-r1-action-edit"));
     await waitFor(() => expect(navigateCalls.length).toBe(1));
     expect(navigateCalls[0]).toEqual({ screenId: "task-edit", entityId: "r1" });
-    expect(searchParamUpdates).toEqual([]);
+    // No declared params, but returnTo still attaches — the id itself never
+    // leaks into search params (that's the point above).
+    expect(searchParamUpdates).toEqual([{ returnTo: "task-list" }]);
   });
 
   // JSON-Schema-Fall (window.__KUMIKO_SCHEMA__): Declarative entityId: "id"
@@ -1195,7 +1198,7 @@ describe("KumikoScreen", () => {
     expect(navigateCalls[0]).toEqual({ screenId: "task-approve" });
   });
 
-  test("entityList rowActions kind=navigate ohne params: setSearchParams wird NICHT gerufen", async () => {
+  test("entityList rowActions kind=navigate ohne eigene params: setSearchParams trägt nur returnTo", async () => {
     const navigateCalls: { screenId: string }[] = [];
     const searchParamUpdates: Record<string, string | null>[] = [];
     const memoryNav = {
@@ -1241,7 +1244,8 @@ describe("KumikoScreen", () => {
 
     await user.click(screen.getByTestId("row-r1-action-view"));
     await waitFor(() => expect(navigateCalls.length).toBe(1));
-    expect(searchParamUpdates).toEqual([]);
+    // No declared params, but returnTo still attaches.
+    expect(searchParamUpdates).toEqual([{ returnTo: "task-list" }]);
   });
 
   // toolbarActions: Schema-Form (kind: navigate | writeHandler) →

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

@@ -401,6 +401,101 @@ describe("KumikoScreen / projectionDetail — record header + metrics band", ()
   });
 });
 
+describe("KumikoScreen / projectionDetail — header actions sit in the title row", () => {
+  const headerActionsScreen: ProjectionDetailScreenDefinition = {
+    ...baseScreen,
+    header: { title: "tenantName", subtitle: "address", status: "state" },
+    metrics: ["balance"],
+    actions: [
+      {
+        kind: "navigate",
+        id: "open-tenant",
+        label: "actions.openTenant",
+        entity: "tenant",
+        entityId: "tenantId",
+      },
+    ],
+  };
+
+  function nearestCommonAncestor(a: Element, b: Element): Element {
+    const ancestorsOfA = new Set<Element>();
+    for (let el: Element | null = a; el !== null; el = el.parentElement) ancestorsOfA.add(el);
+    for (let el: Element | null = b; el !== null; el = el.parentElement) {
+      if (ancestorsOfA.has(el)) return el;
+    }
+    throw new Error("title and action share no common ancestor");
+  }
+
+  test("title and action buttons share a header container that excludes the metrics band", async () => {
+    const dispatcher = dispatcherReturning({ ...rowData, tenantId: "tenant-9" });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(headerActionsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const title = screen.getByTestId("kumiko-screen-projection-detail-title");
+    const actionButton = screen.getByTestId("render-edit-action-open-tenant");
+    const metricsBand = screen.getByTestId("kumiko-screen-projection-detail-metrics");
+
+    const headerContainer = nearestCommonAncestor(title, actionButton);
+    expect(headerContainer.contains(metricsBand)).toBe(false);
+  });
+
+  test("the metrics band follows the subtitle and the header row in DOM order", async () => {
+    const dispatcher = dispatcherReturning({ ...rowData, tenantId: "tenant-9" });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(headerActionsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const title = screen.getByTestId("kumiko-screen-projection-detail-title");
+    const actionButton = screen.getByTestId("render-edit-action-open-tenant");
+    const subtitle = screen.getByTestId("kumiko-screen-projection-detail-subtitle");
+    const metricsBand = screen.getByTestId("kumiko-screen-projection-detail-metrics");
+    const headerContainer = nearestCommonAncestor(title, actionButton);
+
+    expect(
+      (subtitle.compareDocumentPosition(metricsBand) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0,
+    ).toBe(true);
+    expect(
+      (headerContainer.compareDocumentPosition(metricsBand) & Node.DOCUMENT_POSITION_FOLLOWING) !==
+        0,
+    ).toBe(true);
+  });
+
+  test("the title + status-badge container is vertically centered", async () => {
+    const dispatcher = dispatcherReturning({ ...rowData, tenantId: "tenant-9" });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(headerActionsScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    const title = screen.getByTestId("kumiko-screen-projection-detail-title");
+    expect(title.parentElement?.className).toContain("items-center");
+  });
+});
+
 describe("KumikoScreen / projectionDetail — metric tiles render through the Metric primitive", () => {
   const metricsScreen: ProjectionDetailScreenDefinition = {
     ...baseScreen,

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

@@ -633,7 +633,7 @@ describe("KumikoScreen / projectionDetail extension section (solon#264)", () =>
     expect(screen.queryByTestId("field-userId")).toBeNull();
   });
 
-  test("layout.mode: 'tabs' with a header — exactly one card renders, the head (bedienkonzept A1)", async () => {
+  test("layout.mode: 'tabs' with a header — the head card plus one card for the active tab's fields", async () => {
     const tabsHeaderScreen: ProjectionDetailScreenDefinition = {
       ...detailScreen,
       header: { title: "userId" },
@@ -679,10 +679,9 @@ describe("KumikoScreen / projectionDetail extension section (solon#264)", () =>
     );
 
     await waitFor(() => screen.getByTestId("render-edit-form"));
-    // Bedienkonzept A1: on a tabbed Akte there is exactly one card, the head
-    // — tab content sits on the page background. Checked via the card's
-    // structural marker, not a Tailwind class string.
-    expect(container.querySelectorAll('[data-slot="card"]')).toHaveLength(1);
+    // Head card plus one titled card for the fields tab — checked via the
+    // card's structural marker, not a Tailwind class string.
+    expect(container.querySelectorAll('[data-slot="card"]')).toHaveLength(2);
   });
 
   test("layout.mode: 'tabs' with countField — tab label carries the record's count, sections without it stay unchanged", async () => {

package/src/__tests__/render-edit.test.tsx

@@ -204,10 +204,9 @@ describe("RenderEdit", () => {
 
   // Fall 2: tabs layout sets hideSectionTitles (kumiko-screen.tsx's
   // ProjectionDetailBody, the only real caller) to blank out each section's
-  // OWN title — the active tab already names it. That gate used to also
-  // swallow the screen-level subtitle (screen.description), which has
-  // nothing to do with section titles and must survive tabs mode.
-  test("tabs layout (hideSectionTitles) keeps the section title hidden but still shows the screen's own subtitle", () => {
+  // OWN title — the active tab already names it. The head card also carries
+  // screen.description as its subtitle, so it must not render again here.
+  test("tabs layout (hideSectionTitles) keeps the section title hidden and drops the screen's own subtitle", () => {
     const entity = {
       fields: { email: { type: "text", required: true } },
     } as unknown as EntityDefinition;
@@ -236,9 +235,93 @@ describe("RenderEdit", () => {
 
     expect(screen.queryByTestId("render-edit-form-title")).toBeNull();
     expect(screen.queryByTestId("section-Contact-title")).toBeNull();
-    expect(screen.getByTestId("render-edit-form-subtitle").textContent).toBe(
-      "Everything about this order in one place.",
+    expect(screen.queryByTestId("render-edit-form-subtitle")).toBeNull();
+  });
+
+  // S2: a fields-kind section's `groups` splits it into its own titled cards
+  // (tabs mode only — the branch that renders `groups` at all lives behind
+  // `hideSectionTitles`) instead of one flat grid.
+  test("a section with two groups renders two titled cards in tabs mode, each with its own fields", () => {
+    const entity = {
+      fields: {
+        email: { type: "text", required: true },
+        plan: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+    const screenDef: EntityEditScreenDefinition = {
+      id: "orders:screen:order-detail",
+      type: "entityEdit",
+      entity: "order",
+      layout: {
+        mode: "tabs",
+        sections: [
+          {
+            id: "overview",
+            title: "Overview",
+            fields: [],
+            groups: [
+              { title: "Contact", fields: [{ field: "email" }] },
+              { title: "Billing", fields: [{ field: "plan" }] },
+            ],
+          },
+        ],
+      },
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <RenderEdit
+          screen={screenDef}
+          entity={entity}
+          featureName="orders"
+          initial={{ email: "", plan: "" } as never}
+          writeCommand="order:create"
+          hideSectionTitles
+        />
+      </DispatcherProvider>,
     );
+
+    const contactCard = screen.getByTestId("section-Overview-group-0");
+    const billingCard = screen.getByTestId("section-Overview-group-1");
+    expect(contactCard.querySelector("h3")?.textContent).toBe("Contact");
+    expect(billingCard.querySelector("h3")?.textContent).toBe("Billing");
+    expect(within(contactCard).getByTestId("field-email")).toBeTruthy();
+    expect(within(billingCard).getByTestId("field-plan")).toBeTruthy();
+    expect(within(contactCard).queryByTestId("field-plan")).toBeNull();
+
+    // Default columns per group is 2 (--grid-cols CSS var), unless overridden.
+    const contactGrid = contactCard.querySelector(".grid") as HTMLElement | null;
+    expect(contactGrid?.style.getPropertyValue("--grid-cols")).toBe("repeat(2, minmax(0, 1fr))");
+  });
+
+  test("a tabs-mode section without groups renders a single card", () => {
+    const entity = {
+      fields: { email: { type: "text", required: true } },
+    } as unknown as EntityDefinition;
+    const screenDef: EntityEditScreenDefinition = {
+      id: "orders:screen:order-detail",
+      type: "entityEdit",
+      entity: "order",
+      layout: {
+        mode: "tabs",
+        sections: [{ id: "overview", title: "Overview", fields: [{ field: "email" }] }],
+      },
+    };
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <RenderEdit
+          screen={screenDef}
+          entity={entity}
+          featureName="orders"
+          initial={{ email: "" } as never}
+          writeCommand="order:create"
+          hideSectionTitles
+        />
+      </DispatcherProvider>,
+    );
+
+    expect(screen.getByTestId("section-Overview")).toBeTruthy();
+    expect(screen.queryByTestId("section-Overview-group-0")).toBeNull();
+    expect(within(screen.getByTestId("section-Overview")).getByTestId("field-email")).toBeTruthy();
   });
 
   // End-to-end-Routing: ein `type:"locatedTimestamp"`-Entity-Feld muss durch

package/src/__tests__/return-to-singleton.test.tsx

@@ -0,0 +1,144 @@
+// Split out of return-to.test.tsx: the singleton create->update path fires
+// fireEvent.change immediately followed by a click right after an async load
+// settles — the #457 shared single-process happy-dom pattern. Isolated the
+// same way as kumiko-screen-singleton-entity-edit.test.tsx (bunfig.ci-dom.toml,
+// pathIgnorePatterns in bunfig.dom.toml).
+import { describe, expect, mock, test } from "bun:test";
+import type {
+  DashboardScreenDefinition,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+  FeatureSchema,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import {
+  AppFeaturesProvider,
+  DashboardBodyProvider,
+  DispatcherProvider,
+  KumikoScreen,
+  NavProvider,
+  qualifyScreenId,
+  useNav,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { WebDashboardBody } from "../app/dashboard-body";
+import { useBrowserNavApi } from "../app/nav";
+import { createMockDispatcher, fireEvent, render, screen, waitFor } from "./test-utils";
+
+const settingEntity: EntityDefinition = {
+  fields: { title: { type: "text", required: false, searchable: false, sortable: false } },
+};
+
+const singletonScreen: EntityEditScreenDefinition = {
+  id: "settings-edit",
+  type: "entityEdit",
+  entity: "setting",
+  singleton: true,
+  layout: { sections: [{ fields: ["title"] }] },
+};
+
+const dashboardScreen: DashboardScreenDefinition = {
+  id: "home",
+  type: "dashboard",
+  panels: [{ kind: "screen", id: "singleton", screen: "settings-edit" }],
+};
+
+const schema: FeatureSchema = {
+  featureName: "settingsfeat",
+  entities: { setting: settingEntity },
+  screens: [dashboardScreen, singletonScreen],
+};
+
+function RouterScreen({ appSchema }: { readonly appSchema: FeatureSchema }): ReactNode {
+  const nav = useNav();
+  if (nav.route === undefined) return null;
+  const qn = qualifyScreenId(appSchema.featureName, nav.route.screenId);
+  return (
+    <KumikoScreen
+      schema={appSchema}
+      qn={qn}
+      {...(nav.route.entityId !== undefined && { entityId: nav.route.entityId })}
+    />
+  );
+}
+
+function BrowserNavRoot({ appSchema }: { readonly appSchema: FeatureSchema }): ReactNode {
+  const nav = useBrowserNavApi({ hasWorkspaces: false });
+  return (
+    <NavProvider value={nav}>
+      <RouterScreen appSchema={appSchema} />
+    </NavProvider>
+  );
+}
+
+function App({
+  appSchema,
+  dispatcher,
+}: {
+  readonly appSchema: FeatureSchema;
+  readonly dispatcher: Dispatcher;
+}): ReactNode {
+  return (
+    <DispatcherProvider dispatcher={dispatcher}>
+      <AppFeaturesProvider features={[appSchema]}>
+        <DashboardBodyProvider value={WebDashboardBody}>
+          <BrowserNavRoot appSchema={appSchema} />
+        </DashboardBodyProvider>
+      </AppFeaturesProvider>
+    </DispatcherProvider>
+  );
+}
+
+describe("returnTo — singleton entityEdit ignores it", () => {
+  test("reached with ?returnTo=home, saving stays on the singleton screen", async () => {
+    let created = false;
+    const write = mock(async (type: string) => {
+      if (type === "settingsfeat:write:setting:create") {
+        created = true;
+        return { isSuccess: true, data: { id: "s1" } };
+      }
+      return { isSuccess: true, data: {} };
+    });
+    const query = mock(async (type: string) => {
+      if (type === "settingsfeat:query:setting:list") {
+        return created
+          ? { isSuccess: true, data: { rows: [{ id: "s1", title: "Saved title" }] } }
+          : { isSuccess: true, data: { rows: [], nextCursor: null } };
+      }
+      if (type === "settingsfeat:query:setting:detail") {
+        return {
+          isSuccess: true,
+          data: { id: "s1", version: 1, title: "Saved title" },
+        };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    });
+    const dispatcher = createMockDispatcher({
+      write: write as unknown as Dispatcher["write"],
+      query: query as unknown as Dispatcher["query"],
+    });
+
+    window.history.replaceState(null, "", "/settings-edit?returnTo=home");
+    render(<App appSchema={schema} dispatcher={dispatcher} />);
+
+    await waitFor(() => expect(screen.getByTestId("field-title")).toBeTruthy());
+    const titleInput = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+    fireEvent.change(titleInput, { target: { value: "Saved title" } });
+    await waitFor(() => {
+      const button = screen.getByTestId("render-edit-submit") as HTMLButtonElement;
+      expect(button.disabled).toBe(false);
+    });
+    fireEvent.click(screen.getByTestId("render-edit-submit"));
+
+    await waitFor(() => expect(write).toHaveBeenCalledTimes(1));
+    // The singleton wrapper flips to the update form of the newly created
+    // record instead of navigating anywhere — returnTo must not interfere.
+    await waitFor(() => {
+      const input = screen.getByTestId("field-title").querySelector("input") as HTMLInputElement;
+      expect(input.value).toBe("Saved title");
+    });
+    expect(window.location.pathname).toBe("/settings-edit");
+
+    window.history.replaceState(null, "", "/");
+  });
+});

package/src/__tests__/return-to.test.tsx

@@ -0,0 +1,551 @@
+// Exercises the real navigation stack end to end (real useBrowserNavApi),
+// asserting on window.location instead of a captured NavTarget.
+import { afterEach, describe, expect, test } from "bun:test";
+import type {
+  DashboardScreenDefinition,
+  EntityDefinition,
+  FeatureSchema,
+  ScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import {
+  AppFeaturesProvider,
+  DashboardBodyProvider,
+  DispatcherProvider,
+  KumikoScreen,
+  NavProvider,
+  qualifyScreenId,
+  UserRolesProvider,
+  useNav,
+} from "@cosmicdrift/kumiko-renderer";
+import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
+import { WebDashboardBody } from "../app/dashboard-body";
+import { useBrowserNavApi } from "../app/nav";
+import { createMockDispatcher, fireEvent, render, screen, waitFor } from "./test-utils";
+
+const tokenEntity: EntityDefinition = {
+  fields: { name: { type: "text", required: false, searchable: false, sortable: false } },
+};
+
+const dashboardScreen: DashboardScreenDefinition = {
+  id: "settings",
+  type: "dashboard",
+  panels: [
+    { kind: "screen", id: "list", screen: "token-list" },
+    { kind: "screen", id: "stats", screen: "token-stats" },
+  ],
+};
+
+const listScreen: ScreenDefinition = {
+  id: "token-list",
+  type: "entityList",
+  entity: "token",
+  columns: ["name"],
+  toolbarActions: [
+    { kind: "navigate", id: "create", label: "create", screen: "token-create" },
+    { kind: "navigate", id: "action", label: "action", screen: "token-action" },
+  ],
+  rowActions: [{ kind: "navigate", id: "open", label: "open", screen: "token-open" }],
+};
+
+const secretMintScreen: ScreenDefinition = {
+  id: "token-create",
+  type: "secretMint",
+  handler: "tokens:write:token-secret:mint",
+  fields: { label: { type: "text", required: false, searchable: false, sortable: false } },
+  layout: { sections: [{ fields: ["label"] }] },
+  reveal: { fields: [{ field: "secret", label: "secret" }] },
+  redirect: "token-list",
+  cancelTarget: "token-list",
+};
+
+const tokenActionScreen: ScreenDefinition = {
+  id: "token-action",
+  type: "actionForm",
+  handler: "tokens:write:token:action",
+  fields: {},
+  layout: { sections: [] },
+  redirect: "token-list",
+};
+
+const tokenOpenScreen: ScreenDefinition = {
+  id: "token-open",
+  type: "actionForm",
+  handler: "tokens:write:token:open",
+  fields: {},
+  layout: { sections: [] },
+  redirect: { screen: "token-edit", idFrom: "id" },
+};
+
+const tokenEditScreen: ScreenDefinition = {
+  id: "token-edit",
+  type: "entityEdit",
+  entity: "token",
+  layout: { sections: [{ fields: ["name"] }] },
+};
+
+// A second, distinct record screen for the same entity/id — lets returnTo
+// name a record screen that is NOT the one being deleted (delete-guard test).
+// Also carries a relatedList section for the host-threading test (18/19
+// cover entityList/projectionList; this one covers relatedList).
+const tokenDetailScreen: ScreenDefinition = {
+  id: "token-detail",
+  type: "projectionDetail",
+  query: "tokens:query:token:detail-view",
+  layout: {
+    sections: [
+      { fields: ["name"] },
+      {
+        kind: "relatedList",
+        title: "Related",
+        query: "tokens:query:token:related",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "navigate",
+            id: "related-action",
+            label: "related-action",
+            screen: "token-action",
+          },
+        ],
+      },
+    ],
+  },
+};
+
+const tokenStatsScreen: ScreenDefinition = {
+  id: "token-stats",
+  type: "projectionList",
+  query: "tokens:query:token:stats",
+  columns: [{ field: "name", label: "name" }],
+  toolbarActions: [
+    { kind: "navigate", id: "stats-action", label: "stats-action", screen: "token-action" },
+  ],
+  rowActions: [
+    { kind: "navigate", id: "stats-row-action", label: "stats-row-action", screen: "token-action" },
+  ],
+};
+
+const adminOnlyScreen: ScreenDefinition = {
+  id: "admin-only",
+  type: "custom",
+  renderer: { react: "stub" },
+  access: { roles: ["Admin"] },
+};
+
+const schema: FeatureSchema = {
+  featureName: "tokens",
+  entities: { token: tokenEntity },
+  screens: [
+    dashboardScreen,
+    listScreen,
+    secretMintScreen,
+    tokenActionScreen,
+    tokenOpenScreen,
+    tokenEditScreen,
+    tokenDetailScreen,
+    tokenStatsScreen,
+    adminOnlyScreen,
+  ],
+};
+
+function makeDispatcher(): Dispatcher {
+  return createMockDispatcher({
+    query: (async (type: string) => {
+      if (type === "tokens:query:token:list") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: "tok-1", name: "Token 1" }], nextCursor: null, total: 1 },
+        };
+      }
+      // Distinct row data from the entityList above — both panels render on
+      // the same dashboard, and duplicate text/ids would break `getByText`/
+      // `getByTestId` uniqueness in the other tests.
+      if (type === "tokens:query:token:stats") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: "stat-1", name: "Stat A" }], nextCursor: null, total: 1 },
+        };
+      }
+      if (type === "tokens:query:token:detail") {
+        return { isSuccess: true, data: { id: "tok-1", version: 1, name: "Token 1" } };
+      }
+      if (type === "tokens:query:token:related") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: "rel-1", name: "Related A" }], nextCursor: null },
+        };
+      }
+      return { isSuccess: true, data: {} };
+    }) as unknown as Dispatcher["query"],
+    write: (async (command: string) => {
+      if (command === "tokens:write:token-secret:mint") {
+        return { isSuccess: true, data: { secret: "shh-secret" } };
+      }
+      if (command === "tokens:write:token:open") {
+        return { isSuccess: true, data: { id: "tok-1" } };
+      }
+      if (command === "tokens:write:token:create") {
+        return { isSuccess: true, data: { id: "new-tok" } };
+      }
+      return { isSuccess: true, data: {} };
+    }) as unknown as Dispatcher["write"],
+  });
+}
+
+function RouterScreen({ appSchema }: { readonly appSchema: FeatureSchema }): ReactNode {
+  const nav = useNav();
+  if (nav.route === undefined) return null;
+  const qn = qualifyScreenId(appSchema.featureName, nav.route.screenId);
+  return (
+    <KumikoScreen
+      schema={appSchema}
+      qn={qn}
+      {...(nav.route.entityId !== undefined && { entityId: nav.route.entityId })}
+    />
+  );
+}
+
+function BrowserNavRoot({ appSchema }: { readonly appSchema: FeatureSchema }): ReactNode {
+  const nav = useBrowserNavApi({ hasWorkspaces: false });
+  return (
+    <NavProvider value={nav}>
+      <RouterScreen appSchema={appSchema} />
+    </NavProvider>
+  );
+}
+
+function App({
+  appSchema,
+  dispatcher,
+}: {
+  readonly appSchema: FeatureSchema;
+  readonly dispatcher: Dispatcher;
+}): ReactNode {
+  return (
+    <DispatcherProvider dispatcher={dispatcher}>
+      <AppFeaturesProvider features={[appSchema]}>
+        <UserRolesProvider roles={["User"]}>
+          <DashboardBodyProvider value={WebDashboardBody}>
+            <BrowserNavRoot appSchema={appSchema} />
+          </DashboardBodyProvider>
+        </UserRolesProvider>
+      </AppFeaturesProvider>
+    </DispatcherProvider>
+  );
+}
+
+function renderApp(): void {
+  render(<App appSchema={schema} dispatcher={makeDispatcher()} />);
+}
+
+async function waitForEnabled(testId: string): Promise<HTMLButtonElement> {
+  const btn = screen.getByTestId(testId) as HTMLButtonElement;
+  await waitFor(() => expect(btn.disabled).toBe(false));
+  return btn;
+}
+
+describe("returnTo", () => {
+  afterEach(() => {
+    window.history.replaceState(null, "", "/");
+  });
+
+  test("1. embedded list toolbar create sets returnTo=settings; cancel returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-toolbar-action-create"));
+
+    expect(window.location.pathname).toBe("/token-create");
+    expect(window.location.search).toBe("?returnTo=settings");
+
+    await user.click(screen.getByTestId("render-edit-cancel"));
+    expect(window.location.pathname).toBe("/settings");
+  });
+
+  test("2. embedded list toolbar create → fill + submit reveals the secret → confirm returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-toolbar-action-create"));
+    expect(window.location.pathname).toBe("/token-create");
+
+    const input = screen.getByTestId("field-label").querySelector("input") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "My token" } });
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("kumiko-screen-secret-mint-reveal")).toBeTruthy(),
+    );
+    await user.click(screen.getByTestId("kumiko-screen-secret-mint-confirm"));
+
+    expect(window.location.pathname).toBe("/settings");
+  });
+
+  test("3. embedded list toolbar action → submit returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-toolbar-action-action"));
+    expect(window.location.pathname).toBe("/token-action");
+    expect(window.location.search).toBe("?returnTo=settings");
+
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/settings"));
+  });
+
+  test("3b. embedded list toolbar action → cancel returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-toolbar-action-action"));
+    expect(window.location.pathname).toBe("/token-action");
+
+    await user.click(screen.getByTestId("render-edit-cancel"));
+    expect(window.location.pathname).toBe("/settings");
+  });
+
+  test("4. + New (default create) on embedded list → token-edit create → save returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-create"));
+
+    expect(window.location.pathname).toBe("/token-edit");
+    expect(window.location.search).toBe("?returnTo=settings");
+
+    const input = screen.getByTestId("field-name").querySelector("input") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "New Token" } });
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/settings"));
+  });
+
+  test("5. row action with a record-targeting redirect lands on token-edit/<id>, not settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("row-tok-1-action-open"));
+
+    expect(window.location.pathname).toBe("/token-open");
+    expect(window.location.search).toBe("?returnTo=settings");
+
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/token-edit/tok-1"));
+  });
+
+  test("6. direct navigation to token-create (no returnTo) → cancel falls back to cancelTarget", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-create");
+    renderApp();
+
+    const cancelBtn = await screen.findByTestId("render-edit-cancel");
+    await user.click(cancelBtn);
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test.each([
+    "unknown-screen",
+    "//evil.com",
+    "https://evil.com",
+    "tokens:screen:settings",
+    "admin-only",
+    "token-create",
+    "settings/x/y",
+  ])("7. manipulated returnTo=%s falls back to cancelTarget", async (value) => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", `/token-create?returnTo=${encodeURIComponent(value)}`);
+    renderApp();
+
+    const cancelBtn = await screen.findByTestId("render-edit-cancel");
+    await user.click(cancelBtn);
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test("8. non-embedded token-list toolbar create sets returnTo=token-list, cancel returns there", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-list");
+    renderApp();
+
+    await waitFor(() => expect(screen.getByText("Token 1")).toBeTruthy());
+    await user.click(screen.getByTestId("render-list-toolbar-action-create"));
+
+    expect(window.location.pathname).toBe("/token-create");
+    expect(window.location.search).toBe("?returnTo=token-list");
+
+    await user.click(screen.getByTestId("render-edit-cancel"));
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test("9. direct navigation to token-action (no returnTo) → submit falls back to its own redirect", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-action");
+    renderApp();
+
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/token-list"));
+  });
+
+  test("10. direct navigation to token-action (no returnTo) → cancel falls back to its own redirect", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-action");
+    renderApp();
+
+    const cancelBtn = await screen.findByTestId("render-edit-cancel");
+    await user.click(cancelBtn);
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test("11. direct navigation to token-create (no returnTo) → submit → reveal → confirm falls back to redirect", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-create");
+    renderApp();
+
+    const input = await screen.findByTestId("field-label");
+    fireEvent.change(input.querySelector("input") as HTMLInputElement, {
+      target: { value: "My token" },
+    });
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("kumiko-screen-secret-mint-reveal")).toBeTruthy(),
+    );
+    await user.click(screen.getByTestId("kumiko-screen-secret-mint-confirm"));
+
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test("12. direct navigation to token-edit create (no returnTo) → save falls back to the entity's list", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-edit");
+    renderApp();
+
+    const input = await screen.findByTestId("field-name");
+    fireEvent.change(input.querySelector("input") as HTMLInputElement, {
+      target: { value: "New Token" },
+    });
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/token-list"));
+  });
+
+  test("13. entityEdit update with returnTo=settings → save returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-edit/tok-1?returnTo=settings");
+    renderApp();
+
+    const input = await screen.findByTestId("field-name");
+    await waitFor(() =>
+      expect((input.querySelector("input") as HTMLInputElement).value).toBe("Token 1"),
+    );
+    fireEvent.change(input.querySelector("input") as HTMLInputElement, {
+      target: { value: "Renamed" },
+    });
+    const submitBtn = await waitForEnabled("render-edit-submit");
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(window.location.pathname).toBe("/settings"));
+  });
+
+  test("14. entityEdit update with returnTo=settings → cancel returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-edit/tok-1?returnTo=settings");
+    renderApp();
+
+    const cancelBtn = await screen.findByTestId("render-edit-cancel");
+    await user.click(cancelBtn);
+    expect(window.location.pathname).toBe("/settings");
+  });
+
+  test("15. entityEdit update with returnTo=settings → delete returns to settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-edit/tok-1?returnTo=settings");
+    renderApp();
+
+    await screen.findByTestId("field-name");
+    await user.click(screen.getByTestId("render-edit-delete"));
+    await user.click(screen.getByTestId("render-edit-delete-dialog-confirm"));
+
+    await waitFor(() => expect(window.location.pathname).toBe("/settings"));
+  });
+
+  test("16. delete-guard: returnTo pointing at the just-deleted record falls back to the list", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-edit/tok-1?returnTo=token-detail/tok-1");
+    renderApp();
+
+    await screen.findByTestId("field-name");
+    await user.click(screen.getByTestId("render-edit-delete"));
+    await user.click(screen.getByTestId("render-edit-delete-dialog-confirm"));
+
+    await waitFor(() => expect(window.location.pathname).toBe("/token-list"));
+  });
+
+  test("17. manipulated entityId in the real URL (returnTo=token-edit/%2e%2e) → cancel falls back to cancelTarget", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-create?returnTo=token-edit/%2e%2e");
+    renderApp();
+
+    const cancelBtn = await screen.findByTestId("render-edit-cancel");
+    await user.click(cancelBtn);
+    expect(window.location.pathname).toBe("/token-list");
+  });
+
+  test("18. projectionList embedded in the dashboard: toolbar navigate carries returnTo=settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await user.click(await screen.findByTestId("render-list-toolbar-action-stats-action"));
+
+    expect(window.location.pathname).toBe("/token-action");
+    expect(window.location.search).toBe("?returnTo=settings");
+  });
+
+  test("19. projectionList embedded in the dashboard: row action navigate carries returnTo=settings", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/settings");
+    renderApp();
+
+    await user.click(await screen.findByTestId("row-stat-1-action-stats-row-action"));
+
+    expect(window.location.pathname).toBe("/token-action");
+    expect(window.location.search).toBe("?returnTo=settings");
+  });
+
+  test("20. relatedList toolbar navigate (in a projectionDetail) sets returnTo=<detail>/<id> and its parentParam prefill", async () => {
+    const user = userEvent.setup();
+    window.history.replaceState(null, "", "/token-detail/tok-1");
+    renderApp();
+
+    await user.click(await screen.findByTestId("render-list-toolbar-action-related-action"));
+
+    expect(window.location.pathname).toBe("/token-action");
+    const params = new URLSearchParams(window.location.search);
+    expect(params.get("returnTo")).toBe("token-detail/tok-1");
+    expect(params.get("id")).toBe("tok-1");
+  });
+});

package/src/app/create-app.tsx

@@ -29,10 +29,12 @@ import {
   mergeTranslations,
   type NavApi,
   NavProvider,
+  navigateWithReturnTo,
   PrimitivesProvider,
   type PrimitivesRegistry,
   type QualifiedContentCollection,
   qualifyScreenId,
+  type ReturnHost,
   TokensProvider,
   type TranslationsByLocale,
   toAppSchema,
@@ -638,14 +640,23 @@ function RoutedScreen({
           (s) => s.type === "entityEdit" && s.entity === entityName,
         );
         if (editScreen) {
+          // No ReturnHostProvider out here — derive the host from this memo's own qn/entityId.
+          const host: ReturnHost = {
+            screenId: lastSegment(qn),
+            ...(entityId !== undefined && { entityId }),
+          };
           // editScreen.id is already short form; lastSegment is a no-op
           // safety net here, kept for symmetry with the other call sites.
-          nav.navigate({ screenId: lastSegment(editScreen.id), entityId: row.id });
+          navigateWithReturnTo(
+            nav,
+            { screenId: lastSegment(editScreen.id), entityId: row.id },
+            host,
+          );
           return;
         }
       }
     };
-  }, [app, activeScreen, onRowClick, nav]);
+  }, [app, activeScreen, onRowClick, nav, qn, entityId]);
 
   // Copy-link action (Issue #912) for entityEdit update screens. Builds
   // the absolute permalink URL from the current route + copies it —

package/src/layout/shell-breadcrumb.ts

@@ -1,4 +1,5 @@
 import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { resolveNavParentScreen } from "@cosmicdrift/kumiko-framework/ui-types";
 import { lastSegment } from "@cosmicdrift/kumiko-renderer";
 
 export type BreadcrumbCrumb = {
@@ -10,51 +11,13 @@ export function screenTitleKey(screenShortId: string): string {
   return `screen:${screenShortId}.title`;
 }
 
-// Every screen type carrying `listScreenId` declares it identically — reading
-// it here (instead of at each call site) keeps the switch the only place
-// that has to grow when a new screen type adopts the field.
-function explicitListScreenId(screen: ScreenDefinition): string | undefined {
-  switch (screen.type) {
-    case "custom":
-    case "projectionDetail":
-    case "entityEdit":
-    case "actionForm":
-    case "secretMint":
-      return screen.listScreenId;
-    default:
-      return undefined;
-  }
-}
-
-// Shared by the breadcrumb (this file) and NavTree's active-marker fallback
-// (nav-tree.tsx) — both need "which list screen does this detail belong to",
-// so this is the one place that answers it. An explicit `listScreenId` wins
-// over the heuristics below (rowAction target / same-entity entityList): a
-// screen author who declares it is opting out of the guess.
+// Delegates to resolveNavParentScreen, supplying the feature-qualified-id
+// normalization the client-side schema needs.
 function resolveParentScreen(
   screens: readonly ScreenDefinition[],
   detail: ScreenDefinition,
 ): ScreenDefinition | undefined {
-  const detailScreenId = lastSegment(detail.id);
-
-  const listFromExplicit = ((): ScreenDefinition | undefined => {
-    const explicitId = explicitListScreenId(detail);
-    return explicitId !== undefined
-      ? screens.find((s) => lastSegment(s.id) === explicitId)
-      : undefined;
-  })();
-
-  const listFromRowAction = screens.find((s) => {
-    if (s.type !== "entityList") return false;
-    return (s.rowActions ?? []).some((a) => a.kind === "navigate" && a.screen === detailScreenId);
-  });
-
-  const listFromEntity =
-    detail.type === "entityEdit"
-      ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
-      : undefined;
-
-  return listFromExplicit ?? listFromRowAction ?? listFromEntity;
+  return resolveNavParentScreen(screens, detail, (s) => lastSegment(s.id));
 }
 
 /** The short id of {screenId}'s parent list screen, resolved via the same

package/src/primitives/__tests__/textarea-submit-shortcut.test.tsx

@@ -1,4 +1,4 @@
-// kumiko-screen-akte-bedienkonzept: Ctrl/Cmd+Enter submits a textarea
+// Ctrl/Cmd+Enter submits a textarea
 // (InputProps.onSubmitShortcut) instead of inserting a newline. Plain Enter
 // keeps inserting a newline — asserted here via the keydown event's
 // defaultPrevented state, since fireEvent.keyDown does not itself simulate

package/src/primitives/index.tsx

@@ -2289,9 +2289,8 @@ function FormSections({
 }
 
 // Title/subtitle block shared by DefaultForm's card and chromeless layouts —
-// the caller-supplied subtitle (screen.description) is independent of
-// hideSectionTitles (which only blanks per-section titles, see RenderEdit)
-// and must keep rendering in tabs/chromeless mode, just without card chrome.
+// RenderEdit already withholds screen.description from `subtitle` in tabs
+// mode (chromeless), so whatever arrives here still renders, just without card chrome.
 function FormTitleBlock({
   title,
   subtitle,
@@ -2694,7 +2693,7 @@ function DefaultGrid({ columns, children, testId, maxRows }: GridProps): ReactNo
   // maxRows/scrolling don't apply — the row just wraps.
   if (columns === "auto") {
     return (
-      <div data-testid={testId} className="flex flex-wrap gap-4">
+      <div data-testid={testId} className="flex flex-wrap items-center gap-4">
         {children}
       </div>
     );