@cosmicdrift/kumiko-types 0.327.0 → 0.328.1

package/src/screen.ts

@@ -1,1593 +0,0 @@
-import type { FieldIconKey } from "./field-icon";
-import type { FieldDefinition, FormFieldDefinition } from "./fields";
-import type { AccessRule, AgentHandlerHints } from "./handlers";
-import type { IconKey, NavIconKey } from "./nav-icon";
-
-export type { FieldIconKey } from "./field-icon";
-
-// Screen definitions describe how a feature surfaces data to the user.
-// Pure data — the engine stores these verbatim and ui-core / the renderer
-// packages decide what to do with them. The framework must not import
-// React / react-native from here; renderer components stay opaque so
-// `engine/` imports don't pull the whole UI toolchain into every bundle.
-//
-// Note on `id`: feature authors write the short form ("product-list"); the
-// registry overwrites `id` with the qualified name ("shop:screen:product-list")
-// in its stored copies. Callers of `registry.getScreen(qn)` /
-// `getAllScreens()` / `getScreensByEntity(...)` always see the qualified id.
-// `feature.screens[shortId]` on the unregistered FeatureDefinition keeps
-// the short form.
-
-// A per-platform component pair — used anywhere a feature attaches a
-// rendered component (screens, slots, routes, field renderers, future
-// r.uiComponent). Both fields are `unknown` so the engine doesn't depend
-// on React types; ui-core resolves the correct platform at mount-time.
-// Framework code only checks structural presence.
-export type PlatformComponent = {
-  readonly react?: unknown;
-  readonly native?: unknown;
-};
-
-// Closed set of unit identifiers for `{ format: "unit" }` (no bare `string`
-// per house convention). "m2" has no ECMA-402 sanctioned unit — Intl throws
-// RangeError for "square-meter" — so kumiko-headless's applyFormatSpec
-// formats it as a locale-formatted number with a literal "m²" suffix. The
-// rest map to a CLDR-sanctioned Intl.NumberFormat unit id and get
-// locale-correct pluralization/spacing straight from Intl.
-export type UnitKey = "m2" | "km" | "m" | "kg" | "percent" | "mi";
-
-// Built-in value formatters. Apps extend via module augmentation:
-//   declare module "@cosmicdrift/kumiko-framework/engine/types" {
-//     interface FieldFormatRegistry { myFormat: { myOption?: string } }
-//   }
-// renderer-web handles all built-in keys; unknown app-specific keys fall back
-// to String(value).
-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 };
-  // Value is percent *points* (12 → "12 %"), not a 0..1 ratio — Intl
-  // style:"unit"/unit:"percent" does NOT multiply by 100 (unlike style:"percent").
-  unit: {
-    readonly unit: UnitKey;
-    readonly locale?: string;
-    readonly unitDisplay?: "long" | "short" | "narrow";
-  };
-  // Resolves an enum value through the i18n convention
-  // `<feature>:entity:<entity>:field:<field>:option:<value>` — same
-  // fallback-to-raw-value rule as buildOptionLabels: an untranslated key
-  // renders the raw enum value instead of the literal i18n key.
-  // Prefer fieldOptionLabelKeyPrefix() from @cosmicdrift/kumiko-headless
-  // over hand-typed prefix strings.
-  enumOption: { readonly keyPrefix: string };
-  /** JSON-safe structured value rendered as indented text. */
-  json: { readonly indent?: number };
-}
-
-// Discriminated union derived from the registry — one variant per key.
-// JSON-safe: no function members, survives buildAppSchema → GET /api/schema.
-export type FormatSpec = {
-  [K in keyof FieldFormatRegistry]: { readonly format: K } & FieldFormatRegistry[K];
-}[keyof FieldFormatRegistry];
-
-// Level-2 field renderer (ui-architecture.md §Renderer Customization):
-//   - PlatformComponent → platform-specific component from the same feature
-//   - string            → cross-feature QN reference (resolved at mount-time)
-//   - FormatSpec        → declarative value formatter, JSON-safe ({ format: "timestamp" } etc.)
-export type FieldRenderer = PlatformComponent | string | FormatSpec;
-
-// Declarative field-state condition. Evaluated by the renderer against the
-// current row/form values. Five forms:
-//   boolean          — static on/off (e.g. readOnly: true)
-//   { field, eq }    — true when row[field] === eq
-//   { field, ne }    — true when row[field] !== ne
-//   { field, in }    — true when row[field] is one of the given values
-//   { field, notIn } — true when row[field] is none of the given values
-// JSON-safe: survives buildAppSchema → GET /api/schema stringify.
-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[] };
-
-// --- entityList ---
-
-// `string` shorthand when the column only needs its field name; the object
-// form carries renderer / display overrides. normalizeListColumn() below
-// collapses both into the object form for downstream consumers.
-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;
-    };
-
-// Pagination-Modi für entityList:
-//   - "pages":     klassischer Pager (← 1 2 ... N →) — bookmarkable
-//                  via ?page=N in der URL. Server liefert `total`
-//                  damit der Pager "Page X of Y" rendern kann.
-//                  Default für CRUD-/Admin-Listen.
-//   - "infinite":  IntersectionObserver am Bottom — beim Sichtbar
-//                  werden lädt cursor-basiert die nächste Page und
-//                  appended an `rows`. Kein page-State in URL (Scroll-
-//                  Position ist Browser-eigen).
-//   - false:       Pagination aus — `executor.list()` lädt alles
-//                  was zur Tenant-Sicht passt. Sinnvoll für kleine
-//                  Lookup-/Master-Daten (≤ ~200 Rows).
-export type ListPaginationMode = "pages" | "infinite" | false;
-
-// Sort-State auf der Wire — Field-Name muss zur Entity-Definition
-// passen UND als sortable: true markiert sein. Validator lehnt sonst
-// beim Boot ab.
-export type ListSortDir = "asc" | "desc";
-export type ListSortSpec = {
-  readonly field: string;
-  readonly dir: ListSortDir;
-};
-
-// Screen-Level Filter — Author deklariert pro List-Screen einen festen
-// Filter der bei jedem Query angewendet wird. Use-case: drei Buckets
-// derselben Entity ("Upcoming Maintenance" / "Active Maintenance" /
-// "Past Maintenance") ohne drei Custom-Pages — Filter pro Screen
-// unterscheidet sie.
-//
-// Operatoren (Drizzle-konsistent):
-//   eq/ne     → field = value | field != value
-//   lt/gt     → field < value | field > value (numerisch / temporal)
-//   lte/gte   → field <= value | field >= value (numerisch / temporal)
-//   in        → field IN (...values), value muss readonly array sein
-//
-// Field muss in der Entity existieren UND `filterable: true` haben
-// (Boot-Validator pinned beides). `lt`/`gt`/`lte`/`gte` nur auf
-// vergleichbaren Field-Types (number/money/date/timestamp/
-// locatedTimestamp); auf text/boolean/select/multiSelect lehnt der
-// Validator das ab.
-//
-// Security-Modell: Filter ist UX-Bucketing, KEINE Access-Boundary. Der
-// Server appliziert den filter aus dem Payload — der Client kann ihn
-// weglassen oder durch einen anderen ersetzen. Boundary bleiben
-// access-rule + Tenant-Scope; Felder mit Sicherheits-Bias (encrypted,
-// restricted) müssen dort geschützt werden, nicht über den Screen-Filter.
-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>> };
-
-// RowAction — per-Row Button/Dropdown-Item das einen Write-Handler
-// triggert oder zu einem anderen Screen navigiert.
-//
-// Pattern: row-level Lifecycle-Operations (Maintenance start/cancel/
-// complete, Incident resolve, Order ship etc.) — Sachen die in einem
-// CRUD-update kein passendes Verb haben aber als WriteHandler existieren.
-//
-// Discriminated Union mit `kind`:
-//   - "writeHandler" (default): dispatched einen Write-Handler mit
-//     Payload pro Row.
-//   - "navigate" (Tier 2.7e): navigiert zu einem anderen Screen,
-//     optional mit URL-Search-Params aus `params`. Use-case: "Edit",
-//     "View Audit-Log", "Open in actionForm" etc.
-//   - "drawer" (fw#2710): mounts an actionForm in a Drawer without leaving
-//     the list/detail screen, prefilled from the clicked row via `params`.
-//     Row-level pendant to ToolbarAction's "drawer" variant (fw#2225).
-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;
-};
-
-// ToolbarAction — button in the list header. Three variants: navigate to
-// another screen (e.g. a full-page actionForm), dispatch a handler directly
-// (e.g. "Sync All" without a form), or mount an actionForm in a Drawer
-// without leaving the list (fw#2225).
-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";
-    };
-
-// relatedList-only extension of ToolbarAction:
-// a relatedList section's toolbar renders inside a projectionDetail, which
-// has a record to evaluate against — a plain entityList/projectionList
-// toolbar does not, so `visible`/`params` live here instead of on the base
-// union. `visible` uses the same FieldCondition as header actions/
-// RowAction; `params` reuses RowActionNavigate's RowFieldExtractor, applied
-// to the enclosing record instead of a clicked row. Every field is optional,
-// so a plain ToolbarAction is already a valid RelatedListToolbarAction —
-// callers pass either type without a cast.
-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";
-  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[];
-  // Row renderer (Desktop) — when omitted, renderer draws the default table
-  // from `columns`. cardRenderer fills the same role on compact layouts.
-  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;
-  // Pagination-Modus (Default "pages"). Bestimmt UI (Pager vs Scroll-
-  // Sentinel) und ob der Server `total` mitliefern muss.
-  readonly pagination?: ListPaginationMode;
-  // Page-Größe. Default 50 — guter Kompromiss zwischen "viel sichtbar"
-  // und "DB liefert schnell". Apps mit teurem Read (Joins, Computed-
-  // Fields) gehen runter; Power-User-Listen (z.B. internal Analytics)
-  // gehen hoch.
-  readonly pageSize?: number;
-  // Default-Sortierung beim Erst-Mount. Wenn URL-Param `?sort=…`
-  // gesetzt ist, gewinnt der; sonst nutzt RenderList diesen Default.
-  // `field` muss in der Entity sortable: true sein — Boot-Validator
-  // pinnt das.
-  readonly defaultSort?: ListSortSpec;
-  // Search-Toolbar im UI an/aus. Server-Search geht IMMER über den
-  // SearchAdapter (Meilisearch) — kein DB-ILIKE-Drift. Default true
-  // wenn die Entity searchable Felder hat, sonst false.
-  readonly searchable?: boolean;
-  readonly slots?: ScreenSlots;
-  readonly access?: AccessRule;
-};
-
-// --- projectionList ---
-
-// Like entityList, but bound to an EXPLICIT query instead of an entity. The
-// list-query is taken verbatim from `query` (a fully qualified QN like
-// "ledger:query:schedule:list") — NOT derived from the screen's own feature —
-// so a screen can render any read-projection, including one owned by a
-// different feature (the entityList feature-local resolution can't). Columns
-// carry their own labels (no entity to derive field-labels from); there is no
-// auto create-navigation (a projection isn't an editable entity list). Row
-// interaction is explicit via `rowActions`. The query must return the same
-// paged envelope as an entity list-query: `{ rows, nextCursor, total? }`.
-// User-toggleable facet dropdown on a projectionList screen (fw#2224).
-// entityList derives the same UI from `filterable: true` entity fields plus
-// the `<feature>:entity:<entity>:field:<field>:option:<value>` i18n
-// convention. Labels here (`label`, `options[].label`, `trueLabel`/
-// `falseLabel`) are i18n keys resolved via `translate()` with passthrough
-// for unknown keys (fw#2373) — not raw display strings. Sent to the server
-// as `{field, op:"in", value}` in `payload.filters`, ANDed with `filter`.
-// Exception: "dateRange" sends its bounds as the two top-level payload keys
-// named in `params`, not as a `filters` entry.
-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";
-  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;
-  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;
-};
-
-// --- projectionDetail ---
-
-// Read-only counterpart to projectionList — a single-row inspector bound to
-// an EXPLICIT query instead of an entity (`entityEdit` requires `r.entity`,
-// which a direct-write/projection read-model like `jobs`/`sessions` doesn't
-// have — see #255). There is no write path: the renderer forces every field
-// readOnly structurally (not just by convention — see
-// renderer/projection-detail-shim.ts), so no `<entity>:write:...:update`
-// command is ever constructed. `idParam` names the query-payload key the
-// route's row-id is passed under; defaults to "id", but a query handler
-// owned by a different feature may already use a domain-specific param name
-// (e.g. jobs' `detailQuery` expects `runId`) — this lets the primitive bind
-// to it without forcing a handler rename. Extension sections aren't
-// supported (no entity for them to persist against); the boot-validator
-// rejects them. `relatedList` sections ARE supported — they run their own
-// query against the displayed record's id, independent of the entity gap
-// above (fw#2166).
-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;
-};
-
-// Same shape as `RowActionNavigate`'s screen/entity choice, minus the fields
-// a metric click has no use for (id, confirm, style).
-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;
-};
-
-// A metric can navigate on click, so the plain string shorthand (field name,
-// same as before) sits alongside an object form carrying an explicit i18n
-// `label` and a `navigate` target.
-export type MetricSpec =
-  | string
-  | {
-      readonly field: string;
-      readonly label?: string;
-      readonly navigate?: MetricNavigate;
-    };
-
-export function metricField(metric: MetricSpec): string {
-  return typeof metric === "string" ? metric : metric.field;
-}
-
-export type ProjectionDetailScreenDefinition = {
-  readonly id: string;
-  readonly type: "projectionDetail";
-  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";
-};
-
-// --- dashboard ---
-
-// Deklaratives Panel-Grid — Kennzahlen, Verläufe und Kurzlisten ohne
-// Custom-JSX. Jedes Panel zieht seine Daten aus einer eigenen Query
-// (fully-qualified QN, cross-feature erlaubt wie projectionList).
-// Formatierung ist Sache des Query-Handlers: Stat-Werte kommen als
-// anzeigefertige Strings/Zahlen aus der Read-Projection (ES-Read-Models
-// shapen ihre Daten selbst; der Renderer formatiert nicht nach).
-
-// Query-Result-Contract: flaches Record; `valueField` zeigt auf den
-// anzeigefertigen Wert, `subField` optional auf eine Sub-Zeile,
-// `toneField` optional auf "default" | "positive" | "warn".
-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;
-};
-
-// Query-Result-Contract: `{ points: { atMs, value | null }[],
-// windowStartMs, windowEndMs }` — value=null zeichnet einen Einbruch.
-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;
-};
-
-// Kurzliste im Dashboard — Query-Contract wie projectionList
-// (`{ rows, nextCursor, total? }`), gerendert ohne Pager/Toolbar.
-export type DashboardListPanel = {
-  readonly kind: "list";
-  readonly id: string;
-  readonly label: string;
-  readonly query: string;
-  readonly columns: readonly ListColumnSpec[];
-};
-
-// Betitelte Sektion aus mehreren Stat-Panels (z.B. "Net Worth": Assets/Debts/
-// Net). Ein Nesting-Level, kein Group-of-Groups — jedes Kind bleibt ein
-// vollwertiges DashboardStatPanel mit eigener Query/id/label, der Renderer
-// zieht sie nur gemeinsam unter einen Sektions-Titel.
-export type DashboardStatGroupPanel = {
-  readonly kind: "stat-group";
-  readonly id: string;
-  readonly label: string;
-  readonly stats: readonly DashboardStatPanel[];
-};
-
-// Nicht-tabellarische Kurzliste (z.B. "nächste Termine"). Query-Result-
-// Contract: `{ rows: { primary: string; trailing?: string }[] }`.
-export type DashboardFeedPanel = {
-  readonly kind: "feed";
-  readonly id: string;
-  readonly label: string;
-  readonly query: string;
-  readonly emptyLabel?: string;
-};
-
-// Liste aus Label/Wert/Fortschrittsbalken (z.B. Tilgungsfortschritt pro
-// Kredit). Query-Result-Contract: `{ rows: { label: string; value: string;
-// fraction: number }[] }` — fraction wird auf 0..1 geclampt.
-export type DashboardProgressListPanel = {
-  readonly kind: "progress-list";
-  readonly id: string;
-  readonly label: string;
-  readonly query: string;
-};
-
-// Eingehängte App-Komponente, die ihre Daten/Titel selbst verwaltet (wie ein
-// custom Screen, nur als Panel — bleibt an ihrer Array-Position statt in
-// einen separaten Slot zu wandern). Kein `query`, keine `label`: der Renderer
-// löst `component` über dieselbe extensionSectionComponents-Registry auf wie
-// entityEdit-Extension-Sections und List-Header-Slots.
-export type DashboardCustomPanel = {
-  readonly kind: "custom";
-  readonly id: string;
-  readonly component: PlatformComponent;
-};
-
-// Live query, so a write that flips `field` swaps panels without reload; hidden while loading.
-export type DashboardPanelVisibility = {
-  readonly query: string;
-  readonly field: string;
-  readonly eq: string | number | boolean | null;
-};
-
-// Embedded redirect/cancelTarget navigate away from the dashboard — targets meant for tiles omit both.
-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;
-
-// Screen-weiter Picker (Combobox), dessen gewählter Wert unter `id` in JEDE
-// Panel-Query dieses Screens gemerged wird (Query-Handler validieren den Wert
-// selbst gegen die Tenant-Sicht — dies ist UX-Scoping, keine Access-Boundary).
-// Genau eins von `options`/`optionsQuery` ist gesetzt (Boot-Validator prüft).
-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;
-};
-
-// --- entityEdit ---
-
-// camelCase `readOnly` instead of the spec's lowercase `readonly`: TS's
-// `readonly` modifier on the same line would make the declaration read
-// `readonly readonly?: FieldCondition`, which is legal but a real lese-knick.
-// Mirrors React's `readOnly` prop so the ergonomic cost of the divergence
-// from ui-architecture.md is minimal.
-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;
-    };
-
-// A section is a normal field-grid (default — `kind` omitted keeps every
-// existing screen-def working), an extension slot that mounts a feature-
-// provided component, or a related-list of other records. The extension
-// component is resolved client-side by name (same `__component` marker as
-// custom screens / column renderers) and receives the host entity name +
-// id, so a bundled feature (e.g. custom-fields) can load and persist its
-// own data inside the form. `relatedList` runs its own query instead —
-// see `EditRelatedListSection`.
-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[];
-};
-
-// Read-only list of related records, driven by its own query — for a
-// projectionDetail screen showing e.g. a tenant's payments below the
-// tenant's own fields. Only supported on projectionDetail (fw#2166); the
-// boot-validator rejects it on entityEdit/configEdit/actionForm.
-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[];
-  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;
-  };
-};
-
-// A declarative, self-persisting form section for `projectionDetail`
-// (fw editable-detail-screens). Unlike the plain `fields` section — which
-// projectionDetail forces read-only, see the type's own doc — this section's
-// fields ARE editable and submit through their own write-handler, entirely
-// independent of the (nonexistent) outer form submit. Modeled on
-// `ActionFormScreenDefinition`: `fieldDefs` carries the field-type map (a
-// projectionDetail's synthesized display entity has no real field types to
-// draw on), `fields` the rendered order/overrides, same as
-// `EditFieldsSection.fields`. Only supported on projectionDetail — the
-// boot-validator rejects it on entityEdit/configEdit/actionForm, same as
-// `relatedList`.
-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[];
-};
-
-// Max width of the form container (see FormScreenShell in renderer-web).
-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";
-  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;
-};
-
-// --- actionForm ---
-
-// Form-Screen für non-CRUD Write-Handler. Wird gerendert wie ein
-// EntityEditScreen (sections + fields), aber:
-//   - kein detail-fetch beim Mount (initial-state = field-defaults)
-//   - kein CRUD-verb-mapping ("create"/"update") — Author gibt
-//     explizit die Write-Handler-QN an
-//   - Form-Object landet 1:1 als payload beim Handler; sein Zod-Schema
-//     validiert weiter
-//   - optional `redirect` zu einem anderen Screen nach Submit-Success
-//
-// Beispiele: "Send invitation" (mit recipient-email + role), "Approve
-// invoice" (mit notes), "Bulk-import" (mit CSV-string + mode).
-//
-// Field-Shape: inline am Screen statt entity-Reference. Author hat
-// explizite Kontrolle was die Form rendert ohne eine ganze Entity
-// dafür anzulegen. Die FieldDefinitions sind dieselben wie auf
-// Entities (text/select/number/...) — alle DefaultInput-Renderer
-// greifen unverändert.
-export type ActionFormScreenDefinition = {
-  readonly id: string;
-  readonly type: "actionForm";
-  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;
-  /** 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;
-};
-
-// --- custom ---
-
-// Sub-route declared by a custom screen (Expo Router / URL-routing use).
-// `path` is the route-segment appended to the screen's own path; the
-// framework owns the outer routing. Components stay opaque.
-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;
-};
-
-// --- configEdit ---
-
-// Form-Screen der Tenant-/User-/System-Settings aus dem bundled
-// config-Feature liest und schreibt. Wird gerendert wie ein
-// EntityEditScreen (sections + fields), aber:
-//   - Detail-Load via `config:query:values` (statt `<entity>:detail`)
-//   - Pre-Fill nutzt `configKeys[shortName]` → qualifizierter Key, dann
-//     `values[qualifiedKey].value`
-//   - Submit feuert pro geändertem Feld einen `config:write:set` mit
-//     {key, value, scope}; das config-feature behandelt jeden Key als
-//     eigenes Aggregate (configValue.<keyHash>) und alle N Writes laufen
-//     parallel (Promise.all). Per-Key idempotent → Retry safe.
-//   - kein Singleton-Hack nötig: pro (key+tenantId) gibt's by-design
-//     genau eine Row, der Bridge-Pattern aus dem Branding-MVP fällt weg
-//
-// Partial-Failure-Semantik: wenn von N parallelen Writes einer scheitert,
-// bleiben die anderen committed (pro-Aggregate, kein Multi-Stream-Rollback).
-// Das Form bleibt dirty bis der User retried — die schon erfolgreichen
-// Writes feuern dann nochmal mit demselben Wert. Für `text` / `number` /
-// `boolean` Keys ist das idempotent. Wer einen ConfigKey mit nicht-
-// idempotentem Setter baut (Counter, append-only-list o.ä.) muss die
-// Idempotenz im Setter sicherstellen.
-//
-// Field-Shape: inline am Screen wie bei `actionForm`. Author hat damit
-// explizite Kontrolle über Input-Type (text/number/select/...) ohne
-// Resolve-Ceremony — die FieldDefinitions sind dieselben wie auf
-// Entities, alle DefaultInput-Renderer greifen unverändert. Field-
-// Labels gehen über bestehende i18n-Konventionen (`<feature>:entity:
-// <namespace>:field:<name>` o.ä. — der Author wählt den Namespace).
-//
-// scope MUSS mit der `createTenantConfig`/`createSystemConfig`/
-// `createUserConfig`-Deklaration der referenzierten Keys
-// übereinstimmen — der Boot-Validator pinnt das.
-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;
-};
-
-// Self-populating counterpart of ConfigEditScreenDefinition for `r.secret(...)`
-// declarations. No EditLayout/FieldDefinition — secrets never round-trip a
-// stored value to the client, so the screen renders its own body (password
-// inputs + redaction display + delete) instead of going through RenderEdit.
-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;
-};
-
-// --- shared slots (Level 4 from ui-architecture.md) ---
-
-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;
-};
-
-// --- discriminated union ---
-
-// Inline nav-entry sugar for `r.screen({ ..., nav: {...} })` — covers the
-// common case of "one nav entry pointing at this screen". The nav entry's
-// `id`/`screen` are synthesized from the screen's own id; for anything
-// beyond label/icon/parent/order (access-gating, workspaces, actions),
-// declare a standalone `r.nav()` entry instead.
-export type ScreenNavSugar = {
-  readonly label: string;
-  readonly icon?: NavIconKey;
-  readonly parent?: string;
-  readonly order?: number;
-};
-
-// `nav`/`detailFor`/`description`/`agent` live directly on every variant (not only via this
-// union) so a screen typed as its own concrete kind — e.g. `const screen:
-// CustomScreenDefinition = {...}` in a module split out of `feature.ts` —
-// still accepts all four; a union-only intersection drops them the
-// moment a caller narrows to one member.
-//
-// `detailFor` applies to any screen kind because any kind can be the
-// detail view for an entity — including `custom`: in app repos, detail
-// screens are overwhelmingly custom screens today (projectionDetail
-// doesn't carry entity semantics). Value is an entity name in the same
-// (unqualified, globally-unique) form as `entity` on
-// `EntityListScreenDefinition` — entities are never feature-prefixed, so
-// there's no separate qualification step.
-export type ScreenDefinition =
-  | EntityListScreenDefinition
-  | ProjectionListScreenDefinition
-  | ProjectionDetailScreenDefinition
-  | DashboardScreenDefinition
-  | EntityEditScreenDefinition
-  | ActionFormScreenDefinition
-  | ConfigEditScreenDefinition
-  | SecretsEditScreenDefinition
-  | SecretMintScreenDefinition
-  | CustomScreenDefinition;