@cosmicdrift/kumiko-renderer-web 0.233.0 → 0.235.0

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

@@ -129,6 +129,69 @@ describe("KumikoScreen / projectionDetail — record header + metrics band", ()
     expect(screen.queryByTestId("kumiko-screen-projection-detail-title")).toBeNull();
     expect(screen.queryByTestId("kumiko-screen-projection-detail-metrics")).toBeNull();
   });
+
+  test("colors the status badge via the StatusTone heuristic for a recognized value", async () => {
+    const headerScreen: ProjectionDetailScreenDefinition = {
+      ...baseScreen,
+      header: { title: "tenantName", status: "state" },
+    };
+    const dispatcher = dispatcherReturning({ ...rowData, state: "overdue" });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(headerScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.getByTestId("kumiko-screen-projection-detail-status").className).toContain(
+      "text-status-bad",
+    );
+  });
+
+  test("an unmapped status value falls back to the muted tone", async () => {
+    const headerScreen: ProjectionDetailScreenDefinition = {
+      ...baseScreen,
+      header: { title: "tenantName", status: "state" },
+    };
+    const dispatcher = dispatcherReturning({ ...rowData, state: "archived" });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(headerScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.getByTestId("kumiko-screen-projection-detail-status").className).toContain(
+      "text-muted-foreground",
+    );
+  });
+
+  test("read-only detail screens render no footer action bar", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaFor(baseScreen)}
+          qn="rentals:screen:rent-detail"
+          entityId="rent-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.queryByTestId("render-edit-form-actions")).toBeNull();
+  });
 });
 
 describe("KumikoScreen / projectionDetail — metric tiles render through the Metric primitive", () => {
@@ -399,6 +462,58 @@ describe("KumikoScreen / projectionDetail — layout.mode: 'tabs'", () => {
 
     expect(setSearchParamsCalls).toContainEqual({ tab: "payments" });
   });
+
+  test("relatedList tab content renders without its own Section card wrapper", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const { navApi } = navWithTab("payments");
+
+    render(
+      <NavProvider value={navApi}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+
+    await waitFor(() =>
+      expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:payments")).toBe(true),
+    );
+    // hideTitle (tabs mode) drops the Section wrapper — DataTable already
+    // draws its own card frame, so a second nested Card would double it up.
+    expect(screen.queryByTestId("related-list-Payments")).toBeNull();
+  });
+
+  test("without a Tabs primitive, falls back to the stacked all-sections layout instead of truncating to the first section (fw#2501)", async () => {
+    const dispatcher = dispatcherReturning(rowData);
+    const { navApi } = navWithTab(undefined);
+
+    renderWithPrimitivesOverride(
+      <NavProvider value={navApi}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen
+            schema={schemaFor(tabsScreen)}
+            qn="rentals:screen:rent-detail"
+            entityId="rent-1"
+          />
+        </DispatcherProvider>
+      </NavProvider>,
+      { Tabs: undefined },
+    );
+
+    await waitFor(() => screen.getByTestId("field-description"));
+    // Pre-fix: activeSection stayed truncated to sections[0] even without a
+    // Tabs primitive to switch away from it — payments/invoices content was
+    // permanently unreachable, with no tab strip to reach it either.
+    await waitFor(() =>
+      expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:payments")).toBe(true),
+    );
+    expect(dispatcher.calls.some((c) => c.type === "rentals:query:rent:invoices")).toBe(true);
+    expect(screen.queryByTestId("kumiko-screen-projection-detail-tabs")).toBeNull();
+  });
 });
 
 // Only guard against a solon-shaped screen (relatedList-heavy) silently regressing.
@@ -448,6 +563,10 @@ describe("KumikoScreen / projectionDetail — unchanged for a solon-shaped scree
     // Contrast for the tabs-mode "form title suppressed" test above — outside
     // tabs mode (hideSectionTitles unset) the form's own title still renders.
     expect(screen.getByTestId("render-edit-form-title")).toBeTruthy();
+    // Contrast for the tabs-mode "no Section wrapper" test above — a stacked
+    // (non-tabs) relatedList section has a visible title, so it keeps its
+    // own Section card.
+    expect(screen.getByTestId("related-list-Payments")).toBeTruthy();
   });
 });
 

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

@@ -119,8 +119,8 @@ describe("RenderEdit", () => {
     // notes is hidden (isUrgent=false): title, count, isUrgent → 3 cells.
     expect(grid?.children.length).toBe(3);
 
-    const urgentCheckbox = screen.getByTestId("field-isUrgent").querySelector('[role="checkbox"]');
-    fireEvent.click(urgentCheckbox as HTMLElement);
+    const urgentSwitch = screen.getByTestId("field-isUrgent").querySelector('[role="switch"]');
+    fireEvent.click(urgentSwitch as HTMLElement);
 
     // notes becomes visible → 4 cells, no leftover empty cell from before.
     expect(grid?.children.length).toBe(4);
@@ -240,10 +240,9 @@ describe("RenderEdit", () => {
     );
 
     expect(screen.queryByTestId("field-notes")).toBeNull();
-    // boolean-Feld = vendored Radix-Checkbox → button[role=checkbox], kein
-    // native input[type=checkbox] mehr.
-    const urgentCheckbox = screen.getByTestId("field-isUrgent").querySelector('[role="checkbox"]');
-    fireEvent.click(urgentCheckbox as HTMLElement);
+    // boolean field in a standard form = vendored Radix Switch → button[role=switch].
+    const urgentSwitch = screen.getByTestId("field-isUrgent").querySelector('[role="switch"]');
+    fireEvent.click(urgentSwitch as HTMLElement);
     expect(screen.queryByTestId("field-notes")).toBeTruthy();
   });
 
@@ -284,7 +283,7 @@ describe("RenderEdit", () => {
     expect(seenResults[0]?.isSuccess).toBe(true);
   });
 
-  test("layout.width defaults the form shell to max-w-full when unset", () => {
+  test("layout.width defaults the form shell to max-w-4xl when unset", () => {
     render(
       <DispatcherProvider dispatcher={makeDispatcher()}>
         <RenderEdit<TestValues>
@@ -298,7 +297,7 @@ describe("RenderEdit", () => {
     );
 
     const shell = screen.getByTestId("render-edit-form").firstElementChild;
-    expect(shell?.className).toContain("max-w-full");
+    expect(shell?.className).toContain("max-w-4xl");
     expect(shell?.className).not.toContain("max-w-3xl");
   });
 
@@ -2858,8 +2857,8 @@ describe("RenderEdit locked state (#1896)", () => {
     expect((titleInput as HTMLInputElement).disabled).toBe(true);
     const countInput = screen.getByTestId("field-count").querySelector("input");
     expect((countInput as HTMLInputElement).disabled).toBe(true);
-    const urgentCheckbox = screen.getByTestId("field-isUrgent").querySelector('[role="checkbox"]');
-    expect((urgentCheckbox as HTMLButtonElement).disabled).toBe(true);
+    const urgentSwitch = screen.getByTestId("field-isUrgent").querySelector('[role="switch"]');
+    expect((urgentSwitch as HTMLButtonElement).disabled).toBe(true);
     expect((screen.getByTestId("render-edit-submit") as HTMLButtonElement).disabled).toBe(true);
   });
 

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

@@ -0,0 +1,287 @@
+//
+// Unit tests for the secretsEdit screen type. Secrets are write-only — the
+// security invariant this file exists to pin: an input NEVER starts pre-filled
+// with the redacted preview, and no dispatched payload ever carries that
+// preview string next to the plaintext the user typed.
+//
+// `as unknown as Dispatcher["query"/"batch"/"write"]` throughout: each inline
+// mock lambda only implements the one overload a given test exercises, never
+// the full overloaded Dispatcher signature — the missing overloads are never
+// called at runtime.
+
+import { describe, expect, mock, test } from "bun:test";
+import type { SecretsEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, DispatcherError } from "@cosmicdrift/kumiko-headless";
+import type { FeatureSchema } from "@cosmicdrift/kumiko-renderer";
+import { DispatcherProvider, KumikoScreen } from "@cosmicdrift/kumiko-renderer";
+import userEvent from "@testing-library/user-event";
+import { createMockDispatcher, render, screen, waitFor } from "./test-utils";
+
+const secretsScreen: SecretsEditScreenDefinition = {
+  id: "secrets",
+  type: "secretsEdit",
+  secretKeys: { "stripe-api-key": "stripe:secret:api-key" },
+  fieldLabels: { "stripe-api-key": "config.secret.stripe.api-key.label" },
+  sections: [{ fields: ["stripe-api-key"] }],
+};
+
+const schema: FeatureSchema = {
+  featureName: "config",
+  entities: {},
+  screens: [secretsScreen],
+};
+
+describe("KumikoScreen / secretsEdit", () => {
+  test("a set secret shows its redacted preview while the input stays empty", async () => {
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: [{ key: "stripe:secret:api-key", redactedPreview: "sk_***abc", hint: null }],
+      })) as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    await waitFor(() => screen.getByText("sk_***abc"));
+    const input = screen.getByTestId("secret-input-stripe-api-key") as HTMLInputElement;
+    expect(input.value).toBe("");
+  });
+
+  test("submitting with no input dispatches nothing", async () => {
+    const batchSpy = mock(async (_commands: ReadonlyArray<{ type: string; payload: unknown }>) => ({
+      isSuccess: true as const,
+      results: [],
+    }));
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({ isSuccess: true, data: [] })) as unknown as Dispatcher["query"],
+      batch: batchSpy as unknown as Dispatcher["batch"],
+    });
+
+    const user = userEvent.setup();
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    await user.click(screen.getByTestId("secrets-edit-submit"));
+    expect(batchSpy).not.toHaveBeenCalled();
+  });
+
+  test("typing a value and saving dispatches exactly one secrets:write:set with the plaintext, never the redacted preview", async () => {
+    const batchSpy = mock(async (_commands: ReadonlyArray<{ type: string; payload: unknown }>) => ({
+      isSuccess: true as const,
+      results: [],
+    }));
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: [{ key: "stripe:secret:api-key", redactedPreview: "sk_***abc", hint: null }],
+      })) as unknown as Dispatcher["query"],
+      batch: batchSpy as unknown as Dispatcher["batch"],
+    });
+
+    const user = userEvent.setup();
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    const input = screen.getByTestId("secret-input-stripe-api-key");
+    await user.type(input, "sk_live_newvalue");
+    await user.click(screen.getByTestId("secrets-edit-submit"));
+
+    await waitFor(() => expect(batchSpy).toHaveBeenCalledTimes(1));
+    const commands = batchSpy.mock.calls[0]?.[0];
+    if (!commands) throw new Error("batchSpy not called");
+    expect(commands).toEqual([
+      {
+        type: "secrets:write:set",
+        payload: { key: "stripe:secret:api-key", value: "sk_live_newvalue" },
+      },
+    ]);
+    // The security invariant this test exists for: the preview never rides
+    // along in a write payload next to the plaintext.
+    expect(JSON.stringify(commands)).not.toContain("sk_***abc");
+  });
+
+  test("an unset required secret shows the required marker; a set one does not", async () => {
+    const requiredScreen: SecretsEditScreenDefinition = {
+      ...secretsScreen,
+      requiredFields: ["stripe-api-key"],
+    };
+    const requiredSchema: FeatureSchema = {
+      featureName: "config",
+      entities: {},
+      screens: [requiredScreen],
+    };
+
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({ isSuccess: true, data: [] })) as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={requiredSchema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    await waitFor(() => screen.getByTestId("required-marker-stripe-api-key"));
+  });
+
+  test("a set required secret does not show the required marker", async () => {
+    const requiredScreen: SecretsEditScreenDefinition = {
+      ...secretsScreen,
+      requiredFields: ["stripe-api-key"],
+    };
+    const requiredSchema: FeatureSchema = {
+      featureName: "config",
+      entities: {},
+      screens: [requiredScreen],
+    };
+    const qualifiedKey = requiredScreen.secretKeys["stripe-api-key"];
+
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: [{ key: qualifiedKey, redactedPreview: "sk_***abc", hint: null }],
+      })) as unknown as Dispatcher["query"],
+    });
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={requiredSchema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    await waitFor(() => screen.getByText("sk_***abc"));
+    expect(screen.queryByTestId("required-marker-stripe-api-key")).toBeNull();
+  });
+
+  test("an unset required secret does not block saving a different secret", async () => {
+    const twoFieldScreen: SecretsEditScreenDefinition = {
+      id: "secrets",
+      type: "secretsEdit",
+      secretKeys: {
+        "stripe-api-key": "stripe:secret:[REDACTED:API key param]",
+        "webhook-secret": "stripe:secret:[REDACTED:webhook param]",
+      },
+      fieldLabels: {
+        "stripe-api-key": "config.secret.stripe.api-key.label",
+        "webhook-secret": "config.secret.stripe.webhook.label",
+      },
+      sections: [{ fields: ["stripe-api-key", "webhook-secret"] }],
+      requiredFields: ["stripe-api-key"],
+    };
+    const twoFieldSchema: FeatureSchema = {
+      featureName: "config",
+      entities: {},
+      screens: [twoFieldScreen],
+    };
+    const batchSpy = mock(async (_commands: ReadonlyArray<{ type: string; payload: unknown }>) => ({
+      isSuccess: true as const,
+      results: [],
+    }));
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({ isSuccess: true, data: [] })) as unknown as Dispatcher["query"],
+      batch: batchSpy as unknown as Dispatcher["batch"],
+    });
+
+    const user = userEvent.setup();
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={twoFieldSchema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    const requiredInput = screen.getByTestId("secret-input-stripe-api-key") as HTMLInputElement;
+    expect(requiredInput.required).toBe(false);
+
+    await user.type(screen.getByTestId("secret-input-webhook-secret"), "whsec_newvalue");
+    await user.click(screen.getByTestId("secrets-edit-submit"));
+
+    await waitFor(() => expect(batchSpy).toHaveBeenCalledTimes(1));
+    const commands = batchSpy.mock.calls[0]?.[0];
+    if (!commands) throw new Error("batchSpy not called");
+    expect(commands).toEqual([
+      {
+        type: "secrets:write:set",
+        payload: { key: "stripe:secret:[REDACTED:webhook param]", value: "whsec_newvalue" },
+      },
+    ]);
+  });
+
+  test("delete dispatches secrets:write:delete with the qualified key", async () => {
+    const writeSpy = mock(async (_type: string, _payload: unknown) => ({
+      isSuccess: true as const,
+      data: {},
+    }));
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({
+        isSuccess: true,
+        data: [{ key: "stripe:secret:api-key", redactedPreview: "sk_***abc", hint: null }],
+      })) as unknown as Dispatcher["query"],
+      write: writeSpy as unknown as Dispatcher["write"],
+    });
+
+    const user = userEvent.setup();
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    await user.click(screen.getByTestId("secret-delete-stripe-api-key"));
+
+    await waitFor(() => expect(writeSpy).toHaveBeenCalledTimes(1));
+    expect(writeSpy).toHaveBeenCalledWith("secrets:write:delete", { key: "stripe:secret:api-key" });
+  });
+
+  test("a failed save shows the error and never renders the typed plaintext", async () => {
+    const plaintext = "sk_live_wouldbeleakedifechoed";
+    const serverError: DispatcherError = {
+      code: "TENANT_SECRET_WRITE_CONFLICT",
+      httpStatus: 409,
+      i18nKey: "secrets:errors.writeConflict",
+      message: "Could not save secret: a concurrent update conflicted, please retry.",
+    };
+    const batchSpy = mock(async (_commands: ReadonlyArray<{ type: string; payload: unknown }>) => ({
+      isSuccess: false as const,
+      error: serverError,
+    }));
+    const dispatcher: Dispatcher = createMockDispatcher({
+      query: (async () => ({ isSuccess: true, data: [] })) as unknown as Dispatcher["query"],
+      batch: batchSpy as unknown as Dispatcher["batch"],
+    });
+
+    const user = userEvent.setup();
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="config:screen:secrets" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("secrets-edit-form"));
+    const input = screen.getByTestId("secret-input-stripe-api-key");
+    await user.type(input, plaintext);
+    await user.click(screen.getByTestId("secrets-edit-submit"));
+
+    await waitFor(() => screen.getByTestId("secrets-edit-error"));
+    expect(screen.getByTestId("secrets-edit-error").textContent).toContain(serverError.message);
+    // The drafted plaintext must never leak into the error surface (or
+    // anywhere else in the DOM besides the input's own `value`).
+    expect(document.body.textContent).not.toContain(plaintext);
+  });
+});

package/src/__tests__/workspace-shell.test.tsx

@@ -440,13 +440,12 @@ describe("WorkspaceShell", () => {
     expect(screen.queryByText("Tours")).toBeNull();
   });
 
-  test("fill=true applies h-svh on root and min-h-0 on inset/main", () => {
+  test("fill defaults to true: applies h-svh on root and min-h-0 on inset/main", () => {
     renderShell(
       <WorkspaceShell
         brand={<div>Brand</div>}
         schema={schema}
         user={{ id: "u1", roles: ["admin"] }}
-        fill
       >
         <div>content</div>
       </WorkspaceShell>,
@@ -462,13 +461,15 @@ describe("WorkspaceShell", () => {
     expect(innerMain?.classList.contains("overflow-auto")).toBe(true);
   });
 
-  // #1692: default (no fill) must not force viewport-lock classes
-  test("without fill does not apply h-svh or min-h-0", () => {
+  // fill={false} is the escape hatch back to page-scroll: must not apply
+  // viewport-lock classes.
+  test("fill={false} does not apply h-svh or min-h-0", () => {
     renderShell(
       <WorkspaceShell
         brand={<div>Brand</div>}
         schema={schema}
         user={{ id: "u1", roles: ["admin"] }}
+        fill={false}
       >
         <div>content</div>
       </WorkspaceShell>,

package/src/icons.tsx

@@ -1,5 +1,20 @@
+// Icon registry: symbolic `NavIconKey` → lucide-react component. `NavIconKey`
+// is the closed vocabulary a feature author can write (packages/types/src/
+// nav-icon.ts); `satisfies` below makes this map a compile-time drift
+// guard — a key added to one without the other fails the build.
+//
+// Runtime data (provider-supplied nav/action icons) is only typed as plain
+// `string` at the resolved-tree layer, so an unknown key can still show up
+// at runtime on occasion — `Icon` falls back to rendering the raw key as
+// text rather than crashing, mirroring the old `ActionGlyph` behavior in
+// nav-tree.tsx.
+//
+// Buttons resolve icons through the same map — importing it from the nav
+// layout module would couple them to the sidebar.
 import type { NavIconKey } from "@cosmicdrift/kumiko-framework/ui-types";
 import {
+  AlertTriangle,
+  Archive,
   ArrowLeft,
   ArrowRight,
   BarChart3,
@@ -9,17 +24,27 @@ import {
   Calculator,
   CalendarDays,
   Check,
+  CheckCircle2,
+  ChevronDown,
+  ChevronRight,
   ClipboardList,
+  Clock,
   Coins,
   Copy,
   CreditCard,
   Download,
+  ExternalLink,
+  Eye,
+  EyeOff,
   FileText,
+  Filter,
+  Flag,
   Folder,
   FolderOpen,
   Gauge,
   Hash,
   Home,
+  Info,
   KeyRound,
   Languages,
   Layers,
@@ -28,14 +53,23 @@ import {
   LineChart,
   Link,
   List,
+  Loader2,
   Lock,
   Mail,
+  MapPin,
+  MoreHorizontal,
+  MoreVertical,
   Package,
   Palette,
+  Pencil,
+  Phone,
   PiggyBank,
   Plus,
+  Printer,
   Receipt,
+  RefreshCw,
   Rocket,
+  Save,
   Search,
   Send,
   Server,
@@ -44,19 +78,23 @@ import {
   Shield,
   ShieldCheck,
   Sparkles,
+  Star,
   Table,
   Tag,
   Trash2,
   TrendingUp,
+  Undo2,
   Upload,
   User,
   Users,
   Wallet,
   Wand2,
   X,
+  XCircle,
 } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "./lib/cn";
 
-// Buttons resolve icons through the same map, importing it from the nav layout module would couple them to the sidebar.
 export const NAV_ICONS = {
   dashboard: LayoutDashboard,
   "layout-grid": LayoutGrid,
@@ -113,4 +151,49 @@ export const NAV_ICONS = {
   "arrow-left": ArrowLeft,
   "arrow-right": ArrowRight,
   copy: Copy,
+  pencil: Pencil,
+  eye: Eye,
+  "eye-off": EyeOff,
+  filter: Filter,
+  refresh: RefreshCw,
+  "more-horizontal": MoreHorizontal,
+  "more-vertical": MoreVertical,
+  "external-link": ExternalLink,
+  "chevron-down": ChevronDown,
+  "chevron-right": ChevronRight,
+  save: Save,
+  undo: Undo2,
+  archive: Archive,
+  star: Star,
+  flag: Flag,
+  clock: Clock,
+  "map-pin": MapPin,
+  phone: Phone,
+  printer: Printer,
+  "alert-triangle": AlertTriangle,
+  info: Info,
+  "check-circle": CheckCircle2,
+  "x-circle": XCircle,
+  loader: Loader2,
 } as const satisfies Readonly<Record<NavIconKey, typeof Folder>>;
+
+// Widened alias for runtime lookups against the plain `string` icon keys
+// resolved-tree nodes carry — not the closed NavIconKey union NAV_ICONS
+// itself is typed against.
+const ICON_LOOKUP: Readonly<Record<string, typeof Folder | undefined>> = NAV_ICONS;
+
+export function Icon({
+  name,
+  className,
+}: {
+  readonly name: NavIconKey;
+  readonly className?: string;
+}): ReactNode {
+  const LucideIcon = Object.hasOwn(NAV_ICONS, name) ? ICON_LOOKUP[name] : undefined;
+  if (LucideIcon !== undefined) return <LucideIcon aria-hidden="true" className={className} />;
+  return (
+    <span aria-hidden="true" className={cn("text-xs", className)}>
+      {name}
+    </span>
+  );
+}

package/src/layout/app-layout.tsx

@@ -13,12 +13,12 @@ export type AppLayoutProps = {
   readonly sidebar?: ReactNode;
   readonly children: ReactNode;
   readonly testId?: string;
-  /** Viewport-fit Shell. true → Wurzel = `h-screen` (fixe Viewport-Höhe),
-   *  Sidebar/Topbar bleiben stehen, der Main-Bereich scrollt INNEN
-   *  (`min-h-0` + `overflow-auto`). false (Default) → klassischer
-   *  `min-h-screen`-Flow, die ganze Seite scrollt. Dashboard-artige Apps
-   *  wollen `true`; eine öffentliche, lange Content-Seite eher `false`.
-   *  Clippt nie — der Content scrollt in `main` statt im Body. */
+  /** Viewport-fit Shell. Default `true` → Wurzel = `h-screen` (fixe
+   *  Viewport-Höhe), Sidebar/Topbar bleiben stehen, der Main-Bereich
+   *  scrollt INNEN (`min-h-0` + `overflow-auto`). `false` → klassischer
+   *  `min-h-screen`-Flow, die ganze Seite scrollt — Escape-Hatch für
+   *  eine öffentliche, lange Content-Seite die echten Body-Scroll
+   *  braucht. Clippt nie — der Content scrollt in `main` statt im Body. */
   readonly fill?: boolean;
   /** Optionaler Klassen-Append an die Wurzel (eigener Hintergrund etc.).
    *  Erweitert die Defaults, ersetzt sie nicht (cn-merge). */
@@ -32,7 +32,7 @@ export function AppLayout({
   sidebar,
   children,
   testId,
-  fill,
+  fill = true,
   className,
   mainClassName,
 }: AppLayoutProps): ReactNode {