@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/dist/screen.d.ts

@@ -0,0 +1,1265 @@
+import type { FieldIconKey } from "./field-icon.js";
+import type { FieldDefinition, FormFieldDefinition, SelectOptionTone } from "./fields.js";
+import type { AccessRule, AgentHandlerHints } from "./handlers.js";
+import type { IconKey, NavIconKey } from "./nav-icon.js";
+export type { FieldIconKey } from "./field-icon.js";
+export type PlatformComponent = {
+    readonly react?: unknown;
+    readonly native?: unknown;
+};
+export type UnitKey = "m2" | "km" | "m" | "kg" | "percent" | "mi";
+export interface FieldFormatRegistry {
+    timestamp: {
+        readonly locale?: string;
+        readonly dateStyle?: "full" | "long" | "medium" | "short";
+        readonly timeStyle?: "full" | "long" | "medium" | "short";
+    };
+    date: {
+        readonly locale?: string;
+        readonly dateStyle?: "full" | "long" | "medium" | "short";
+    };
+    boolean: {
+        readonly trueLabel?: string;
+        readonly falseLabel?: string;
+    };
+    currency: {
+        readonly symbol?: string;
+    };
+    priority: {
+        readonly emptyLabel?: string;
+        readonly prefix?: string;
+    };
+    /** `grouping: false` renders without thousands-separators (e.g. a model
+     *  year: "2021", not "2.021"). Default `true`. */
+    number: {
+        readonly locale?: string;
+        readonly grouping?: boolean;
+    };
+    decimal: {
+        readonly locale?: string;
+        readonly grouping?: boolean;
+    };
+    bigInt: {
+        readonly locale?: string;
+        readonly grouping?: boolean;
+    };
+    unit: {
+        readonly unit: UnitKey;
+        readonly locale?: string;
+        readonly unitDisplay?: "long" | "short" | "narrow";
+    };
+    enumOption: {
+        readonly keyPrefix: string;
+    };
+    /** JSON-safe structured value rendered as indented text. */
+    json: {
+        readonly indent?: number;
+    };
+}
+export type FormatSpec = {
+    [K in keyof FieldFormatRegistry]: {
+        readonly format: K;
+    } & FieldFormatRegistry[K];
+}[keyof FieldFormatRegistry];
+export type FieldRenderer = PlatformComponent | string | FormatSpec;
+export type FieldCondition = boolean | {
+    readonly field: string;
+    readonly eq: unknown;
+} | {
+    readonly field: string;
+    readonly ne: unknown;
+} | {
+    readonly field: string;
+    readonly in: readonly unknown[];
+} | {
+    readonly field: string;
+    readonly notIn: readonly unknown[];
+};
+export type ListColumnSpec = string | {
+    readonly field: string;
+    readonly renderer?: FieldRenderer;
+    /** Optional header, overriding the default
+     *  `<feature>:entity:<entity>:field:<field>` i18n convention. Resolved
+     *  through `translate` like any header — an i18n key, or a plain literal
+     *  shown verbatim if it isn't a key. Also the way to declare a *virtual*
+     *  column whose `field` is NOT an entity field — a presentational column
+     *  drawn entirely by a `columnRenderer` component that reads the `row`
+     *  (e.g. a tag-chips cell), not a stored value. Such a column needs a
+     *  label; without one it is rejected at boot as an unknown field. `field`
+     *  is then just a stable column key (pick any unique slug). */
+    readonly label?: string;
+    /** Marks this column as a reference lookup instead of a plain value —
+     *  for projectionList/relatedList columns, which have no
+     *  `EntityDefinition` to carry a real `reference` field type. Same
+     *  target convention as `parseRefTarget`: an entity name (same
+     *  feature) or `feature:entity` (cross-feature). Ignored on
+     *  `entityList` columns, where the field's own declared type always
+     *  wins. */
+    readonly refEntity?: string;
+    /** Row field on the referenced entity shown as the label (default
+     *  "id"). Only meaningful together with `refEntity`. */
+    readonly refLabelField?: string;
+    /** Marks this column as sortable via a clickable header — for
+     *  relatedList columns, which have no `EntityDefinition` field to carry
+     *  `sortable` on. Ignored on `entityList` columns, where the entity
+     *  field's own `sortable` flag wins. */
+    readonly sortable?: boolean;
+    /** Value type of a relatedList column, which has no `EntityDefinition`
+     *  field to derive it from. Numeric types right-align the column and its
+     *  header with tabular figures, like an entityList column of that field
+     *  type. Ignored on entityList columns, where the field's own type wins. */
+    readonly valueType?: "number" | "decimal" | "bigInt" | "money";
+    /** Leaves the column out of the compact card layout used below the
+     *  `md` breakpoint (tables keep it). For columns that only make sense
+     *  next to the others, like a sort key. */
+    readonly hideOnNarrow?: boolean;
+};
+export type ListPaginationMode = "pages" | "infinite" | false;
+export type ListSortDir = "asc" | "desc";
+export type ListSortSpec = {
+    readonly field: string;
+    readonly dir: ListSortDir;
+};
+export type ScreenFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+export type ScreenFilter = {
+    readonly field: string;
+    readonly op: ScreenFilterOp;
+    readonly value: unknown;
+};
+/** Declarative row-field extractor — JSON-safe (no function prop, survives
+ *  GET /api/schema / buildAppSchema).
+ *
+ *  `pick`: extracts fields 1:1. `{ pick: ["id", "version"] }` → `{ id: row.id, version: row.version }`
+ *  `map`:  renames fields.      `{ map: { incidentId: "id" } }` → `{ incidentId: row.id }`
+ *
+ *  Limitation: computed/templated values can't be expressed this way —
+ *  that logic belongs server-side in the write handler. */
+export type RowFieldExtractor = {
+    readonly pick: readonly string[];
+} | {
+    readonly map: Readonly<Record<string, string>>;
+};
+export type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer;
+export type RowActionWriteHandler = {
+    /** Default für RowActions ohne explizit gesetzten `kind` —
+     *  Backwards-kompatible Form. Kann auch explizit gesetzt werden. */
+    readonly kind?: "writeHandler";
+    /** Stable id pro Screen — kebab-case, eindeutig im Action-Set. */
+    readonly id: string;
+    /** Anzeige-Text (i18n-Key). */
+    readonly label: string;
+    /** Qualified-Name des Server-Handlers, z.B.
+     *  "publicstatus:write:maintenance:start". Wird via useDispatcher
+     *  dispatcht. */
+    readonly handler: string;
+    /** Deklarativer Payload pro Row. Default = `{ id: row.id }`.
+     *  `pick` extrahiert Felder gleichen Namens; `map` benennt um. */
+    readonly payload?: RowFieldExtractor;
+    /** i18n-Key für die Confirm-Dialog-Description. Wenn gesetzt, öffnet
+     *  ein Modal vor der Ausführung — der User muss explizit bestätigen.
+     *  Zusammen mit `style: "danger"` ist das die Standard-Sicherheits-
+     *  Garde für destruktive Aktionen. */
+    readonly confirm?: string;
+    /** i18n-Key für den Confirm-Button-Text im Dialog. Default = `label`
+     *  (also "Delete" → "Delete"-Button im Confirm). Setzen wenn die
+     *  Action einen langen Namen hat ("Mark Subscription as Cancelled")
+     *  und der Button kürzer sein soll ("Cancel Subscription"). */
+    readonly confirmLabel?: string;
+    /** Conditional Visibility pro Row. */
+    readonly visible?: FieldCondition;
+    /** Visual-Style. "danger" rendert rot + erzwingt einen Confirm-
+     *  Dialog (auch ohne expliziten `confirm`-Key). */
+    readonly style?: "primary" | "secondary" | "danger";
+    /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
+     *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
+     *  (renderer-web), analogous to EditFieldSpec.icon. */
+    readonly icon?: IconKey;
+};
+export type RowActionNavigateBase = {
+    readonly kind: "navigate";
+    readonly id: string;
+    readonly label: string;
+    /** Feldname dessen Wert als entityId in den URL-Pfad eingebettet wird
+     *  (`/<workspace>/<screen>/<entityId>`). entityEdit liest die Id
+     *  AUSSCHLIESSLICH aus dem Pfad. Default: "id" wenn der Ziel-Screen ein
+     *  entityEdit ist ODER wenn `entity` (statt `screen`) gesetzt ist. */
+    readonly entityId?: string;
+    /** Declarative URL search params extracted from the clicked row.
+     *  Both actionForm and entityEdit-create targets read `params` as
+     *  initial values (pre-filling the form). entityEdit-update does
+     *  not — the existing record's values take precedence.
+     *  `pick` extracts fields of the same name; `map` renames them. */
+    readonly params?: RowFieldExtractor;
+    /** Section id of the tab to activate on the target projectionDetail
+     *  (layout.mode "tabs"); merged into the navigate search params next to
+     *  returnTo. Boot validator checks the id exists on the target. */
+    readonly tab?: string;
+    /** Conditional Visibility pro Row. */
+    readonly visible?: FieldCondition;
+    /** Visual style only — unlike the writeHandler variants, "danger" does not
+     *  force a confirm dialog here: the target form is the confirmation. */
+    readonly style?: "primary" | "secondary" | "danger";
+    /** Wenn true, löst ein Klick auf die ganze Zeile (nicht nur das Aktionsmenü)
+     *  diese navigate-Action aus. Max. eine pro Liste (Boot-Validator prüft). Nur
+     *  auf navigate — ein Row-Klick darf keinen (evtl. destruktiven, unbestätigten)
+     *  Write auslösen, daher nicht auf writeHandler-Actions. */
+    readonly rowClick?: boolean;
+    /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
+     *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
+     *  (renderer-web), analogous to EditFieldSpec.icon. */
+    readonly icon?: IconKey;
+};
+/** Exactly one of `screen` / `entity` — mutual exclusivity is type-enforced
+ *  (boot validator still rejects both/neither for untyped schemas). */
+export type RowActionNavigate = RowActionNavigateBase & ({
+    /** Screen-id (kurz, unqualified). Boot-Validator prüft Existenz im
+     *  selben Feature. */
+    readonly screen: string;
+    readonly entity?: never;
+} | {
+    /** Entity-Name statt Screen-Id (fw#2228) — löst zur Boot-Zeit auf den
+     *  Screen auf, der `detailFor: "<entity>"` deklariert (siehe ObjectTarget/
+     *  resolveTarget in @cosmicdrift/kumiko-renderer's nav.tsx). */
+    readonly entity: string;
+    readonly screen?: never;
+});
+export type RowActionDrawer = {
+    readonly kind: "drawer";
+    readonly id: string;
+    readonly label: string;
+    /** Short, unqualified id of an `actionForm` screen in the same feature.
+     *  Boot validator rejects a missing screen and a screen whose `type`
+     *  isn't `actionForm` — same check as ToolbarAction's drawer variant
+     *  (see docs/plans/bundled-features-screen-standardisierung.md §2.6c). */
+    readonly screen: string;
+    /** Declarative prefill extracted from the clicked row. `pick` extracts
+     *  fields of the same name; `map` renames them. */
+    readonly params?: RowFieldExtractor;
+    /** Per-row conditional visibility. */
+    readonly visible?: FieldCondition;
+    /** Visual style only — unlike the writeHandler variants, "danger" does not
+     *  force a confirm dialog here: the target form is the confirmation. */
+    readonly style?: "primary" | "secondary" | "danger";
+    /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
+     *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
+     *  (renderer-web), analogous to EditFieldSpec.icon. */
+    readonly icon?: IconKey;
+};
+export type ToolbarAction = {
+    readonly kind: "navigate";
+    readonly id: string;
+    readonly label: string;
+    /** Screen-id (kurz, unqualified) zu dem navigiert wird. */
+    readonly screen: string;
+    /** Section id of the tab to activate on the target projectionDetail
+     *  (layout.mode "tabs"); merged into the navigate search params next to
+     *  returnTo. Boot validator checks the id exists on the target. */
+    readonly tab?: string;
+    /** Visual style only — unlike the writeHandler variant, "danger" does
+     *  not force a confirm dialog here: the target form is the
+     *  confirmation. */
+    readonly style?: "primary" | "secondary" | "danger";
+} | {
+    readonly kind: "writeHandler";
+    readonly id: string;
+    readonly label: string;
+    readonly handler: string;
+    /** Statischer Payload ohne row-Context. Default = `{}`. */
+    readonly payload?: Record<string, unknown>;
+    /** i18n-Key für Confirm-Dialog-Description. Wenn gesetzt UND/ODER
+     *  style="danger": Modal vor der Ausführung. */
+    readonly confirm?: string;
+    /** i18n-Key für Confirm-Button-Text im Dialog. Default = `label`. */
+    readonly confirmLabel?: string;
+    readonly style?: "primary" | "secondary" | "danger";
+} | {
+    readonly kind: "drawer";
+    readonly id: string;
+    readonly label: string;
+    /** Short, unqualified id of an `actionForm` screen in the same
+     *  feature. Boot validator rejects a missing screen and a screen
+     *  whose `type` isn't `actionForm` — the caller decides full-page
+     *  vs. drawer, not the form (see docs/plans/bundled-features-screen-
+     *  standardisierung.md §2.6c). */
+    readonly screen: string;
+    /** Visual style only — unlike the writeHandler variant, "danger" does
+     *  not force a confirm dialog here: the target form is the
+     *  confirmation. */
+    readonly style?: "primary" | "secondary" | "danger";
+};
+export type RelatedListToolbarAction = (Extract<ToolbarAction, {
+    readonly kind: "navigate";
+}> & {
+    /** Conditional visibility, evaluated against the relatedList's parent
+     *  record (the "Akte"). */
+    readonly visible?: FieldCondition;
+    /** Declarative URL search params extracted from the parent record,
+     *  prefilling the target screen. Replaces the implicit
+     *  `{ [parentParam]: parentId }` default when set. */
+    readonly params?: RowFieldExtractor;
+}) | (Extract<ToolbarAction, {
+    readonly kind: "writeHandler";
+}> & {
+    readonly visible?: FieldCondition;
+}) | (Extract<ToolbarAction, {
+    readonly kind: "drawer";
+}> & {
+    readonly visible?: FieldCondition;
+});
+export type EntityListScreenDefinition = {
+    readonly id: string;
+    readonly type: "entityList";
+    /** Default true: the screen fills the shell content height, its body scrolls
+     *  inside and the pager / action bar stays pinned. `false` restores page
+     *  scroll (table grows with its rows, pager below the last row, form footer
+     *  in the flow). */
+    readonly fillHeight?: boolean;
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    readonly entity: string;
+    readonly columns: readonly ListColumnSpec[];
+    readonly rowRenderer?: PlatformComponent;
+    readonly cardRenderer?: PlatformComponent;
+    /** Per-Row-Aktionen — rendert eine Actions-Spalte rechts in der Tabelle.
+     *  Bis zu 2 actions als inline-Buttons; >2 als Kebab-Dropdown.
+     *  Reihenfolge im Array = Reihenfolge in der UI. */
+    readonly rowActions?: readonly RowAction[];
+    /** Toolbar-Aktionen (List-Header). "Open Incident", "Schedule Maintenance"
+     *  etc. — neben "+ Neu" wenn vorhanden. Reihenfolge im Array = UI-
+     *  Reihenfolge, primary-style links. */
+    readonly toolbarActions?: readonly ToolbarAction[];
+    /** Server-side Filter, fest am Screen — drei Buckets derselben
+     *  Entity ohne Custom-Pages (z.B. "Upcoming" / "Active" / "Past"
+     *  Maintenance). User-side q-Search läuft AUF dem gefilterten Set
+     *  oben drauf. Boot-Validator pinst dass field in der Entity existiert. */
+    readonly filter?: ScreenFilter;
+    readonly pagination?: ListPaginationMode;
+    readonly pageSize?: number;
+    readonly defaultSort?: ListSortSpec;
+    /** i18n key for the primary create button label (default `kumiko.actions.create`). */
+    readonly createLabel?: string;
+    /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
+    readonly searchPlaceholder?: string;
+    readonly searchable?: boolean;
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+export type ListFacetSpec = {
+    readonly field: string;
+    readonly type: "select";
+    readonly label: string;
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+} | {
+    readonly field: string;
+    readonly type: "boolean";
+    readonly label: string;
+    readonly trueLabel: string;
+    readonly falseLabel: string;
+} | {
+    readonly field: string;
+    readonly type: "reference";
+    readonly label: string;
+    /** Entity name (same feature) or `feature:entity` (cross-feature), same
+     *  convention as `ListColumnSpec.refEntity`. Options load at render time. */
+    readonly entity: string;
+    /** Row field on the referenced entity shown as the option label
+     *  (default "id"). */
+    readonly labelField?: string;
+} | {
+    /** Declarative only — the date field the range narrows. It is NOT sent
+     *  to the server (the bounds go under `params`); it namespaces the
+     *  facet's URL keys and tells a reading agent which column this list
+     *  is time-rangeable on. */
+    readonly field: string;
+    readonly type: "dateRange";
+    readonly label: string;
+    /** Query-payload keys the chosen bounds are sent under as ISO instants.
+     *  Explicit rather than a `from`/`to` convention — a query is free to
+     *  name its time bounds anything, and the boot-validator checks these
+     *  keys against the handler's Zod schema. */
+    readonly params: {
+        readonly from: string;
+        readonly to: string;
+    };
+};
+export type ProjectionListScreenDefinition = {
+    readonly id: string;
+    readonly type: "projectionList";
+    /** Default true: the screen fills the shell content height, its body scrolls
+     *  inside and the pager / action bar stays pinned. `false` restores page
+     *  scroll (table grows with its rows, pager below the last row, form footer
+     *  in the flow). */
+    readonly fillHeight?: boolean;
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    readonly query: string;
+    readonly columns: readonly ListColumnSpec[];
+    readonly rowRenderer?: PlatformComponent;
+    readonly cardRenderer?: PlatformComponent;
+    readonly rowActions?: readonly RowAction[];
+    readonly toolbarActions?: readonly ToolbarAction[];
+    readonly pagination?: ListPaginationMode;
+    readonly pageSize?: number;
+    readonly defaultSort?: ListSortSpec;
+    /** i18n key for the primary create button label (default `kumiko.actions.create`). */
+    readonly createLabel?: string;
+    /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
+    readonly searchPlaceholder?: string;
+    readonly searchable?: boolean;
+    /** Derived by buildAppSchema from the query handler's Zod schema (`sort`
+     *  param present). Same type serves author and wire schema (no separate
+     *  client-facing screen type exists), so this stays structurally
+     *  writable — validateProjectionListScreens rejects any hand-authored
+     *  value at boot (fw#2165). */
+    readonly sortable?: boolean;
+    /** Derived by buildAppSchema from the query handler's Zod schema (`cursor`
+     *  or `offset` param present). See `sortable` doc for why this is
+     *  boot-enforced rather than type-enforced. */
+    readonly paginated?: boolean;
+    /** Server-side filter, fixed on the screen — see `ScreenFilter` doc above
+     *  (entityList). Field existence can't be checked without an entity; the
+     *  boot-validator only checks structure (`op:"in"` ⇒ array value). */
+    readonly filter?: ScreenFilter;
+    /** User-toggleable facet dropdowns — see `ListFacetSpec` doc. `field`
+     *  must be a declared column; the bound query handler must accept
+     *  `filters` in its Zod schema — the boot-validator checks both. A
+     *  "dateRange" facet instead needs its two `params` keys in that schema;
+     *  it sends no `filters` entry. */
+    readonly facets?: readonly ListFacetSpec[];
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+export type RecordHeaderSpec = {
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly status?: string;
+    /** Record field holding an absolute http(s) URL. When present and the
+     *  field's value is such a URL, the subtitle renders as an external link
+     *  (`target="_blank"`) instead of plain text. */
+    readonly subtitleHref?: string;
+    /** Badge tone per `status` field value; unlisted values fall back to the value heuristic. */
+    readonly statusTones?: {
+        readonly [statusValue: string]: SelectOptionTone;
+    };
+};
+export type MetricNavigate = {
+    readonly screen?: string;
+    readonly entity?: string;
+    readonly entityId?: string;
+    readonly params?: RowFieldExtractor;
+    /** Section id of the tab to activate at the destination. Alone (no
+     *  `screen`/`entity`), it activates that tab on the current record
+     *  instead of navigating away. */
+    readonly tab?: string;
+};
+export type MetricSpec = string | {
+    readonly field: string;
+    readonly label?: string;
+    readonly navigate?: MetricNavigate;
+};
+export declare function metricField(metric: MetricSpec): string;
+export type ProjectionDetailScreenDefinition = {
+    readonly id: string;
+    readonly type: "projectionDetail";
+    /** Default true: the screen fills the shell content height, its body scrolls
+     *  inside and the pager / action bar stays pinned. `false` restores page
+     *  scroll (table grows with its rows, pager below the last row, form footer
+     *  in the flow). */
+    readonly fillHeight?: boolean;
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    readonly query: string;
+    /** Query-payload key for the row-id. Default "id". */
+    readonly idParam?: string;
+    /** The server determines the shown row from the caller's session/context
+     *  instead of a row id in the path — a self-service screen ("my profile",
+     *  "my data") that has no row to link to (unlike `EntityEditScreenDefinition.
+     *  singleton`, which still resolves via `<entity>:list` limit 1; here the
+     *  query itself owns the row selection, e.g. `user:query:user:me`). The
+     *  query is called WITHOUT the `idParam` key — there is no id to send, so
+     *  the boot-validator rejects declaring `idParam` alongside this flag
+     *  instead of letting one silently win. Stricter than an id-addressed
+     *  screen, not looser: the server picks the row, so no client-supplied id
+     *  can reach the query — a stray id on the path is ignored, never
+     *  forwarded. */
+    readonly singleton?: boolean;
+    readonly layout: EditLayout;
+    /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key), analog zu
+     *  entityEdit.fieldLabels. Die Pseudo-Entity `__projection-detail__` hat
+     *  keinen natürlichen Field-Namespace — fehlt ein Eintrag, gilt die
+     *  Konvention `<feature>:entity:__projection-detail__:field:<name>`. */
+    readonly fieldLabels?: Readonly<Record<string, string>>;
+    /** Record header above the layout — title/subtitle/status name columns
+     *  in the query row (not literals). Rendered only when set. */
+    readonly header?: RecordHeaderSpec;
+    /** Metric band above the layout — column names in the query row, labeled
+     *  via `fieldLabels` (string shorthand) or the object form's own `label`.
+     *  Rendered only when set. */
+    readonly metrics?: readonly MetricSpec[];
+    /** Parent list screen (kurze id) für eine "Zurück"-Navigation. */
+    readonly listScreenId?: string;
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+    /** Header action buttons. Reuses `RowAction` — the screen's single
+     *  displayed record stands in for the "row", so `pick`/`map`, `visible`,
+     *  `confirm`/`confirmLabel` and `style` keep their meaning unchanged.
+     *  `rowClick` has no target here (there is no row to click) and is
+     *  rejected by the boot-validator. */
+    readonly actions?: readonly RowAction[];
+    /** How head fields render. Default "text" — plain text instead of a
+     *  disabled Input, since every field on this screen type is forced
+     *  readOnly anyway (there is no write path, see the shim doc above).
+     *  Set "form" to opt back into the disabled-Input look (fw#2245). */
+    readonly valueDisplay?: "form" | "text";
+};
+export type DashboardStatPanel = {
+    readonly kind: "stat";
+    /** Stable id — kebab-case, eindeutig im Panel-Set. */
+    readonly id: string;
+    /** Anzeige-Text (i18n-Key). */
+    readonly label: string;
+    readonly query: string;
+    /** Static, author-set query parameters merged on top of the screen's
+     *  dynamic filterParams — lets a panel pin a value (e.g. a status facet)
+     *  the screen-wide filter doesn't cover, without needing its own query. */
+    readonly params?: Readonly<Record<string, unknown>>;
+    readonly valueField: string;
+    readonly subField?: string;
+    readonly toneField?: string;
+    /** Optionaler Delta-Chip (z.B. "↓23 %") neben dem Label. Nur wenn BEIDE
+     *  Felder gesetzt sind UND der Query-Handler sie liefert, rendert der Chip
+     *  — sonst bleibt die Kachel wie ohne Delta. `deltaToneField` fällt auf
+     *  `toneField`/"default" zurück, wenn ungesetzt. */
+    readonly deltaField?: string;
+    readonly deltaDirectionField?: string;
+    readonly deltaToneField?: string;
+    /** Statisches Icon neben dem Label — anders als value/sub/delta variiert
+     *  das Icon nicht pro Query-Result, sondern ist eine Author-Entscheidung
+     *  wie das Panel selbst. Aufgelöst über dieselbe extensionSectionComponents-
+     *  Registry wie custom-Panels; die registrierte Komponente ignoriert
+     *  typischerweise entityName/entityId/filterParams (kein Entity-Kontext
+     *  für ein reines Icon). */
+    readonly icon?: PlatformComponent;
+    /** Statischer CSS-Farbwert (z.B. "var(--color-debt)") für den Icon-Chip —
+     *  Passthrough an die Kachel, keine Registry, kein Lookup. Wirkt NUR wenn
+     *  `icon` gesetzt ist (StatCard rendert den Chip nur zusammen mit einem
+     *  Icon) — ohne icon wird der Wert still verworfen. */
+    readonly accentColor?: string;
+};
+export type DashboardChartPanel = {
+    readonly kind: "chart";
+    readonly id: string;
+    readonly label: string;
+    /** v1: geglättete Zeitreihe. Weitere Chart-Formen additiv. */
+    readonly chart: "timeseries";
+    readonly query: string;
+};
+export type DashboardListPanel = {
+    readonly kind: "list";
+    readonly id: string;
+    readonly label: string;
+    readonly query: string;
+    readonly columns: readonly ListColumnSpec[];
+};
+export type DashboardStatGroupPanel = {
+    readonly kind: "stat-group";
+    readonly id: string;
+    readonly label: string;
+    readonly stats: readonly DashboardStatPanel[];
+};
+export type DashboardFeedPanel = {
+    readonly kind: "feed";
+    readonly id: string;
+    readonly label: string;
+    readonly query: string;
+    readonly emptyLabel?: string;
+};
+export type DashboardProgressListPanel = {
+    readonly kind: "progress-list";
+    readonly id: string;
+    readonly label: string;
+    readonly query: string;
+};
+export type DashboardCustomPanel = {
+    readonly kind: "custom";
+    readonly id: string;
+    readonly component: PlatformComponent;
+};
+export type DashboardPanelVisibility = {
+    readonly query: string;
+    readonly field: string;
+    readonly eq: string | number | boolean | null;
+};
+export type DashboardScreenPanel = {
+    readonly kind: "screen";
+    readonly id: string;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>`. */
+    readonly screen: string;
+    readonly label?: string;
+    readonly visibleWhen?: DashboardPanelVisibility;
+};
+export type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardCustomPanel | DashboardScreenPanel;
+export type DashboardFilterDefinition = {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "select";
+    readonly placeholder?: string;
+    /** i18n-Key für den "(alle)"-Eintrag. */
+    readonly allLabel?: string;
+    readonly options?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** Query-Result-Contract: `{ rows: { value: string; label: string }[] }`. */
+    readonly optionsQuery?: string;
+};
+export type DashboardScreenDefinition = {
+    readonly id: string;
+    readonly type: "dashboard";
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    readonly panels: readonly DashboardPanelDefinition[];
+    readonly filter?: DashboardFilterDefinition;
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+export type EditFieldSpec = string | {
+    readonly field: string;
+    readonly span?: number;
+    readonly visible?: FieldCondition;
+    readonly readOnly?: FieldCondition;
+    readonly required?: FieldCondition;
+    readonly renderer?: FieldRenderer;
+    /** Prefix icon on the input — closed FieldIconKey vocabulary into
+     *  the FIELD_ICONS registry (renderer-web), analogous to
+     *  `ScreenNavSugar.icon` / NavIconKey. Only takes effect for
+     *  single-line `type: "text"` and `"number"` — a `text` field with
+     *  `multiline` routes to a textarea (no icon slot), and other input
+     *  kinds (select, combobox, date, …) silently ignore the key. */
+    readonly icon?: FieldIconKey;
+    /** Marks this field as a reference lookup instead of a plain value —
+     *  for projectionDetail fields, which have no `EntityDefinition` to
+     *  carry a real `reference` field type. Same target convention as
+     *  `parseRefTarget` (and `ListColumnSpec.refEntity`): an entity name
+     *  (same feature) or `feature:entity` (cross-feature). Ignored on
+     *  `entityEdit` fields, where the field's own declared type always
+     *  wins. */
+    readonly refEntity?: string;
+    /** Row field on the referenced entity shown as the label (default
+     *  "id"). Only meaningful together with `refEntity`. */
+    readonly refLabelField?: string;
+};
+export type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
+export type EditFieldsSection = {
+    /** Kebab-case tab id, used as the `?tab=` value. Required by the
+     *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
+    readonly id?: string;
+    readonly kind?: "fields";
+    /** Optional. Ohne Titel rendert die Section nur ihre Felder (keine h3-
+     *  Überschrift) — für flache Forms (Card-Titel + Felder direkt, ein
+     *  einzelner Abschnitt) wie bei den meisten shadcn-Form-Mustern. */
+    readonly title?: string;
+    /** Optional help text under the block heading (i18n key or raw string,
+     *  like `title`) — makes a form usable without training instead of
+     *  falling back to custom JSX for help text. Renders through the same
+     *  `subtitle` slot as `FormProps.subtitle`. Works without `title` too
+     *  (subtitle-only section). */
+    readonly description?: string;
+    readonly columns?: number;
+    /** Mutually exclusive with `groups` — pass `[]` when using `groups`; the
+     *  boot-validator rejects both non-empty or both empty. */
+    readonly fields: readonly EditFieldSpec[];
+    /** Splits the section into multiple titled cards instead of one flat grid.
+     *  Mutually exclusive with `fields`; fields named here still need to exist. */
+    readonly groups?: readonly {
+        readonly title: string;
+        readonly fields: readonly EditFieldSpec[];
+        /** Default 2. */
+        readonly columns?: number;
+    }[];
+    /** Rendered left of the section title, `text-muted-foreground` — closed
+     *  IconKey vocabulary into the ICONS registry (renderer-web), analogous
+     *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
+     *  one from the title (titles are free i18n strings). */
+    readonly icon?: IconKey;
+    /** Record field rendered as a count badge in the tab label when the
+     *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+     *  Ignored outside tabs mode or when the field's value is not a finite
+     *  number. */
+    readonly countField?: string;
+    /** Rendered top-right in the section's Card title row — same
+     *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+     *  evaluated against the same record. Every action must resolve an icon
+     *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+    readonly actions?: readonly RowAction[];
+};
+export type EditExtensionSection = {
+    /** Kebab-case tab id, used as the `?tab=` value. Required by the
+     *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
+    readonly id?: string;
+    readonly kind: "extension";
+    readonly title: string;
+    readonly component: PlatformComponent;
+    /** When true, the extension registers via `useExtensionFormSubmit` and the
+     *  surrounding form's Save button should activate for its dirty state.
+     *  Omit/false for extensions that persist through their own dispatcher
+     *  writes (e.g. notes-history NotesSection) — otherwise a read-only form
+     *  shows a Save button that does nothing (fw#2359). */
+    readonly contributesToFormSubmit?: boolean;
+    /** Overrides the host-derived entity name passed to the mounted component.
+     *  Required on `projectionDetail` (which has no real entity — the host
+     *  value there is an internal placeholder) so a self-persisting extension
+     *  like NotesSection filters/writes against the right domain entity. Takes
+     *  precedence over the host value on every screen type. */
+    readonly entityName?: string;
+    /** Record field rendered as a count badge in the tab label when the
+     *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+     *  Ignored outside tabs mode or when the field's value is not a finite
+     *  number. */
+    readonly countField?: string;
+    /** Rendered top-right in the section's Card title row — same
+     *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+     *  evaluated against the same record. Every action must resolve an icon
+     *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+    readonly actions?: readonly RowAction[];
+};
+export type EditRelatedListSection = {
+    /** Kebab-case tab id, used as the `?tab=` value. Required by the
+     *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
+    readonly id?: string;
+    readonly kind: "relatedList";
+    readonly title: string;
+    /** Fully qualified query QN. Same paged envelope as projectionList.query:
+     *  `{ rows, nextCursor, total? }`. */
+    readonly query: string;
+    /** Query-payload key the parent record's id is passed under. Default "id". */
+    readonly parentParam?: string;
+    /** Server-side WHERE clause pinning this section to the parent record —
+     *  sent as `payload.filter: { field, op: "eq", value: parentId }`, kept
+     *  out of the user-facet `filters` array so it can't be cleared by facet
+     *  interaction. Lets a tab reuse the generic `<entity>:list` query instead
+     *  of a bespoke child-rows handler. Mutually exclusive with `parentParam`
+     *  (the boot-validator rejects both). `field` must be a real field on the
+     *  entity behind `query`, and that query's Zod schema must accept
+     *  `filter` (same requirement `filter`/`facets` already have). */
+    readonly parentFilter?: {
+        readonly field: string;
+    };
+    readonly columns: readonly ListColumnSpec[];
+    /** i18n key for the one-line hint at the left of the tab toolbar. */
+    readonly description?: string;
+    /** i18n key holding plural forms for the footer count ("1 Position",
+     *  "3 Positionen"). Omitted: generic "entries" wording. */
+    readonly itemNoun?: string;
+    readonly pageSize?: number;
+    /** Initial sort on mount, applied client-side over the already-loaded rows
+     *  (this section has no pager, so there is no "loaded subset" to mislead).
+     *  `field` must name a column with `sortable: true` — boot-validator pins
+     *  that, same as `entityList.defaultSort`. */
+    readonly defaultSort?: ListSortSpec;
+    /** Renders a search box whose debounced term rides along as
+     *  `payload.search` on this section's own query. Opt-in, unlike
+     *  `projectionList.searchable` (derived from the bound query's schema): a
+     *  relatedList query is an ordinary child-rows handler, so a `search`
+     *  parameter in its schema is not by itself a statement that this section
+     *  should offer search. The boot-validator rejects `true` when the query's
+     *  Zod schema has no `search` parameter. */
+    readonly searchable?: boolean;
+    /** User-toggleable facet dropdowns — same explicit-label `ListFacetSpec` as
+     *  `projectionList.facets` (a relatedList has no entity to derive filterable
+     *  fields from). `field` must be a declared column and the bound query
+     *  handler must accept `filters` in its Zod schema — the boot-validator
+     *  checks both. Selected values ride along as `payload.filters`. */
+    readonly facets?: readonly ListFacetSpec[];
+    /** Row click opens the target entity's detail screen via ObjectTarget —
+     *  the `detailFor` lookup owns the entity→screen mapping, so no screenId
+     *  is named here. `idColumn` names the row key holding that id (default
+     *  "id"). Omit `rowClick` for a non-interactive list. */
+    readonly rowClick?: {
+        readonly entity: string;
+        readonly idColumn?: string;
+    };
+    /** Per-row actions — same type and dispatch semantics as `entityList`/
+     *  `projectionList`'s `rowActions` (writeHandler dispatch with a
+     *  declarative `payload` extractor, or navigate). A successful
+     *  writeHandler action re-runs this section's own query, same as a
+     *  projectionList row action re-running its list query. */
+    readonly rowActions?: readonly RowAction[];
+    /** Toolbar actions above the table — same type and dispatch semantics as
+     *  `entityList`/`projectionList`'s `toolbarActions` ("+ Anlegen" etc.),
+     *  plus `visible`/`params` evaluated against the parent record (see
+     *  RelatedListToolbarAction). */
+    readonly toolbarActions?: readonly RelatedListToolbarAction[];
+    /** Record field rendered as a count badge in the tab label when the
+     *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+     *  Ignored outside tabs mode or when the field's value is not a finite
+     *  number. */
+    readonly countField?: string;
+    /** Rendered top-right in the section's Card title row — same
+     *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+     *  evaluated against the parent record. Every action must resolve an icon
+     *  (declared or id-derived); the boot-validator rejects one that doesn't.
+     *  Distinct from `toolbarActions` (rendered inside the DataTable toolbar) —
+     *  this is the Card-level title-row action. */
+    readonly actions?: readonly RowAction[];
+    /** Rendered inside the section's Card in place of the table when this
+     *  section's query returns zero rows. Omitted: the DataTable default
+     *  ("kumiko.list.no-entries") applies. `action`'s icon must resolve, same
+     *  as `actions` above. */
+    readonly emptyState?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly action?: RowAction;
+    };
+};
+export type EditWriteFormSection = {
+    /** Kebab-case tab id, used as the `?tab=` value. Required by the
+     *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
+    readonly id?: string;
+    readonly kind: "writeForm";
+    readonly title?: string;
+    readonly description?: string;
+    readonly columns?: number;
+    readonly icon?: IconKey;
+    /** Field-type map for this section's own form — same shape as
+     *  `ActionFormScreenDefinition.fields`. */
+    readonly fieldDefs: Readonly<Record<string, FieldDefinition>>;
+    /** Rendered fields, in order — same shape as `EditFieldsSection.fields`.
+     *  Every referenced field must have an entry in `fieldDefs`. */
+    readonly fields: readonly EditFieldSpec[];
+    /** Write-handler QN dispatched on submit. The submitted values (not a
+     *  diff) land 1:1 as payload, same as `ActionFormScreenDefinition.handler`.
+     *  The payload carries only this section's own fields — no parent/record
+     *  id is injected automatically. To thread the host record's id through,
+     *  declare it in `fieldDefs` with `visible: false` on its `fields` entry:
+     *  it gets prefilled from the loaded record like any other field and rides
+     *  along in the submit payload without being shown in the form. */
+    readonly handler: string;
+    /** i18n-key for the submit button. Default: "kumiko.actions.save". */
+    readonly submitLabel?: string;
+    /** Rendered top-right in the section's Card title row — same
+     *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
+     *  evaluated against the same record. Every action must resolve an icon
+     *  (declared or id-derived); the boot-validator rejects one that doesn't. */
+    readonly actions?: readonly RowAction[];
+};
+export type FormWidth = "3xl" | "4xl" | "full";
+export type EditLayout = {
+    readonly sections: readonly EditSectionSpec[];
+    /** Default "4xl" (a centered column, narrower than list chrome), unless
+     *  the app overrides it via `createKumikoApp({ screenWidth })`. Override
+     *  per-screen to "3xl" for a narrower column or "full" to match list
+     *  chrome. */
+    readonly width?: FormWidth;
+    /** Default "single". "wizard" renders one section per step (with
+     *  progress + per-step validation) instead of all sections at once —
+     *  boot-validator requires >= 2 sections, each with a title, when set.
+     *  "tabs" renders one section per tab (projectionDetail only — the
+     *  boot-validator rejects it on entityEdit, see the check for the reason);
+     *  requires >= 2 sections, each with a title and an `id`. */
+    readonly mode?: "single" | "wizard" | "tabs";
+    /** Persists in-progress wizard state as a resumable draft instead of
+     *  discarding it on navigation away. */
+    readonly draft?: boolean;
+};
+export type EntityEditScreenDefinition = {
+    readonly id: string;
+    readonly type: "entityEdit";
+    /** Default true: the screen fills the shell content height, its body scrolls
+     *  inside and the pager / action bar stays pinned. `false` restores page
+     *  scroll (table grows with its rows, pager below the last row, form footer
+     *  in the flow). */
+    readonly fillHeight?: boolean;
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    /** Derived by buildAppSchema from the navigate `params` targeting this
+     *  screen — the only URL query keys the create form prefills. An authored
+     *  value is overwritten. */
+    readonly urlPrefillFields?: readonly string[];
+    readonly entity: string;
+    readonly layout: EditLayout;
+    /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
+     *  `kumiko.actions.save`. Lässt den Auto-Edit-Screen domain-spezifische
+     *  CTAs zeigen ("Save Address", "Create item") statt generisch "Speichern". */
+    readonly submitLabel?: string;
+    /** Default true. `false` für Entities deren Create über einen eigenen
+     *  Lifecycle-Write läuft (z.B. incident:open mit Event-Stream + Joins)
+     *  statt über `<entity>:create`: unterdrückt den automatischen
+     *  „+ Neu"-Button auf entityList-Screens dieser Entity und rendert den
+     *  Create-Branch (Aufruf ohne entityId) als Fehler statt eines Forms,
+     *  dessen Submit gegen einen nicht registrierten Handler liefe. */
+    readonly allowCreate?: boolean;
+    /** Default true. `false` wenn kein `<entity>:delete`-Handler existiert
+     *  (History-/Audit-Erhalt): unterdrückt den Löschen-Button im
+     *  Update-Form. */
+    readonly allowDelete?: boolean;
+    /** Default false. `true` for singleton entities (exactly one record per
+     *  tenant: organization, settings, tenant profile). A call without an
+     *  `entityId` first resolves the existing record via `<entity>:list`
+     *  (limit 1) and renders the update branch with prefill on a hit,
+     *  instead of blindly creating another one. The create branch only
+     *  fires when the table is empty (and `allowCreate: false` still
+     *  applies there). */
+    readonly singleton?: boolean;
+    /** Navigate to this screen ID after a successful save (create or update).
+     *  Either a same-feature short screen-ID, or a fully-qualified
+     *  cross-feature screen QN (`<feature>:screen:<id>`) — the nav-router
+     *  resolves both against the schema; boot-validator checks the target
+     *  resolves to a registered screen. Overrides the default post-save
+     *  target (the entity's list screen); delete is unaffected and still
+     *  always navigates to the list. A cross-feature QN hard-couples this
+     *  feature to the target at boot time — an app that doesn't mount the
+     *  target feature fails the boot-validator; only use this form in a
+     *  reusable feature when the target feature is guaranteed to be
+     *  mounted alongside it.
+     *
+     *  The object form additionally names the success-payload field the
+     *  navigation id comes from (`ActionFormRedirect.idFrom`) — needed when
+     *  the edited record is a child and the target screen is the parent's
+     *  detail screen. Update falls back to the loaded record when the
+     *  success payload doesn't carry that field flatly; create falls back
+     *  to the submitted form values. */
+    readonly redirect?: string | ActionFormRedirect;
+    /** Parent list screen (short id) for breadcrumb + nav highlighting when
+     *  this screen has no nav entry of its own. Same field/semantics as on
+     *  `custom`/`projectionDetail`; an explicit value here wins over the
+     *  entity-list heuristic (rowAction target / same-entity entityList). */
+    readonly listScreenId?: string;
+    /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key), überschreibt
+     *  die Default-Konvention `<feature>:entity:<entity>:field:<name>`.
+     *  Primär für configEdit: dessen Pseudo-Entity `__config-edit__` hat
+     *  keinen natürlichen Field-Namespace — der Settings-Hub injiziert hier
+     *  das `mask.title`-Label des Config-Keys. Fehlt ein Eintrag, gilt die
+     *  Konvention. */
+    readonly fieldLabels?: Readonly<Record<string, string>>;
+    /** Header action buttons. Reuses `RowAction` — analogous to
+     *  `ProjectionDetailScreenDefinition.actions` (the loaded record stands
+     *  in for the "row"). `rowClick` has no target here and is rejected by
+     *  the boot-validator, same as on projectionDetail. Not rendered in
+     *  create mode — every action targets an existing record, which the
+     *  create branch doesn't have yet. */
+    readonly actions?: readonly RowAction[];
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+export type ActionFormScreenDefinition = {
+    readonly id: string;
+    readonly type: "actionForm";
+    /** Default true: the screen fills the shell content height, its body scrolls
+     *  inside and the pager / action bar stays pinned. `false` restores page
+     *  scroll (table grows with its rows, pager below the last row, form footer
+     *  in the flow). */
+    readonly fillHeight?: boolean;
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
+    readonly urlPrefillFields?: readonly string[];
+    /** Write-Handler-QN der bei Submit gerufen wird. Form-Object landet
+     *  1:1 als payload — Handler-Schema (Zod) validiert weiter. */
+    readonly handler: string;
+    /** Form-Shape: Field-Map pro Name. Nutzt dieselben FieldDefinitions
+     *  wie Entity-Felder. Mindestens ein Feld erforderlich (Boot-
+     *  Validator).
+     *
+     *  A `money` field here must name its own currency source: this screen
+     *  has no entity whose `defaultCurrency` it could inherit (fw#2839). */
+    readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    /** Layout analog zu EntityEditScreen: sections mit fields aus dem
+     *  fields-Map oben. */
+    readonly layout: EditLayout;
+    /** Per-field label i18n key override, same type/semantics as
+     *  `EntityEditScreenDefinition.fieldLabels`. Falls back to the convention when absent. */
+    readonly fieldLabels?: Readonly<Record<string, string>>;
+    /** i18n-key für den Submit-Button. Default: i18n-Default des
+     *  Renderers (typischerweise "actions.submit"). */
+    readonly submitLabel?: string;
+    /** Context box above the fields (i18n keys). `{name}` placeholders resolve from the
+     *  drawer prefill (`params` of the opening row action), formatted for display. */
+    readonly summary?: {
+        readonly title: string;
+        readonly subtitle?: string;
+    };
+    /** Visual style of the submit button. "danger" renders it red — for a form
+     *  whose handler is destructive (terminate, revoke, delete), so the warning
+     *  isn't lost on the way from the calling screen to this one. Default "primary". */
+    readonly submitStyle?: "primary" | "danger";
+    /** Navigate to this screen ID after a successful submit: either a short
+     *  ID (e.g. "item-list" — same feature, the nav-router resolves to the
+     *  full path) or a fully-qualified cross-feature QN
+     *  (`<feature>:screen:<id>`). If not set, the user stays on the form
+     *  screen. Boot-validator checks that the target resolves to a
+     *  registered screen. A cross-feature QN hard-couples this feature to
+     *  the target at boot time — an app that doesn't mount the target
+     *  feature fails the boot-validator; only use this form in a reusable
+     *  feature when the target feature is guaranteed to be mounted
+     *  alongside it.
+     *
+     *  The object form additionally names the success-payload field the
+     *  navigation id comes from (`ActionFormRedirect.idFrom`) — needed when
+     *  the handler creates a child record but the target screen is the
+     *  parent's detail screen (fw#2670). */
+    readonly redirect?: string | ActionFormRedirect;
+    /** Target of the Cancel button. Default: `redirect` (historical
+     *  behavior — Cancel and the submit-redirect then land in the same
+     *  place). `false` = no Cancel button; correct for single-action
+     *  screens with no discardable state (e.g. "Send test mail"), where
+     *  Cancel would just be a second path to the same target. Accepts the
+     *  same string targets as `redirect` (short ID or cross-feature QN);
+     *  boot-validator checks it. A cross-feature QN hard-couples this
+     *  feature to the target at boot time — an app that doesn't mount the
+     *  target feature fails the boot-validator; only use this form in a
+     *  reusable feature when the target feature is guaranteed to be
+     *  mounted alongside it. */
+    readonly cancelTarget?: string | false;
+    /** Parent list screen (short id) for breadcrumb + nav highlighting when
+     *  this screen has no nav entry of its own. Same field/semantics as on
+     *  `custom`/`projectionDetail`/`entityEdit`; an explicit value here wins
+     *  over the rowAction heuristic. */
+    readonly listScreenId?: string;
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+/** Redirect target plus the success-payload field carrying the navigation
+ *  id. The write-handler reports the id of what it wrote (`data.id`); when
+ *  that record is a child and the target screen shows its parent, the
+ *  parent id has to be read from a different field instead of forcing the
+ *  handler to misreport its own result (fw#2670). */
+export type ActionFormRedirect = {
+    /** Same target forms as the string `redirect`: short screen ID
+     *  (same-feature) or a fully-qualified cross-feature screen QN. */
+    readonly screen: string;
+    /** Flat field name in the handler's success payload, e.g. "leaseId".
+     *  Only used when the target screen type carries an id (`entityEdit`,
+     *  `projectionDetail`); a non-string or missing value navigates without
+     *  an id, same as a payload without `id` does today. */
+    readonly idFrom: string;
+};
+/** Author-declared field shown once after a mint-form submit — API token,
+ *  recovery codes, similar one-time secrets. */
+export type SecretRevealField = {
+    /** Flat field name in the handler's success payload. */
+    readonly field: string;
+    /** i18n key for this value's label. */
+    readonly label: string;
+    /** "code" (default) renders one monospaced value; "list" renders a
+     *  string-array payload one value per line (recovery codes); "qr" renders
+     *  the value as a scannable QR code (otpauth://-style enrollment URI) —
+     *  platforms without a QR-capable SecretReveal primitive fall back to the
+     *  monospaced text display. */
+    readonly display?: "code" | "list" | "qr";
+    /** Default true — offer a copy-to-clipboard control next to the value. */
+    readonly copyable?: boolean;
+};
+/** Post-reveal proof-of-receipt step. A mint whose effect is only armed once
+ *  the user proves they received the secret (TOTP enrollment: scan the code,
+ *  then enter one) declares it here — the reveal card renders this form in
+ *  place of the bare acknowledge button. */
+export type SecretMintConfirmStep = {
+    /** Write-handler QN dispatched when the confirm form is submitted. */
+    readonly handler: string;
+    readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    readonly layout: EditLayout;
+    /** Mint success-payload fields merged into the confirm payload (e.g. a
+     *  short-lived setup token). Held in component state only — never rendered,
+     *  never in the URL, a query cache, nav or a persisted draft. */
+    readonly carry?: readonly string[];
+    readonly submitLabel?: string;
+    /** i18n key for the banner shown after a successful confirm when the screen
+     *  declares no `redirect`. Default "kumiko.secretMint.done". */
+    readonly doneMessage?: string;
+};
+export type SecretReveal = {
+    readonly fields: readonly SecretRevealField[];
+    /** i18n key. Default "kumiko.secretMint.title". */
+    readonly title?: string;
+    /** i18n key for the "this is the only time you see it" warning.
+     *  Default "kumiko.secretMint.warning". */
+    readonly warning?: string;
+    /** i18n key for the acknowledge button. Default "kumiko.secretMint.confirm". */
+    readonly confirmLabel?: string;
+};
+/** Mint form → one-time reveal → explicit confirm. The secret (API token,
+ *  recovery codes) lives only in the write-handler's own success payload —
+ *  no stored value backs it, so no query can redisplay it later. That gap
+ *  is why this needs its own screen type instead of a flag on `actionForm`,
+ *  which discards the success payload after extracting the navigation id. */
+export type SecretMintScreenDefinition = {
+    readonly id: string;
+    readonly type: "secretMint";
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
+    readonly urlPrefillFields?: readonly string[];
+    /** Write-handler QN dispatched on submit. */
+    readonly handler: string;
+    readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    readonly layout: EditLayout;
+    /** Navigate here after the reveal is confirmed. Short id (same-feature) or
+     *  a fully-qualified cross-feature screen QN — no result-id navigation
+     *  form exists here (unlike `ActionFormScreenDefinition.redirect`), since
+     *  the confirmed screen carries no entity id to thread through. */
+    readonly redirect?: string;
+    readonly cancelTarget?: string | false;
+    readonly listScreenId?: string;
+    readonly access?: AccessRule;
+    readonly reveal: SecretReveal;
+    /** i18n-key for the mint button. Default: renderer's own default. */
+    readonly submitLabel?: string;
+    /** Proof-of-receipt step rendered on the reveal card in place of the bare
+     *  acknowledge button — see `SecretMintConfirmStep` doc. */
+    readonly confirm?: SecretMintConfirmStep;
+};
+export type CustomScreenRoute = {
+    readonly path: string;
+    readonly component: PlatformComponent;
+};
+export type CustomScreenDefinition = {
+    readonly id: string;
+    readonly type: "custom";
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    /** Only `expose` is read for screens; `risk` ranks handler tool calls. */
+    readonly agent?: AgentHandlerHints;
+    readonly renderer: PlatformComponent;
+    readonly routes?: readonly CustomScreenRoute[];
+    /** Parent list screen for breadcrumb when this detail is not in nav. */
+    readonly listScreenId?: string;
+    readonly access?: AccessRule;
+    /** This screen is registered without a self-owned `r.nav()` entry by
+     *  design — an app opts in by navving it explicitly (e.g. a settings-area
+     *  self-service screen). `createKumikoApp`'s boot diagnostic
+     *  (kumiko-framework#2025) skips dormant screens instead of flagging
+     *  every consumer that doesn't mount the client plugin as a false
+     *  positive (kumiko-framework#2034). Only set this on screens the
+     *  feature itself never navs — a screen the feature DOES nav still needs
+     *  its client plugin mounted by every consumer, and should keep
+     *  triggering the diagnostic if it's missing. Also gates the
+     *  boot-validator's nav-area check, same as `dormant` on other screens. */
+    readonly dormant?: boolean;
+};
+export type ConfigEditScreenDefinition = {
+    readonly id: string;
+    readonly type: "configEdit";
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    /** scope für config:write:set Calls. Muss zur Scope-Deklaration der
+     *  in `configKeys` referenzierten Keys passen — Boot-Validator
+     *  prüft das gegen die Registry. */
+    readonly scope: "tenant" | "system" | "user";
+    /** Map: form-field-name (kurz, wie im Layout referenziert) → voll-
+     *  qualifizierter Config-Key (`<feature>:config:<short>`). Boot-
+     *  Validator prüft dass jeder qualifizierte Key in der Registry
+     *  bekannt ist. */
+    readonly configKeys: Readonly<Record<string, string>>;
+    /** Form-Shape pro Field-Name. Selbe FieldDefinitions wie auf
+     *  Entities/ActionForm. Field-Names matchen die Keys in `configKeys`
+     *  — Boot-Validator pinnt das. */
+    readonly fields: Readonly<Record<string, FieldDefinition>>;
+    /** Layout: Sections mit Field-Refs. Identisch zu entityEdit/
+     *  actionForm. */
+    readonly layout: EditLayout;
+    /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key). Der
+     *  Settings-Hub setzt hier `mask.title` des jeweiligen Config-Keys,
+     *  damit das am Key deklarierte Label am generierten Feld erscheint —
+     *  ohne es unter der `__config-edit__`-Konvention zu duplizieren.
+     *  Fehlt ein Eintrag, gilt die Konvention. */
+    readonly fieldLabels?: Readonly<Record<string, string>>;
+    /** i18n-key für den Submit-Button. Default: "kumiko.actions.save". */
+    readonly submitLabel?: string;
+    readonly slots?: ScreenSlots;
+    readonly access?: AccessRule;
+};
+export type SecretsEditSection = {
+    readonly title?: string;
+    readonly fields: readonly string[];
+};
+export type SecretsEditScreenDefinition = {
+    readonly id: string;
+    readonly type: "secretsEdit";
+    readonly nav?: ScreenNavSugar;
+    readonly detailFor?: string;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** Screen has no nav entry by design (opened via link or navved by the
+     *  app); exempts it from the nav-area boot check. */
+    readonly dormant?: boolean;
+    /** field id -> qualified secret name (`<feature>:secret:<kebab>`). */
+    readonly secretKeys: Readonly<Record<string, string>>;
+    /** field id -> i18n key for the label. */
+    readonly fieldLabels: Readonly<Record<string, string>>;
+    /** field id -> i18n key for the hint, only where the declaration carries one. */
+    readonly fieldHints?: Readonly<Record<string, string>>;
+    /** field ids whose declaration set `required: true`. */
+    readonly requiredFields?: readonly string[];
+    readonly sections: readonly SecretsEditSection[];
+    readonly access?: AccessRule;
+};
+export type ScreenSlots = {
+    readonly header?: PlatformComponent;
+    /** entityEdit / actionForm: rendered on the right of the form title, same row. */
+    readonly titleAction?: PlatformComponent;
+    readonly beforeForm?: PlatformComponent;
+    readonly afterForm?: PlatformComponent;
+    readonly sidebar?: PlatformComponent;
+    readonly footer?: PlatformComponent;
+    /** entityEdit wizard: marks `footer` as the sticky-footer primary action
+     *  (fw#1918's pinned `max-sm:fixed` group on mobile) instead of the
+     *  non-sticky secondary bucket it falls into by default alongside
+     *  Back/Cancel. Set this when `footer` renders the screen's actual
+     *  submit-type action (e.g. a custom "Publish" button standing in for, or
+     *  beside, the built-in Finish/Save) — the renderer can't infer that from
+     *  the slot's arbitrary rendered output, only from this declaration. */
+    readonly footerPrimary?: boolean;
+    readonly toolbar?: PlatformComponent;
+};
+export type ScreenNavSugar = {
+    readonly label: string;
+    readonly icon?: NavIconKey;
+    readonly parent?: string;
+    readonly order?: number;
+};
+export type ScreenDefinition = EntityListScreenDefinition | ProjectionListScreenDefinition | ProjectionDetailScreenDefinition | DashboardScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretsEditScreenDefinition | SecretMintScreenDefinition | CustomScreenDefinition;