@cosmicdrift/kumiko-renderer-web 0.244.0 → 0.246.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.244.0",
+  "version": "0.246.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.244.0",
-    "@cosmicdrift/kumiko-headless": "0.244.0",
-    "@cosmicdrift/kumiko-renderer": "0.244.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.246.0",
+    "@cosmicdrift/kumiko-headless": "0.246.0",
+    "@cosmicdrift/kumiko-renderer": "0.246.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -64,7 +64,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.244.0"
+    "@cosmicdrift/kumiko-locale-de": "0.246.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/nav-tree.test.tsx

@@ -21,8 +21,8 @@ import type {
   TreeChildrenSubscribe,
   TreeNode,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { FeatureSchema, LiveEventSubscriber } from "@cosmicdrift/kumiko-renderer";
-import { LiveEventsProvider } from "@cosmicdrift/kumiko-renderer";
+import type { FeatureSchema, LiveEventSubscriber, NavApi } from "@cosmicdrift/kumiko-renderer";
+import { LiveEventsProvider, NavProvider } from "@cosmicdrift/kumiko-renderer";
 import { act } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { NavProvidersProvider } from "../app/nav-providers-context";
@@ -463,6 +463,90 @@ describe("NavTree navBadges (Runtime-Badge-Slot)", () => {
   });
 });
 
+// fw#2724: leaving a list for a sub-screen (entityEdit/actionForm/...) used
+// to lose BOTH orientation cues at once — nav marks nothing, breadcrumb
+// shrinks to one crumb. NavTree now falls back to resolveParentScreenId
+// (same resolution shell-breadcrumb.ts uses) when the routed screen has no
+// node of its own in the tree.
+function navWithRoute(screenId: string): NavApi {
+  return {
+    route: { screenId },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: () => {},
+  };
+}
+
+describe("NavTree active-marker parent fallback", () => {
+  test("screen without its own nav entry highlights the resolved parent, without aria-current", () => {
+    const schema: FeatureSchema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "user-list", type: "entityList", entity: "profile", columns: [] },
+        {
+          id: "user-edit",
+          type: "entityEdit",
+          // Deliberately a DIFFERENT entity than "user-list" — the old
+          // same-entity heuristic must NOT be what resolves this; only the
+          // explicit listScreenId does.
+          entity: "user-detail",
+          listScreenId: "user-list",
+          layout: { sections: [{ fields: [] }] },
+        },
+      ],
+      navs: [{ id: "user-list", label: "Users", screen: "user-list", order: 10 }],
+    } as FeatureSchema;
+
+    render(
+      <NavProvider value={navWithRoute("user-edit")}>
+        <NavTree schema={schema} />
+      </NavProvider>,
+    );
+
+    const link = screen.getByText("Users").closest("a");
+    expect(link?.getAttribute("data-active")).toBe("true");
+    expect(link?.hasAttribute("aria-current")).toBe(false);
+  });
+
+  test("screen with its own nav entry still marks itself and keeps aria-current=page", () => {
+    const schema: FeatureSchema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "user-list", type: "entityList", entity: "profile", columns: [] },
+        {
+          id: "user-edit",
+          type: "entityEdit",
+          entity: "profile",
+          layout: { sections: [{ fields: [] }] },
+        },
+      ],
+      navs: [
+        { id: "user-list", label: "Users", screen: "user-list", order: 10 },
+        { id: "user-edit", label: "Edit User", screen: "user-edit", order: 20 },
+      ],
+    } as FeatureSchema;
+
+    render(
+      <NavProvider value={navWithRoute("user-edit")}>
+        <NavTree schema={schema} />
+      </NavProvider>,
+    );
+
+    const editLink = screen.getByText("Edit User").closest("a");
+    expect(editLink?.getAttribute("data-active")).toBe("true");
+    expect(editLink?.getAttribute("aria-current")).toBe("page");
+
+    // The list is not silently highlighted too — only the exact match is.
+    const listLink = screen.getByText("Users").closest("a");
+    expect(listLink?.getAttribute("data-active")).toBe("false");
+    expect(listLink?.hasAttribute("aria-current")).toBe(false);
+  });
+});
+
 // ── Visual-Tree-Merge: dynamische Knoten in der EINEN Nav ──────────────
 //
 // Beweist die vier Caps die NavTree aus dem alten VisualTree übernimmt:

package/src/__tests__/primitives.test.tsx

@@ -437,6 +437,34 @@ describe("DataTable", () => {
     expect(onRowClick).toHaveBeenCalledWith(row);
   });
 
+  // chromeless (fw#2722): a relatedList section in a tabs-mode Akte already
+  // sits inside a tab panel — the table's own card frame would nest a card
+  // inside that boundary without separating anything further.
+  describe("chromeless", () => {
+    const cols = [{ field: "name", label: "Name", type: "string", sortable: false }] as const;
+    const oneRow = [{ id: "r1", values: { name: "Alice" } }];
+
+    // Table itself renders its own [data-slot="table-container"] wrapper div
+    // (ui/table.tsx) around the <table data-testid> — the card frame lives
+    // one level up, on DefaultDataTable's own wrapping div.
+    test("default: table renders with its own card frame", () => {
+      render(<DataTable columns={cols} rows={oneRow} testId="t" />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).toContain("border");
+      expect(wrapper?.className).toContain("rounded-lg");
+      expect(wrapper?.className).toContain("bg-card");
+    });
+
+    test("chromeless: table drops the card frame, table markup is unchanged", () => {
+      render(<DataTable columns={cols} rows={oneRow} testId="t" chromeless />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).not.toContain("border");
+      expect(wrapper?.className).not.toContain("rounded-lg");
+      expect(wrapper?.className).not.toContain("bg-card");
+      expect(screen.getByTestId("row-r1")).not.toBeNull();
+    });
+  });
+
   // Sort-Header pinnt das 3-State-Toggle-Verhalten + Visual-Indicator
   // + aria-sort. Renderer-Vertrag mit dem Caller (RenderList): jede
   // sortable-Column liefert beim Click den nächsten Sort-State zurück

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

@@ -923,3 +923,143 @@ describe("KumikoScreen / projectionDetail extension section with its own <form>
     expect(outerSubmitFired).toBe(false);
   });
 });
+
+// fw#2713: `actions` are on the record the head shows, not on whichever tab
+// is open — they used to render in the card footer, below the active tab's
+// content, so a long tab pushed them off-screen and they visually "moved"
+// as the tab content's length changed. They now render inside the head
+// region (title/status/metrics), before any tab content, in both layout
+// modes — `single` gets the same treatment as `tabs` since the actions
+// belong to the header regardless of how the body is laid out.
+describe("KumikoScreen / projectionDetail header actions placement (fw#2713)", () => {
+  const dispatcher: Dispatcher = createMockDispatcher({
+    query: (async () => ({
+      isSuccess: true,
+      data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+    })) as unknown as Dispatcher["query"],
+  });
+
+  test("with actions declared: the action button renders in the head region, before the tab content, not in the form footer", async () => {
+    const screenWithActions: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      header: { title: "userId" },
+      layout: { mode: "tabs", sections: detailScreen.layout.sections },
+      actions: [
+        {
+          kind: "navigate",
+          id: "open-user",
+          label: "sessions.detail.action.openUser",
+          screen: "user-detail",
+        },
+      ],
+    };
+    const schemaWithActions: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [screenWithActions],
+    };
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaWithActions}
+          qn="sessions:screen:session-detail"
+          entityId="sess-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    const actionButton = await waitFor(() => screen.getByTestId("render-edit-action-open-user"));
+    // The footer regions RenderEdit's Form would otherwise draw the action
+    // into are gone entirely — the action moved out, it didn't just gain a
+    // second home.
+    expect(screen.queryByTestId("render-edit-form-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions-secondary")).toBeNull();
+    // The action sits in the head Card, ahead of the field it shares a
+    // screen with in document order — i.e. inside headerRegion, not the
+    // card body below it.
+    const field = screen.getByTestId("field-userId");
+    expect(
+      actionButton.compareDocumentPosition(field) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  test("without actions: no action area renders at all (no empty strip, no leftover footer)", async () => {
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="sessions:screen:session-detail" entityId="sess-1" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.queryByTestId("kumiko-screen-projection-detail-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions-secondary")).toBeNull();
+  });
+
+  test("switching tabs leaves the action in place — same head placement regardless of which tab is active", async () => {
+    const tabsScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      header: { title: "userId" },
+      layout: {
+        mode: "tabs",
+        sections: [
+          { id: "overview", title: "Session", fields: ["userId"] },
+          { id: "meta", title: "Meta", fields: ["createdAt"] },
+        ],
+      },
+      actions: [
+        {
+          kind: "navigate",
+          id: "open-user",
+          label: "sessions.detail.action.openUser",
+          screen: "user-detail",
+        },
+      ],
+    };
+    const tabsSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [tabsScreen],
+    };
+    function navWithTab(tab: string | undefined): NavApi {
+      return {
+        route: undefined,
+        navigate: () => {},
+        replace: () => {},
+        hrefFor: () => "",
+        searchParams: tab !== undefined ? { tab } : {},
+        setSearchParams: () => {},
+      };
+    }
+
+    const { unmount } = render(
+      <NavProvider value={navWithTab("overview")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen schema={tabsSchema} qn="sessions:screen:session-detail" entityId="sess-1" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    const buttonOnOverview = await waitFor(() =>
+      screen.getByTestId("render-edit-action-open-user"),
+    );
+    expect(buttonOnOverview.textContent).toBe("sessions.detail.action.openUser");
+    unmount();
+
+    render(
+      <NavProvider value={navWithTab("meta")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen schema={tabsSchema} qn="sessions:screen:session-detail" entityId="sess-1" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    const buttonOnMeta = await waitFor(() => screen.getByTestId("render-edit-action-open-user"));
+    expect(buttonOnMeta.textContent).toBe("sessions.detail.action.openUser");
+    // Same head placement on both tabs — ahead of whichever field the
+    // active tab shows, not trailing it.
+    const fieldOnMeta = screen.getByTestId("field-createdAt");
+    expect(
+      buttonOnMeta.compareDocumentPosition(fieldOnMeta) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+});

package/src/layout/__tests__/shell-breadcrumb.test.ts

@@ -105,4 +105,78 @@ describe("resolveDetailBreadcrumb", () => {
   test("unknown screen returns undefined", () => {
     expect(resolveDetailBreadcrumb([], "missing", t)).toBeUndefined();
   });
+
+  // fw#2724: explicit `listScreenId` on entityEdit/actionForm must win over
+  // the rowAction/entity heuristics, not just supplement them (the way it
+  // already did for custom/projectionDetail above).
+  test("explicit listScreenId on entityEdit wins over the rowAction heuristic", () => {
+    const screens: ScreenDefinition[] = [
+      {
+        id: "user-list",
+        type: "entityList",
+        entity: "user",
+        columns: ["email"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "kumiko.actions.view",
+            screen: "user-edit",
+            entityId: "id",
+          },
+        ],
+      },
+      {
+        id: "user-archive",
+        type: "entityList",
+        entity: "user",
+        columns: ["email"],
+        rowActions: [],
+      },
+      {
+        id: "user-edit",
+        type: "entityEdit",
+        entity: "user",
+        listScreenId: "user-archive",
+        layout: { sections: [{ fields: ["email"] }] },
+      },
+    ];
+    // Without the explicit field, the rowAction heuristic would resolve
+    // "user-list" (see "entityList navigate rowAction..." above) — the
+    // declared listScreenId overrides that guess.
+    expect(resolveDetailBreadcrumb(screens, "user-edit", t)?.[0]?.screenId).toBe("user-archive");
+  });
+
+  // Regression guard: an actionForm without listScreenId (the common case —
+  // the field is new and optional) must keep resolving exactly like before,
+  // via the rowAction heuristic. Pins that existing apps see no change.
+  test("actionForm without listScreenId still resolves via the rowAction heuristic", () => {
+    const screens: ScreenDefinition[] = [
+      {
+        id: "invoice-list",
+        type: "entityList",
+        entity: "invoice",
+        columns: ["status"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "approve",
+            label: "kumiko.actions.view",
+            screen: "invoice-approve",
+            entityId: "id",
+          },
+        ],
+      },
+      {
+        id: "invoice-approve",
+        type: "actionForm",
+        handler: "billing:write:invoice:approve",
+        fields: { notes: { type: "text" } },
+        layout: { sections: [{ fields: ["notes"] }] },
+      },
+    ];
+    expect(resolveDetailBreadcrumb(screens, "invoice-approve", t)?.[0]?.screenId).toBe(
+      "invoice-list",
+    );
+  });
 });

package/src/layout/nav-tree.tsx

@@ -56,6 +56,7 @@ import {
   SidebarMenuSubItem,
   useSidebar,
 } from "../ui/sidebar";
+import { resolveParentScreenId } from "./shell-breadcrumb";
 import { useDispatchTarget } from "./target-resolver-stub";
 import { parseTargetFromSearchParams } from "./target-url";
 
@@ -92,6 +93,24 @@ const NavBadgesContext = createContext<ReadonlyMap<string, ReactNode>>(EMPTY_BAD
 type NavFilter = { readonly q: string; readonly matches: (rawLabel: string) => boolean };
 const NavFilterContext = createContext<NavFilter>({ q: "", matches: () => true });
 
+// Which nav node should highlight for the current route. `exact` means the
+// active screen has its own node in {tree} (aria-current="page" belongs
+// here); otherwise {screenId} is the resolved parent from
+// resolveParentScreenId — a screen reachable only through a list stays
+// orientable, but a Screen-Reader shouldn't be told it IS that list.
+type ActiveScreenMarker = { readonly screenId: string; readonly exact: boolean } | undefined;
+const ActiveScreenMarkerContext = createContext<ActiveScreenMarker>(undefined);
+
+// Walks only the static `children` — provider-emitted nodes (treeNodeToNavNode
+// below) never set `screen`, so they can't hide a match this walk would miss.
+function treeContainsScreen(nodes: readonly NavNode[], screenId: string): boolean {
+  return nodes.some(
+    (n) =>
+      (n.screen !== undefined && lastSegment(n.screen) === screenId) ||
+      treeContainsScreen(n.children, screenId),
+  );
+}
+
 // Ein Knoten überlebt den Filter, wenn er selbst oder ein Nachfahre matcht.
 // Provider-Kinder sind zur Filterzeit schon materialisiert (Provider-Knoten
 // sind default-expanded → eager geladen), darum reicht die statische
@@ -115,6 +134,19 @@ export function NavTree({
     return resolveNavigation({ source, ...(user !== undefined && { user }) });
   }, [app, user, allowedNavQns]);
 
+  const nav = useNav();
+  const activeScreenId = nav.route?.screenId;
+  // Same "no nav entry of its own" gap the breadcrumb closes (fw#2724):
+  // when the routed screen has no node in {tree}, fall back to its
+  // resolved parent so a detail/edit/form screen still orients the user.
+  const activeMarker = useMemo((): ActiveScreenMarker => {
+    if (activeScreenId === undefined) return undefined;
+    if (treeContainsScreen(tree, activeScreenId)) return { screenId: activeScreenId, exact: true };
+    const allScreens = app.features.flatMap((f) => f.screens);
+    const parentScreenId = resolveParentScreenId(allScreens, activeScreenId);
+    return parentScreenId !== undefined ? { screenId: parentScreenId, exact: false } : undefined;
+  }, [tree, app.features, activeScreenId]);
+
   // Collapsed-Set: nur die explizit zugeklappten qualified-names. Default
   // ist also "alles auf" — neue Features tauchen sofort offen auf, ohne
   // dass der User erst klicken muss.
@@ -148,34 +180,36 @@ export function NavTree({
   const navFilter = useMemo<NavFilter>(() => ({ q, matches }), [q, matches]);
 
   return (
-    <NavFilterContext.Provider value={navFilter}>
-      <NavBadgesContext.Provider value={navBadges ?? EMPTY_BADGES}>
-        <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
-          <div className="px-2 pt-2 pb-1 group-data-[collapsible=icon]:hidden">
-            <SidebarInput
-              value={filter}
-              onChange={(e) => setFilter(e.target.value)}
-              placeholder={t("kumiko.nav.search")}
-              aria-label={t("kumiko.nav.search")}
-            />
-          </div>
-          {tree.map((node) =>
-            isPureSection(node) ? (
-              <NavSection
-                key={node.qualifiedName}
-                node={node}
-                collapsed={collapsed}
-                onToggle={onToggle}
+    <ActiveScreenMarkerContext.Provider value={activeMarker}>
+      <NavFilterContext.Provider value={navFilter}>
+        <NavBadgesContext.Provider value={navBadges ?? EMPTY_BADGES}>
+          <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
+            <div className="px-2 pt-2 pb-1 group-data-[collapsible=icon]:hidden">
+              <SidebarInput
+                value={filter}
+                onChange={(e) => setFilter(e.target.value)}
+                placeholder={t("kumiko.nav.search")}
+                aria-label={t("kumiko.nav.search")}
               />
-            ) : (
-              <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
-                <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
-              </SidebarMenu>
-            ),
-          )}
-        </div>
-      </NavBadgesContext.Provider>
-    </NavFilterContext.Provider>
+            </div>
+            {tree.map((node) =>
+              isPureSection(node) ? (
+                <NavSection
+                  key={node.qualifiedName}
+                  node={node}
+                  collapsed={collapsed}
+                  onToggle={onToggle}
+                />
+              ) : (
+                <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
+                  <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
+                </SidebarMenu>
+              ),
+            )}
+          </div>
+        </NavBadgesContext.Provider>
+      </NavFilterContext.Provider>
+    </ActiveScreenMarkerContext.Provider>
   );
 }
 
@@ -387,6 +421,9 @@ type NavNodeState = {
   readonly expandable: boolean;
   readonly isExpanded: boolean;
   readonly active: boolean;
+  // Narrower than `active`: true only for the node that IS the routed
+  // screen — never for a parent-fallback match. Drives aria-current="page".
+  readonly ariaCurrent: boolean;
   readonly childNodes: readonly NavNode[];
   readonly hidden: boolean;
   readonly providerLoading: boolean;
@@ -416,8 +453,12 @@ function useNavNodeState(node: NavNode, collapsed: ReadonlySet<string>): NavNode
     () => parseTargetFromSearchParams(nav.searchParams),
     [nav.searchParams],
   );
+  const activeMarker = useContext(ActiveScreenMarkerContext);
   const screenActive =
-    node.screen !== undefined && nav.route?.screenId === lastSegment(node.screen);
+    node.screen !== undefined &&
+    activeMarker !== undefined &&
+    lastSegment(node.screen) === activeMarker.screenId;
+  const screenIsExactMatch = screenActive && activeMarker?.exact === true;
   const targetActive = node.target !== undefined && targetsEqual(node.target, activeTarget);
   const childNodes = node.provider === true ? (providerChildren ?? []) : node.children;
   const visibleChildNodes = filterActive
@@ -429,6 +470,7 @@ function useNavNodeState(node: NavNode, collapsed: ReadonlySet<string>): NavNode
     expandable,
     isExpanded,
     active: screenActive || targetActive,
+    ariaCurrent: screenIsExactMatch || targetActive,
     childNodes: visibleChildNodes,
     // Ein gefilterter Knoten verschwindet nur, wenn weder er selbst noch ein
     // sichtbar gebliebenes Kind matcht — sonst bliebe ein leerer Ordner-Header.
@@ -595,7 +637,7 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         <SidebarMenuButton asChild isActive={s.active} tooltip={s.displayLabel}>
           <KumikoLink
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
-            {...(s.active && { "aria-current": "page" })}
+            {...(s.ariaCurrent && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
             <span
@@ -715,7 +757,7 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         <SidebarMenuSubButton asChild isActive={s.active}>
           <KumikoLink
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
-            {...(s.active && { "aria-current": "page" })}
+            {...(s.ariaCurrent && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
             <span

package/src/layout/shell-breadcrumb.ts

@@ -1,5 +1,5 @@
 import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
-import { lastSegment } from "./nav-tree";
+import { lastSegment } from "@cosmicdrift/kumiko-renderer";
 
 export type BreadcrumbCrumb = {
   readonly label: string;
@@ -10,13 +10,38 @@ export function screenTitleKey(screenShortId: string): string {
   return `screen:${screenShortId}.title`;
 }
 
-export function resolveDetailBreadcrumb(
+// 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":
+      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.
+function resolveParentScreen(
   screens: readonly ScreenDefinition[],
-  detailScreenId: string,
-  t: (key: string) => string,
-): readonly BreadcrumbCrumb[] | undefined {
-  const detail = screens.find((s) => lastSegment(s.id) === detailScreenId);
-  if (detail === undefined) return undefined;
+  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;
@@ -28,22 +53,31 @@ export function resolveDetailBreadcrumb(
       ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
       : undefined;
 
-  const listFromCustomParent =
-    detail.type === "custom" && detail.listScreenId !== undefined
-      ? screens.find((s) => lastSegment(s.id) === detail.listScreenId)
-      : undefined;
+  return listFromExplicit ?? listFromRowAction ?? listFromEntity;
+}
 
-  // projectionDetail has no entity to pair with an entityList (unlike
-  // entityEdit above) — `listScreenId` is its only back-navigation source.
-  // Needed because RenderEdit's Cancel button is never wired up for this
-  // screen type and isn't reachable via a listFromRowAction either.
-  const listFromProjectionDetailParent =
-    detail.type === "projectionDetail" && detail.listScreenId !== undefined
-      ? screens.find((s) => lastSegment(s.id) === detail.listScreenId)
-      : undefined;
+/** The short id of {screenId}'s parent list screen, resolved via the same
+ *  logic as `resolveDetailBreadcrumb` — `undefined` when nothing resolves
+ *  (unknown screen, or no explicit/heuristic parent). */
+export function resolveParentScreenId(
+  screens: readonly ScreenDefinition[],
+  screenId: string,
+): string | undefined {
+  const detail = screens.find((s) => lastSegment(s.id) === screenId);
+  if (detail === undefined) return undefined;
+  const parent = resolveParentScreen(screens, detail);
+  return parent !== undefined ? lastSegment(parent.id) : undefined;
+}
+
+export function resolveDetailBreadcrumb(
+  screens: readonly ScreenDefinition[],
+  detailScreenId: string,
+  t: (key: string) => string,
+): readonly BreadcrumbCrumb[] | undefined {
+  const detail = screens.find((s) => lastSegment(s.id) === detailScreenId);
+  if (detail === undefined) return undefined;
 
-  const list =
-    listFromRowAction ?? listFromEntity ?? listFromCustomParent ?? listFromProjectionDetailParent;
+  const list = resolveParentScreen(screens, detail);
   if (list === undefined) {
     return [{ label: t(screenTitleKey(detailScreenId)) }];
   }

package/src/primitives/__tests__/select-display-request.test.tsx

@@ -0,0 +1,122 @@
+// `kind: "select"` with an explicit `display` (#2711). The short-option-set
+// heuristic covered by select-segmented.test.tsx stays the default; these
+// tests only cover the case where the caller states a presentation and the
+// heuristic would have decided the other way.
+
+import { describe, expect, test } from "bun:test";
+import { fireEvent } from "@testing-library/react";
+import { render, screen } from "../../__tests__/test-utils";
+import { defaultPrimitives } from "../index";
+
+const { Field, Input } = defaultPrimitives;
+
+// Six options, every label past the 14-char threshold — the heuristic would
+// render a dropdown for these.
+const HEURISTIC_REJECTS = [
+  "Background Jobs Queue",
+  "Inbound Mail Processing",
+  "Realtime Event Stream",
+  "Scheduled Reporting",
+  "Tenant Provisioning",
+  "Search Index Rebuild",
+];
+
+// Three short labels — the heuristic would render the radio group for these.
+const HEURISTIC_ACCEPTS = ["Draft", "Review", "Done"];
+
+function renderSelect(
+  options: readonly string[],
+  overrides: {
+    readonly display?: "radio" | "dropdown";
+    readonly value?: string;
+  } = {},
+): string[] {
+  const changes: string[] = [];
+  render(
+    <Field id="area" label="Area" testId="field-area">
+      <Input
+        kind="select"
+        id="area"
+        name="area"
+        value={overrides.value ?? options[0] ?? ""}
+        onChange={(v) => changes.push(v)}
+        options={options}
+        {...(overrides.display !== undefined && { display: overrides.display })}
+      />
+    </Field>,
+  );
+  return changes;
+}
+
+describe("DefaultInput select — explicit display request", () => {
+  test('display: "radio" renders the radio group even where the heuristic says dropdown', () => {
+    renderSelect(HEURISTIC_REJECTS, { display: "radio" });
+    expect(screen.queryByTestId("combobox-area")).toBeNull();
+    expect(screen.getAllByRole("radio")).toHaveLength(6);
+  });
+
+  test("the forced radio group keeps the accessible group name and checked state", () => {
+    renderSelect(HEURISTIC_REJECTS, {
+      display: "radio",
+      value: "Realtime Event Stream",
+    });
+    expect(screen.getByRole("radiogroup", { name: "Area" })).toBeTruthy();
+    expect(
+      screen.getByRole("radio", { name: "Realtime Event Stream" }).getAttribute("aria-checked"),
+    ).toBe("true");
+    expect(
+      screen.getByRole("radio", { name: "Background Jobs Queue" }).getAttribute("aria-checked"),
+    ).toBe("false");
+  });
+
+  test("the forced radio group reports the raw option value on click", () => {
+    const changes = renderSelect(HEURISTIC_REJECTS, {
+      display: "radio",
+      value: "Background Jobs Queue",
+    });
+    fireEvent.click(screen.getByRole("radio", { name: "Search Index Rebuild" }));
+    expect(changes).toEqual(["Search Index Rebuild"]);
+  });
+
+  test('display: "dropdown" keeps the dropdown where the heuristic says radio group', () => {
+    renderSelect(HEURISTIC_ACCEPTS, { display: "dropdown" });
+    expect(screen.queryByRole("radiogroup")).toBeNull();
+    expect(screen.getByTestId("combobox-area")).toBeTruthy();
+  });
+
+  test("no display stated: the heuristic still decides", () => {
+    renderSelect(HEURISTIC_REJECTS);
+    expect(screen.getByTestId("combobox-area")).toBeTruthy();
+  });
+
+  test('display: "radio" without options falls back to the dropdown, not an empty group', () => {
+    renderSelect([], { display: "radio" });
+    expect(screen.queryByRole("radiogroup")).toBeNull();
+    expect(screen.getByTestId("combobox-area")).toBeTruthy();
+  });
+
+  test("labelled options render their label and report their value", () => {
+    const changes: string[] = [];
+    render(
+      <Field id="area" label="Area" testId="field-area">
+        <Input
+          kind="select"
+          id="area"
+          name="area"
+          value="jobs"
+          onChange={(v) => changes.push(v)}
+          display="radio"
+          options={[
+            { value: "jobs", label: "Background Jobs Queue" },
+            { value: "mail", label: "Inbound Mail Processing" },
+            { value: "search", label: "Search Index Rebuild" },
+            { value: "events", label: "Realtime Event Stream" },
+            { value: "tenants", label: "Tenant Provisioning" },
+          ]}
+        />
+      </Field>,
+    );
+    fireEvent.click(screen.getByRole("radio", { name: "Inbound Mail Processing" }));
+    expect(changes).toEqual(["mail"]);
+  });
+});

package/src/primitives/index.tsx

@@ -422,11 +422,10 @@ function withUnitSuffix(unit: string | undefined, input: ReactNode): ReactNode {
   );
 }
 
-// Segmented control for `kind: "select"` with a small closed option set —
+// Default presentation for `kind: "select"` with a small closed option set —
 // a 4-value Status field looked wrong stretched into a full-width dropdown
-// (edit-existing screenshot feedback). Purely a rendering choice inside the
-// "select" branch below; the primitives contract is untouched (still
-// `options` + string value/onChange).
+// (edit-existing screenshot feedback). Only consulted when the caller states
+// no `display` of its own; an explicit `display` wins (#2711).
 const SEGMENTED_SELECT_MAX_OPTIONS = 4;
 const SEGMENTED_SELECT_MAX_LABEL_LENGTH = 14;
 
@@ -699,7 +698,13 @@ function DefaultInput(props: InputProps): ReactNode {
       const comboOptions = props.options.map((o) =>
         typeof o === "string" ? { value: o, label: o } : o,
       );
-      if (isSegmentedSelectEligible(comboOptions)) {
+      // An explicit `display` is an author decision and outranks the
+      // heuristic in both directions — a requested radio group renders as
+      // one even when the labels are long or numerous (#2711).
+      const wantsRadioGroup =
+        props.display === "radio" ||
+        (props.display === undefined && isSegmentedSelectEligible(comboOptions));
+      if (wantsRadioGroup && comboOptions.length > 0) {
         return (
           <SegmentedSelect
             id={props.id}
@@ -898,6 +903,7 @@ function DefaultDataTable({
   onCellChange,
   getRowTestId,
   getCellTestId,
+  chromeless,
 }: DataTableProps): ReactNode {
   // One locale/translate subscription per table — not per cell (fw#2345).
   // Optional hooks: a bare DataTable outside LocaleProvider must not crash.
@@ -930,7 +936,8 @@ function DefaultDataTable({
       // trägt den bg-muted-Grauton. `bg-card` (statt transparent) → die Liste
       // sitzt auf derselben Card-Fläche wie Forms; auf Themes mit farbigem
       // Page-Background (z.B. Cream) matchen Listen sonst nicht die Cards.
-      <div className="overflow-hidden rounded-lg border bg-card">
+      // `chromeless` drops that frame for a host with its own boundary already (a tab panel, fw#2722).
+      <div className={cn("overflow-hidden", chromeless !== true && "rounded-lg border bg-card")}>
         <Table data-testid={testId}>
           <TableHeader className="bg-muted">
             <TableRow className="hover:bg-transparent">