@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/agents/api/renderer-web.md

@@ -0,0 +1,1450 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/renderer/src/web/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-renderer/web
+
+Import from `@cosmicdrift/kumiko-renderer/web`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function ActionMenu(props: ActionMenuProps): ReactNode;
+function AiTextArea(props: AiTextAreaProps): ReactNode; // Multi-line variant of {@link AiTextField}.
+function AiTextField(props: AiTextFieldProps): ReactNode; // Single-line AI text field — ghost-text completion + correct/translate/ rewrite toolbar.
+function AppLayout(props: AppLayoutProps): ReactNode;
+function Avatar(props: AvatarProps): ReactNode;
+function BareFormProvider(props: { children: ReactNode; }): ReactNode;
+function BooleanField(props: BooleanFieldProps): ReactNode; // Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean").
+function Card(props: CardProps): ReactNode;
+function ChoiceCards<T extends string>(props: { value: T | null; options: { value: T; title: string; description?: string; aside?: string; disabled?: boolean; }[]; onChange: (value: T) => void; ariaLabel?: string; testId?: string; }): ReactNode; // Card-styled radio group for mutually exclusive choices that need a description or price line.
+function CollapsibleSection(props: { title: string; defaultOpen?: boolean; children: ReactNode; testId?: string; }): ReactNode; // Collapsible section using native <details> with React-controlled state; otherwise the open attribute resets to its initial value on every parent re-render.
+function ComparisonTable<Col>(props: { columns: Col[]; columnHeader: (col: Col, index: number) => string; columnKey: (col: Col, index: number) => string; metrics: ComparisonMetric<Col>[]; metricLabel: string; testId?: string; className?: string; card?: boolean; }): ReactNode; // Transposed comparison table: row = metric, column = variant, with the best column optionally highlighted for each metric.
+function DateField(props: DateFieldProps): ReactNode; // Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd.
+function DefaultAppShell(props: DefaultAppShellProps): ReactNode;
+function DetailList(props: { rows: { id?: string; label: string; value: ReactNode; emphasize?: boolean; }[]; testId?: string; }): ReactNode; // Read-only key-value list for detail views (dimmed label on the left, value on the right).
+function DispatcherProvider(props: DispatcherProviderProps): ReactNode;
+function Drawer(props: DrawerProps): ReactNode; // Slide-in panel beside a list (e.g. mail reader next to the inbox) — thin wrapper over the Sheet primitive with header/body/footer slots so screens skip per-route Radix boilerplate.
+function DropdownMenuCheckboxItem(props: ComponentPropsWithoutRef<typeof Primitive.CheckboxItem>): ReactNode;
+function DropdownMenuContent(props: ComponentPropsWithoutRef<typeof Primitive.Content> & { portalContainer?: HTMLElement | null; }): ReactNode;
+function DropdownMenuItem(props: ComponentPropsWithoutRef<typeof Primitive.Item>): ReactNode;
+function DropdownMenuLabel(props: ComponentPropsWithoutRef<typeof Primitive.Label>): ReactNode;
+function DropdownMenuSeparator(props: ComponentPropsWithoutRef<typeof Primitive.Separator>): ReactNode;
+function EditorPanel(props: EditorPanelProps): ReactNode;
+function EmptyState(props: { icon?: ReactNode; title: string; description?: string; action?: ReactNode; testId?: string; }): ReactNode; // Empty state with an optional icon and CTA, using the dashed-box style of entityList empty states as a standalone widget for custom screens.
+function ErrorState(props: { error: DispatcherError; onRetry?: () => void; testId?: string; }): ReactNode; // Error state based on the Banner primitive, with a retry button.
+function FeedList(props: { rows: FeedRow[]; emptyContent?: ReactNode; testId?: string; }): ReactNode; // Non-tabular compact list (e.g. "upcoming appointments") — primary text plus an optional right-aligned trailing value for each row.
+function FileField(props: FileFieldProps): ReactNode; // File upload = Field + Input(kind:"file"|"image"), based on FileRef.
+function FloatingPanel(props: FloatingPanelProps): ReactNode; // Non-modal panel floating above the page: draggable by its header, resizable from all edges and corners, clamped to the viewport, geometry optionally remembered.
+function FormScreenShell(props: { children: ReactNode; className?: string; testId?: string; maxWidth?: FormScreenShellWidth; fillHeight?: boolean; }): ReactNode;
+function HeaderActionGroup(props: HeaderActionGroupProps): ReactNode;
+function Icon(props: { name: NavIconKey; className?: string; }): ReactNode;
+function InfinityList<TData = unknown, TRow = Readonly<Record<string, unknown>>>(props: InfinityListProps<TData, TRow>): ReactNode; // Cursor-paginated scroll list (mail inbox, activity feeds) — loads the next page when the end sentinel becomes visible (IntersectionObserver), instead of a pager bar like QueryTable/entityList.
+function KumikoLink(props: KumikoLinkProps): ReactNode;
+function KumikoScreen(props: KumikoScreenProps): ReactNode;
+function LanguageMenuItems(props: LanguageMenuItemsProps): ReactNode; // Locale choices as dropdown entries, for a user menu that carries the shell controls.
+function LanguageSwitcher(props: LanguageSwitcherProps): ReactNode;
+function LiveEventsProvider(props: LiveEventsProviderProps): ReactNode;
+function LoadingState(props: { rows?: number; className?: string; testId?: string; }): ReactNode; // Loading state with skeleton rows styled like cards; `rows` controls the height.
+function LocaleProvider(props: LocaleProviderProps): ReactNode;
+function MiniStat(props: { label: string; value: string; tone?: StatTone; emphasize?: boolean; testId?: string; labelTestId?: string; valueTestId?: string; }): ReactNode; // Compact metric tile (without an icon) — for dense KPI grids.
+function ModeSwitch<T extends string>(props: { value: T | null; options: { value: T; label: string; count?: number; }[]; onChange: (value: T) => void; ariaLabel?: string; variant?: ModeSwitchVariant; className?: string; testId?: string; }): ReactNode; // Segmented control for mutually exclusive modes—the prominent alternative to the buried <select>.
+function NavProvider(props: NavProviderProps): ReactNode;
+function NavTree(props: NavTreeProps): ReactNode;
+function NumberField(props: NumberFieldProps): ReactNode; // Number field = Field + Input(kind:"number"); avoids repeating the id/name/value/onChange wiring at each screen.
+function PageSection(props: PageSectionProps): ReactNode;
+function PdfPreview(props: { source: PdfPreviewSource; testId?: string; }): ReactNode;
+function PhotoSlots(props: PhotoSlotsProps): ReactNode; // Guided photo capture: one tile per requested shot in a two-column grid, each its own camera/gallery picker, filled tiles show the thumbnail.
+function PlainContentEditor(props: ContentEditorProps): ReactNode;
+function PlanCard(props: PlanCardProps): ReactNode;
+function PlanGrid(props: PlanGridProps): ReactNode;
+function PrimitivesProvider(props: PrimitivesProviderProps): ReactNode;
+function ProfileMenu(props: ProfileMenuProps): ReactNode;
+function ProgressBar(props: { value: number; tone?: ProgressTone; size?: "default" | "thin"; ariaLabel?: string; className?: string; testId?: string; }): ReactNode; // Progress bar, `value` 0..1 (clamped).
+function ProgressList(props: { rows: ProgressListRow[]; emptyContent?: ReactNode; testId?: string; }): ReactNode; // Label/value header and progress bar for each entry (for example, loan repayment progress).
+function PublicShell(props: PublicShellProps): ReactNode; // One header and footer for anonymous pages; `focus` narrows to a task column, `card` centers a single card (sign-in).
+function QueryTable<TData = unknown>(props: QueryTableProps<TData>): ReactNode;
+function RangeField(props: RangeFieldProps): ReactNode; // Slider = Field + Input(kind:"range").
+function RenderEdit<TValues extends FormValues, TCtx = unknown>(rawProps: RenderEditProps<TValues, TCtx>): ReactNode;
+function RenderField(props: RenderFieldProps): ReactNode;
+function RenderList(props: RenderListProps): ReactNode;
+function ResizableHandle(props: ResizablePrimitive.SeparatorProps & { withHandle?: boolean; }): JSX.Element;
+function ResizablePanel(props: ResizablePrimitive.PanelProps): JSX.Element;
+function ResizablePanelGroup(props: ResizablePrimitive.GroupProps): JSX.Element;
+function ResultPanel(props: { title: string; subtitle?: string; empty?: boolean; emptyText?: ReactNode; rows?: { label: string; value: ReactNode; emphasize?: boolean; }[]; footer?: ReactNode; children?: ReactNode; testId?: string; }): ReactNode; // Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes).
+function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
+function ScreenWidthProvider(props: { width: FormWidth | undefined; children: ReactNode; }): ReactNode;
+function SectionCard(props: { title: string; subtitle?: string; action?: ReactNode; footer?: ReactNode; children: ReactNode; testId?: string; }): ReactNode; // Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens.
+function SelectField(props: SelectFieldProps): ReactNode; // Select field = Field + Input(kind:"select").
+function SideBySideTable(props: { caption: string; rowHeaderLabel: string; columns: SideBySideTableColumn[]; rows: SideBySideTableRow[]; rowHeaderWidth?: number; testId?: string; }): ReactNode; // Small read-only grid with real table semantics (`th scope`) whose cells are arbitrary React nodes — for side-by-side comparisons like "from the document" vs.
+function Sidebar(props: SidebarProps): ReactNode;
+function SidebarBrand(props: SidebarBrandProps): ReactNode;
+function SidebarMenu(props: React.ComponentProps<"ul">): React.JSX.Element;
+function SidebarMenuButton(props: React.ComponentProps<"button"> & { asChild?: boolean; isActive?: boolean; tooltip?: string | React.ComponentProps<typeof TooltipContent>; } & VariantProps<typeof sidebarMenuButtonVariants>): React.JSX.Element;
+function SidebarMenuItem(props: React.ComponentProps<"li">): React.JSX.Element;
+function SidebarPanel(props: SidebarPanelProps): ReactNode; // Renders its children into the second sidebar column when the shell offers one.
+function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void; }): React.JSX.Element;
+function SidebarUser(props: SidebarUserProps): ReactNode;
+function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
+function Stack(props: StackProps): ReactNode;
+function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
+function StatusBadge(props: { tone: StatusBadgeTone; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
+function StatusBarChart(props: { entries: StatusBarEntry[]; ariaLabel: string; startLabel?: string; endLabel?: string; highlightLast?: boolean; dense?: boolean; testId?: string; }): ReactNode; // Status bar strip (e.g. 90-day uptime): variable-height bars with gradient fade + tick line on top; the last entry gets a "now" accent stripe.
+function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical"; heading?: string; description?: string; subtitles?: (string | undefined)[]; upNext?: { heading: string; title: string; subtitle?: string; }; testId?: string; compactTestId?: string; }): ReactNode; // Wizard step overview — numbered chips with a connector line between them.
+function TextField(props: TextFieldProps): ReactNode; // Text field = Field + Input(kind:"text").
+function TextareaField(props: TextareaFieldProps): ReactNode; // Multi-line text field = Field + Input(kind:"textarea").
+function ThemeMenuItem(props: ThemeMenuItemProps): ReactNode; // Theme toggle as a dropdown entry, for a user menu that carries the shell controls.
+function ThemeToggle(props: ThemeToggleProps): ReactNode;
+function TimeseriesChart(props: { points: TimeseriesPoint[]; windowStartMs: number; windowEndMs: number; tone?: StatusTone; ariaLabel: string; axisLabels?: { start: string; mid?: string; end: string; }; xAxis?: TimeseriesXAxis; yAxis?: TimeseriesYAxis; height?: TimeseriesHeight; markers?: ChartMarker[]; formatMarkerTime?: (atMs: number) => string; referenceLines?: TimeseriesReferenceLine[]; emptyContent?: ReactNode; testId?: string; }): ReactNode; // Time-series line chart (smoothed line with area fill).
+function ToastProvider(props: ToastProviderProps): ReactNode;
+function TokensProvider(props: TokensProviderProps): ReactNode;
+function Topbar(props: TopbarProps): ReactNode;
+function UploadZone(props: UploadZoneProps): ReactNode; // Drop zone + multi-file picker with a per-file status row (uploading/done/ error).
+function UserRolesProvider(props: UserRolesProviderProps): ReactNode;
+function WorkspaceShell(props: WorkspaceShellProps): ReactNode;
+function WorkspaceSwitcher(props: WorkspaceSwitcherProps): ReactNode; // Requires an ancestor `SidebarProvider` (see `../ui/sidebar`) — this component renders `SidebarMenuButton`, which calls `useSidebar()` internally and throws ("useSidebar must be used within a SidebarProvider.") when rendered outside one.
+function applyTokensToCssVars(_tokens: Tokens): void; // Historically wrote tokens to :root as CSS variables.
+function buildFileUploadFormData(input: FileUploadFormDataInput): FormData;
+function buildNavRegistrySlice(schema: FeatureSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
+function buildNavRegistrySliceForApp(app: AppSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
+function clearRememberedListState(): void; // Forgets all remembered list state and the identity marker.
+function cn(...inputs: ClassValue[]): string; // Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`).
+function createBrowserDraftStorage(options?: CreateBrowserDraftStorageOptions): DraftStorage; // Default DraftStorage when createKumikoApp boots without one.
+function createBrowserLocaleResolver(options?: CreateBrowserLocaleResolverOptions): LocaleResolver; // Default resolver when createKumikoApp is booted without a `locale` option.
+function createEventSourceLiveEvents(options?: CreateEventSourceLiveEventsOptions): LiveEventSubscriber; // Returns an EventSource-backed `LiveEventSubscriber`.
+function createKumikoApp(options?: CreateKumikoAppOptions): { root: Root; };
+function createPublicSurface(options: CreatePublicSurfaceOptions): { root: Root; };
+function createStaticLocaleResolver(options?: { locale?: string; timeZone?: string; }): LocaleResolver; // Default resolver for apps without their own i18n layer.
+function downloadFileRef(fileRefId: string, options?: { fileName?: string; }): Promise<void>;
+function fetchFileRefBlob(fileRefId: string): Promise<{ blob: Blob; fileName: string | undefined; }>;
+function fileNameFromContentDisposition(header: string | null): string | undefined;
+function filterAppSchemaNavsByAllowlist(schema: AppSchema, allowedNavQns: ReadonlySet<string>, reparentOverrides?: ReadonlyMap<string, NavReparentOverride>): AppSchema;
+function filterByAccess(workspaces: WorkspaceSchema[], userRoles: string[] | undefined): WorkspaceSchema[];
+function formatMoney(amountMinor: number, currency: string, locale?: string, fractionDigits?: number): string;
+function formatPath(target: ScreenTarget): string;
+function parsePath(pathname: string, hasWorkspaces?: boolean): NavRoute | undefined;
+function parseTargetFromSearchParams(params: Readonly<Record<string, string>>): TargetRef | undefined; // Parses the current search parameters back into a TargetRef.
+function postWithDownload(dispatcher: Dispatcher, type: string, payload: unknown): Promise<DispatcherError | null>;
+function qualifyScreenId(featureName: string, screenId: string): string;
+function readLoadedBuild(): KumikoBuild | undefined;
+function reparentAppSchemaNavs(schema: AppSchema, overrides: ReadonlyMap<string, NavReparentOverride>): AppSchema;
+function resolveDefaultId(visible: WorkspaceSchema[], preferredShortId: string | undefined): string | undefined;
+function saveBlobAsFile(fileName: string, blob: Blob, options?: { bom?: boolean; }): void;
+function smoothPath(pts: ReadonlyArray<{ x: number; y: number; }>): string; // Quadratic midpoint technique: smooths the zigzag line without overshoot (~5 lines instead of a Catmull-Rom/Bezier fit).
+function synthesizeActionFormEntity(fields: Readonly<Record<string, FieldDefinition>>): EntityDefinition; // Builds a minimal EntityDefinition from the inline fields of an ActionForm or SecretMint screen.
+function synthesizeActionFormScreen(screen: ActionFormScreenDefinition | SecretMintScreenDefinition): EntityEditScreenDefinition; // Converts an ActionFormScreenDefinition or SecretMintScreenDefinition to the EntityEditScreen shape expected by RenderEdit.
+function uploadFileRef(file: Blob, target?: FileRefTarget): Promise<string>; // Posts one file to the stack's file endpoint (double-submit CSRF) and returns the new FileRef id.
+function useBrowserNavApi(options?: { hasWorkspaces?: boolean; basePath?: string; features?: FeatureSchema[]; }): NavApi; // React hook that builds a NavApi from browser history.
+function useBrowserTokensApi(): TokensApi; // Builds a TokensApi for the browser.
+function useDispatchTarget(): (target: TargetRef) => void; // Recommended production dispatch.
+function useDispatcher(): Dispatcher;
+function useDispatcherStatus(): DispatcherStatus;
+function useDraft<T extends object>(defaults: T, options?: { idPrefix?: string; }): { draft: T; patch: (changes: Partial<T>) => void; reset: () => void; field: <K extends keyof T>(name: K) => { id: string; name: string; value: T[K]; onChange: (v: T[K]) => void; }; }; // Form state for calculator screens: a draft object plus `patch` for partial updates, and `field(name)` that provides `{ id, name, value, onChange }` props ready for field widgets (NumberField/MoneyField/PercentField).
+function useForm<TValues extends FormValues, TCtx = unknown>(options: UseFormOptions<TValues, TCtx>): UseFormResult<TValues>;
+function useIsNarrowViewport(): boolean;
+function useIsViewportBelow(breakpointPx: number): boolean;
+function useLiveEvents(): LiveEventSubscriber; // Hook for a useQuery-like consumer.
+function useLocale(): LocaleResolver; // Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes.
+function useNav(): NavApi;
+function usePrimitives(): PrimitivesRegistry;
+function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;
+function useResolvers(): ReadonlyMap<string, ResolverComponent>;
+function useStore<T>(store: Store<T>): T;
+function useStoreSelector<T, S>(store: Store<T>, select: (snapshot: T) => S, equals?: (a: S, b: S) => boolean): S;
+function useToast(): ToastApi;
+function useTokenController(): TokensApi; // Full API including theme toggling, for a dark/light switch button.
+function useTokens(): Tokens; // Read-only tokens hook.
+function useTranslation(): (key: string, params?: Readonly<Record<string, unknown>>) => string; // `t("key", params)` resolves in this order: 1.
+function useUserRoles(): string[] | undefined;
+```
+
+## Constants
+
+```ts
+const BROWSER_LOCALE_STORAGE_KEY: "kumiko:locale";
+const DropdownMenu: FC<Primitive.DropdownMenuProps>;
+const DropdownMenuPortal: FC<Primitive.DropdownMenuPortalProps>;
+const DropdownMenuTrigger: ForwardRefExoticComponent<Primitive.DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>>;
+const MoneyField: typeof NumberField;
+const PercentField: typeof NumberField;
+const STATUS_TONE_TEXT: Record<StatusTone, string>;
+const cssVarTokens: Tokens; // Tokens with var-string values.
+const defaultPrimitives: CorePrimitives;
+const defaultTokens: Tokens; // Default tokens—identical to `cssVarTokens` (variable-string references).
+const lightTokens: Tokens;
+```
+
+## Classes
+
+```ts
+class FileDownloadFailedError extends Error {
+  constructor(status: number);
+}
+class FileUploadFailedError extends Error { // Carries the server's own `error` message when the upload endpoint sent one.
+  constructor(message: string, fromServer: boolean, httpStatus?: number, code?: string);
+}
+```
+
+## Types
+
+```ts
+type ActionMenuProps = {
+  trigger: ReactNode; // Free-form Trigger-Component — Avatar, IconButton, Pill, Custom.
+  triggerLabel?: string; // aria-label for the trigger wrapper.
+  items: MenuItemDef[];
+  align?: "start" | "center" | "end"; // Where to anchor the popup relative to the trigger.
+  minWidth?: string; // Minimum width for the content.
+  testId?: string;
+};
+interface AiTextAreaProps extends AiTextFieldBaseProps {
+  rows?: number;
+}
+interface AiTextFieldProps extends AiTextFieldBaseProps {}
+type AppLayoutProps = {
+  topbar?: ReactNode; // Optional.
+  sidebar?: ReactNode;
+  children: ReactNode;
+  testId?: string;
+  fill?: boolean; // Viewport-fit shell.
+  className?: string; // Optional classes appended to the root (for a custom background, etc.).
+  mainClassName?: string; // Optionaler Klassen-Append an `<main>`.
+};
+interface AppPrimitives {} // Extension point for app-owned primitives.
+interface AppTokens {} // Extension point for app-specific token categories.
+type AvatarProps = {
+  id: string; // Stable identifier—the source for the background-color hash.
+  label: string; // Full name or email—the initials are extracted from this value.
+  size?: AvatarSize;
+  testId?: string;
+};
+type AvatarSize = "sm" | "md" | "lg";
+type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
+  variant?: "error" | "info" | "loading" | "warning" | "primary"; // "error" for alerts (conflict, network error), "info" for neutral placeholders (not-found, loading), "loading" for load states, "warning" for a non-blocking but attention-grabbing notice (e.g. secretMint's "this is shown only once"), "primary" for a call-to-action notice (neutral background, accent in the primary color; pair it with `title` and `actions`).
+  title?: ReactNode; // Bold heading above `children`, inside the text column.
+  titleTestId?: string;
+  children: ReactNode;
+  actions?: ReactNode; // Optional—additional buttons or elements to the right of the text (for example, "Neu laden").
+  padded?: boolean; // Adds outer spacing around the banner for page states where it renders alone in the main area (KumikoScreen "not-found", "loading", etc.).
+  testId?: string;
+  id?: string; // Set when a `<Field>` wraps this Banner as its control (no actual input exists for the label to target — see render-field.tsx's unsupported-field-type fallback).
+};
+interface BooleanFieldProps extends FieldBase {
+  value: boolean;
+  onChange: (v: boolean) => void;
+}
+type ButtonProps = ButtonBaseProps & ({ children: ReactNode; } | { children?: undefined; icon: NavIconKey; ariaLabel: string; }); // Standard button.
+type CardProps = { // Generic card chrome (border/background/radius/shadow plus header/body/footer) as a primitive, providing one implementation for all card surfaces.
+  slots?: CardSlots;
+  options?: CardOptions;
+  children?: ReactNode; // Body content in the normal case; header and footer are supplied through `slots`.
+  className?: string;
+  testId?: string;
+  dataAttributes?: DataAttributes;
+};
+type ClientFeatureDefinition = {
+  name: string;
+  providers?: ComponentType<{ children: ReactNode; }>[]; // Context providers wrapped around the complete renderer tree.
+  gates?: ComponentType<{ children: ReactNode; }>[]; // Screen decorators placed between the provider stack and the shell or screen render.
+  translations?: TranslationsByLocale; // Default translations supplied by the feature for its UI strings.
+  components?: Readonly<Record<string, ComponentType>>; // Custom screen components, mapped by screenId.
+  columnRenderers?: Readonly<Record<string, ColumnRendererComponent>>; // Column renderer components, mapped by renderer name.
+  extensionSectionComponents?: Readonly<Record<string, ExtensionSectionComponent>>; // Extension-section components, mapped by `__component` name.
+  clientActions?: Readonly<Record<string, ClientActionHandler>>; // Handlers for RowAction `kind: "clientAction"`, keyed by the action name `<feature>:<kebab>`.
+  navProviders?: Readonly<Record<string, TreeChildrenSubscribe>>; // Nav providers for the single nav visual-tree merge: they attach dynamic children to a static `r.nav({ provider: true })` node.
+  navEntities?: Readonly<Record<string, string[]>>; // SSE entity lists per nav ID for live refresh of navProviders, analogous to `treeEntities`.
+  navProvidersFromCollections?: (collections: QualifiedContentCollection[]) => CollectionNavProviders; // Nav providers derived from the app schema — called with every `r.contentCollection()` the app declares.
+  contentEditors?: Partial<Record<ContentEditorFormat, ContentEditorComponent>>; // Content editor components — map `contentFormat` ("plain" | "document") → React component.
+  resolvers?: Readonly<Record<string, ComponentType<{ target: TargetRef; onClose: () => void; }>>>; // Editor resolver components keyed by featureId:action.
+};
+type ColorTokens = {
+  background: string;
+  foreground: string;
+  card: string;
+  cardForeground: string;
+  popover: string;
+  popoverForeground: string;
+  primary: string;
+  primaryForeground: string;
+  secondary: string;
+  secondaryForeground: string;
+  muted: string;
+  mutedForeground: string;
+  accent: string;
+  accentForeground: string;
+  destructive: string;
+  destructiveForeground: string;
+  border: string;
+  input: string;
+  ring: string;
+};
+interface ComparisonMetric<Col> {
+  label: string;
+  value: (col: Col, index: number) => ReactNode;
+  bestIndex?: (cols: Col[]) => number; // Index of the best column for this row (highlighted); -1 = none.
+}
+type CorePrimitives = {
+  Button: ComponentType<ButtonProps>;
+  Banner: ComponentType<BannerProps>;
+  Field: ComponentType<FieldProps>;
+  Input: ComponentType<InputProps>;
+  DataTable: ComponentType<DataTableProps>;
+  EmbeddedListInput?: ComponentType<EmbeddedListInputProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  Form: ComponentType<FormProps>;
+  Section: ComponentType<SectionProps>;
+  Card: ComponentType<CardProps>;
+  Grid: ComponentType<GridProps>;
+  GridCell: ComponentType<GridCellProps>;
+  Text: ComponentType<TextProps>;
+  Heading: ComponentType<HeadingProps>;
+  Dialog: ComponentType<DialogProps>;
+  Modal: ComponentType<ModalProps>;
+  Drawer?: ComponentType<DrawerProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  Lightbox: ComponentType<LightboxProps>;
+  ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
+  ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;
+  Link: ComponentType<LinkProps>;
+  Progress?: ComponentType<ProgressProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  StepBar?: ComponentType<StepBarProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  WizardStepGroup?: ComponentType<WizardStepGroupProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  Tabs?: ComponentType<TabsProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  StatusBadge?: ComponentType<StatusBadgeProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  Metric?: ComponentType<MetricProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  JsonView?: ComponentType<JsonViewProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  FileValueList?: ComponentType<FileValueListProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  FillContainer?: ComponentType<FillContainerProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  PageHeader?: ComponentType<PageHeaderProps>; // Optional — additive rollout, see StickyActionBar.
+  MetricBand?: ComponentType<MetricBandProps>; // Optional — additive rollout, see StickyActionBar.
+  ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>; // Optional: without an implementation, callers with >2 header/row actions fall back to today's all-buttons-inline rendering.
+  SecretReveal?: ComponentType<SecretRevealProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  StickyActionBar?: ComponentType<StickyActionBarProps>; // Optional (unlike the other Core-Primitives) so existing partial CorePrimitives mocks in tests keep compiling — additive rollout of a new primitive shouldn't force every test double to grow a stub.
+  CopyButton?: ComponentType<CopyButtonProps>; // Optional — additive rollout, see StickyActionBar.
+  ShareButton?: ComponentType<ShareButtonProps>; // Optional — additive rollout, see StickyActionBar.
+  PromoPanel?: ComponentType<PromoPanelProps>; // Optional — additive rollout, see StickyActionBar.
+};
+type CoreTokens = {
+  color: ColorTokens;
+  radius: RadiusTokens;
+  font: FontTokens;
+  shadow: ShadowTokens;
+  spacing: SpacingTokens;
+};
+type CreateBrowserDraftStorageOptions = {
+  storagePrefix?: string; // sessionStorage-key prefix, one entry per screenId gets appended.
+};
+type CreateBrowserLocaleResolverOptions = {
+  storageKey?: string; // localStorage key used to persist the active locale.
+  defaultLocale?: string; // Fallback when neither localStorage nor navigator.language provides a locale.
+  normalizeLocale?: (tag: string) => string | undefined; // Maps a stored or browser-reported tag onto one of the app's locales; `undefined` rejects it (a stored tag then falls through to navigator.language, the browser tag to `defaultLocale`).
+};
+type CreateEventSourceLiveEventsOptions = {
+  url?: string; // URL of the SSE endpoint.
+  onSessionEnded?: () => void; // Fires once per connection when the session ended: the server refused the SSE handshake, or opened the stream with a `session-ended` frame (stale auth cookie downgraded to anonymous).
+  timers?: LiveEventTimers; // Reconnect-timer seam; defaults to the global setTimeout/clearTimeout.
+  random?: () => number; // Jitter source in [0, 1); defaults to Math.random.
+  now?: () => number; // Clock for synthetic resync events; defaults to Date.now.
+};
+type CreateKumikoAppOptions = {
+  onError?: BoundaryErrorHandler; // Called when the screen or root error boundary catches an error, after it was logged with console.error — attach telemetry here.
+  reportClientErrors?: boolean; // POST caught render errors and unhandled window errors to `/api/client-errors` (default true).
+  schema?: AppSchema | FeatureSchema; // App schema.
+  rootId?: string;
+  dispatcher?: Dispatcher;
+  schemaUrl?: string; // URL of the authenticated schema endpoint, fetched when no `schema` is given.
+  draftStorage?: DraftStorage; // RenderEdit's create-mode draftId storage — where a same-tab reload finds which of several parallel create-sessions on a screen to resume.
+  screenQn?: string;
+  translate?: Translate;
+  onRowClick?: (row: ListRowViewModel, entityName: string) => void; // Row-click fallback for entities with no declared `detailFor` screen — a `detailFor` screen always wins over this option.
+  shell?: (props: { children: ReactNode; schema: AppSchema; }) => ReactNode; // App shell.
+  primitives?: Partial<PrimitivesRegistry>;
+  clientFeatures?: ClientFeatureDefinition[]; // Client extensions supplied by features.
+  locale?: LocaleResolver; // App-level LocaleResolver.
+  navAdapter?: (options?: { hasWorkspaces?: boolean; features?: FeatureSchema[]; }) => NavApi; // Navigation adapter — a React hook that returns a NavApi instance (route + navigate + hrefFor).
+  basePath?: string; // URL prefix the app is mounted under (for example "/admin").
+  screenWidth?: FormWidth; // App-wide default width for form/detail screens that don't set their own `layout.width`.
+};
+type CreatePublicSurfaceOptions = {
+  routes: PublicRoute[];
+  fallback?: ReactNode; // Rendered when no route.path matches the current path.
+  rootId?: string;
+  locale?: LocaleResolver;
+  primitives?: Partial<PrimitivesRegistry>;
+  dispatcher?: Dispatcher; // Dispatcher for handler calls (e.g. an anonymous deletion request).
+  clientFeatures?: ClientFeatureDefinition[]; // Feature client extensions — ONLY `providers` + `translations` are stacked.
+  shell?: (props: { children: ReactNode; }) => ReactNode; // Page chrome around the matched content (apex/marketing layout).
+  formality?: Formality; // Wording for every page of this surface.
+};
+type DataTableProps = DataTableTableBlock & {
+  columns: ListColumnViewModel[];
+  rows: ListRowViewModel[];
+  rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined; // Tints a row.
+  onRowClick?: (row: ListRowViewModel) => void;
+  sort?: DataTableSort | null; // Current sorting, or null when unsorted.
+  onSortChange?: (next: DataTableSort | null) => void; // Called with the next sort state after a header click.
+  rowActions?: DataTableRowAction[]; // Per-row actions rendered in a right-hand column as inline buttons (≤2 actions) or a kebab dropdown (>2).
+  rowActionMode?: DataTableRowActionMode; // How the row-action column renders: - `"adaptive"` (default): with `onRowClick` all actions except the `rowClick` one go in the kebab (no kebab or column if none remain); without it the primary action is a link button and the rest go in the kebab (a single action gets no kebab).
+  bulk?: DataTableBulk; // Present: row checkboxes plus a selection bar that runs these actions once per selected row.
+  emptyState?: ReactNode; // Custom empty-state content (e.g. Icon + Heading + CTA-Button).
+  toolbarTitle?: ReactNode; // Optional title slot at the left of the toolbar, typically the screen title ("Items", "Bestellungen").
+  toolbarStart?: ReactNode; // Toolbar slot in the middle, typically a search input.
+  toolbarEnd?: ReactNode; // Toolbar slot on the right, typically for a + New button, filters, or a view switch.
+  filterFacets?: DataTableFacet[]; // Faceted filter dropdowns for select/boolean fields.
+  filterValues?: Readonly<Record<string, string[]>>; // Currently selected values for each facet field, supplied by URL state.
+  onFilterChange?: (field: string, values: string[]) => void; // Toggling a facet value: the caller updates URL state and refetches.
+  onFilterReset?: () => void; // Clears all active facets.
+  dateRangeFacets?: DataTableDateRangeFacet[]; // Time-range filters beside the facet dropdowns.
+  onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed ("" clears it) → caller writes URL state + refetch.
+  pager?: {
+    page: number;
+    limit: number;
+    total: number;
+    onPageChange: (next: number) => void;
+    pageSizeOptions?: number[]; // Offered page sizes; with `onPageSizeChange` the footer shows a "N per page" select.
+    onPageSizeChange?: (next: number) => void;
+  }; // Pagination state and callback.
+  toolbarDescription?: string; // Hint at the left of the toolbar (relatedList tab description).
+  itemNoun?: (count: number) => string; // Noun for the footer count ("1–19 of 19 leases", "1 position"), resolved for the given count.
+  onReachEnd?: () => void; // Infinite-scroll callback.
+  loadingMore?: boolean;
+  hasMore?: boolean; // When false and `onReachEnd` is set, the renderer shows an end-of-list message instead of the sentinel.
+  testId?: string;
+  onCellChange?: (rowId: string, field: string, value: unknown) => void; // Wires an edit path into a component column-renderer: `DataTableCell` passes this down as `ColumnRendererProps.onChange` for that cell, bound to `(rowId, column.field)`.
+  getRowTestId?: (row: ListRowViewModel) => string; // Overrides the row `data-testid` (default `row-${row.id}`) — for a screen that already has its own DOM-test/e2e naming scheme.
+  getCellTestId?: (row: ListRowViewModel, field: string) => string; // Overrides the cell `data-testid` (default `cell-${row.id}-${field}`).
+  chromeless?: boolean; // Drops the table's own rounded/border/card background — for a host that already provides the surrounding boundary (a tab panel) and would otherwise show a card nested inside that boundary.
+  scrollBody?: boolean; // Fills the available height of its flex container and scrolls rows internally instead of growing with row count — for a host that would otherwise have a long table stretch the whole page, or a short table leave dead space below it (a tab panel).
+  screenPadding?: boolean; // Uses the shared screen padding (wider bottom inset) instead of the table's symmetric embedded inset — for a table that IS the screen body (entityList/projectionList), so a list screen ends at the same footer distance as a form or custom screen.
+  expandedRowIds?: ReadonlySet<string>; // Ids of the rows whose expansion area is currently open (controlled by the host; several rows can be open at once).
+  onToggleRowExpanded?: (rowId: string) => void; // User toggled a row's expand control.
+  renderExpandedRow?: (row: ListRowViewModel) => ReactNode; // Content of the area under an expanded row.
+};
+interface DateFieldProps extends FieldBase {
+  value: string;
+  onChange: (v: string) => void;
+  min?: string;
+  max?: string;
+}
+type DefaultAppShellProps = {
+  brand: ReactNode; // Header slot at the top of the sidebar — workspace identity (logo, name, plan tag).
+  schema: AppSchema | FeatureSchema; // Schema (AppSchema or legacy FeatureSchema) passed through to NavTree; sidebar entries are generated automatically from schema.navs (per-feature).
+  user?: DefaultAppShellUser; // Current user — drives navigation role gating.
+  sidebarActions?: ReactNode; // Icon row between the brand and NavTree — typically a Search trigger, ThemeToggle, or TenantSwitcher.
+  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badges per navigation item (bare nav-id → ReactNode), passed through to NavTree.
+  headerActions?: ReactNode; // Right-aligned slot in the topbar (next to the breadcrumb) — for ThemeToggle, global actions, and similar controls.
+  sidebarFooter?: ReactNode; // Footer slot at the bottom of the sidebar — profile row, help link, or plan banner.
+  fill?: boolean; // Viewport-fit shell.
+  children: ReactNode; // Screen content rendered inside SidebarInset.
+};
+type DispatcherProviderProps = {
+  dispatcher: Dispatcher;
+  children: ReactNode;
+};
+type DrawerProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  side?: "left" | "right" | "top" | "bottom";
+  title?: ReactNode;
+  description?: ReactNode;
+  footer?: ReactNode;
+  children: ReactNode;
+  testId?: string;
+  showCloseButton?: boolean; // Header close (X).
+  variant?: "floating" | "flush"; // Panel treatment.
+  belowHeader?: boolean; // `variant="flush"` only: dock the panel below the app's ShellHeader (offset top by `--shell-header-height`, height shrunk to match) instead of covering it.
+  width?: number | string; // Panel width for `side="left"|"right"` (ignored for top/bottom and in the narrow-viewport layout).
+  resize?: {
+    defaultWidthPx?: number;
+    minWidthPx?: number;
+    maxWidthPx?: number;
+  }; // Opt-in drag-to-resize + maximize toggle (left/right sides only).
+  backdrop?: {
+    blurPx?: number;
+    dimPercent?: number;
+  }; // Backdrop behind the panel.
+  modal?: boolean; // `false` runs the drawer as a panel beside the page instead of over it: no overlay, no focus trap, and the page behind stays interactive, so text there can be selected and copied.
+  panelClassName?: string; // Extra classes for the panel, merged over the built-in ones.
+  fillBody?: boolean; // The body becomes a plain flex column with no padding or scrolling of its own, for children that bring their own scroll area and pinned footer.
+};
+type EditorPanelProps = {
+  resolvers: ReadonlyMap<string, ResolverComponent>;
+};
+type FeedRow = {
+  id: string;
+  primary: string;
+  trailing?: string;
+};
+type FieldProps = {
+  id: string;
+  label: string;
+  required?: boolean;
+  issues?: FieldIssue[];
+  labelAppendix?: ReactNode;
+  fieldAppendix?: ReactNode;
+  appendixPlacement?: "above-control" | "below-control"; // Where `fieldAppendix` sits relative to the control.
+  description?: ReactNode; // Help text directly under the label, above the control.
+  status?: {
+    tone: StatusTone;
+    label: string;
+    testId?: string;
+  }; // Status pill at the right end of the label row (e.g. "Saved", "Not set").
+  children: ReactNode;
+  layout?: "stacked" | "inline" | "row"; // Label layout.
+  accent?: boolean; // Marks a field whose value is set at this level (differs from the inherited one).
+  hideLabel?: boolean; // Collapses the visible label to `sr-only` — stays associated via `htmlFor` (no separate `aria-label` needed).
+  changed?: boolean; // Marks the field as edited relative to its saved value — the label row shows a "changed" marker.
+  testId?: string;
+};
+interface FileFieldProps extends FieldBase {
+  value: string | null; // FileRef UUID of the stored file, or null.
+  onChange: (fileId: string | null) => void;
+  accept?: string[];
+  variant?: "file" | "image"; // "image" shows a preview; "file" shows only the file name.
+  entityType?: string; // Binds the upload to a specific entity field; the `/api/files` endpoint then validates `accept`/`maxSize` server-side against that field's definition.
+  fieldName?: string;
+}
+type FileRefTarget = Pick<FileUploadFormDataInput, "entityType" | "entityId" | "fieldName" | "subField" | "actionForm">;
+type FloatingPanelGeometry = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type FloatingPanelProps = {
+  title: ReactNode; // Header content; the header is the move handle.
+  headerActions?: ReactNode; // Header buttons (dock, minimize, close).
+  children: ReactNode;
+  storageKey?: string; // localStorage key; without it the geometry isn't persisted.
+  defaultGeometry?: Partial<FloatingPanelGeometry>; // Default 400x560, bottom-right with a 24px margin.
+  minWidthPx?: number;
+  minHeightPx?: number;
+  maxWidthPx?: number; // Default: viewport width minus twice the margin.
+  maxHeightPx?: number; // Default: viewport height minus twice the margin.
+  testId?: string;
+};
+type FontTokens = {
+  sans: string;
+  heading: string;
+  mono: string;
+};
+type FormProps = { // Submit wrapper.
+  onSubmit: (e?: FormEvent) => void;
+  focusFirstErrorKey?: number; // Bumped by the host each time a submit fails on field errors; the form then moves focus to its first invalid control.
+  children: ReactNode;
+  title?: ReactNode;
+  subtitle?: ReactNode; // Optional muted subtitle below the title (e.g. "Add a new item to your catalog"), providing context in the form header rather than only a label.
+  actions?: ReactNode;
+  secondaryActions?: ReactNode; // Secondary, record-related actions — rendered on the left on desktop, on their own row below the primary action on a narrow viewport.
+  testId?: string;
+  width?: FormWidth; // Max width of the form container.
+  stickyActions?: boolean; // Pins `actions` to the viewport bottom on narrow screens (`<640px`) instead of normal document flow, so it stays reachable when a virtual keyboard shrinks the visible viewport.
+  headerRegion?: ReactNode; // Extra content rendered above the card, inside the same page padding the card itself sits in — for a host that needs its own header region (title/metrics/tabs) to share the form's left padding and width instead of rendering as unpadded siblings before it.
+  titleAction?: ReactNode; // Compact content on the right of the form title, same row — status chips or allowance badges that belong to the screen, not to a field.
+  fillHeight?: boolean; // Sizes the form to fill its container's height (instead of the page's natural content height) so a single scrolling child — a lone relatedList tab's table — can scroll internally instead of stretching the whole page.
+  chromeless?: boolean; // Drops the surrounding card (bg/border/rounded, title/subtitle block, footer border) so sections+footer render as siblings of `headerRegion` on the page background instead of inside a nested card — a tabbed projectionDetail's tab content is a sibling of the head card, not its child (bedienkonzept A1), so it must look like a standalone screen instead of a form embedded in another card.
+  screenForm?: boolean; // Set by RenderEdit for entityEdit/actionForm screens that fill the shell height: the form renders without a surrounding card, in a padded scroll surface with a fixed-width form column.
+  unsavedCount?: number; // Number of unsaved changes, shown in the pinned footer; 0 shows the quiet "No unsaved changes" status.
+  summary?: {
+    title: string;
+    subtitle?: string;
+  }; // Drawer-hosted forms: context box above the fields.
+  sectionNav?: FormSectionNavItem[]; // Titled sections for the "on this page" navigation next to a `screenForm`.
+  sideRail?: ReactNode; // Leading column next to the scroll surface of a `screenForm` (wizard step navigation).
+};
+type GridCellProps = { // Span wrapper for a child within a grid.
+  span?: number;
+  width?: FieldCellWidth; // Only read inside a `flow` grid.
+  children: ReactNode;
+};
+type GridProps = { // Column-based layout.
+  columns: number | "auto";
+  children: ReactNode;
+  testId?: string;
+  maxRows?: number; // Rows visible before the grid becomes vertically scrollable.
+  flow?: boolean; // Fields flow left to right in wrapping rows sized by `GridCell.width` instead of equal-width tracks (screen forms and drawers).
+  list?: boolean; // One full-width row per child, separated by hairlines — the field rows of a `settings-list` section.
+  ariaLabelledBy?: string; // Id of the element naming this grid (a Field label).
+};
+type HeaderActionGroupProps = {
+  children: ReactNode;
+  className?: string;
+};
+type HeadingProps = { // Heading with two roles: `page` is a page title (web: h1), while `section` is a group subheading (web: h2 with uppercase and muted styling).
+  variant?: "page" | "section";
+  children: ReactNode;
+  testId?: string;
+};
+type InfinityListProps<TData = unknown, TRow = Readonly<Record<string, unknown>>> = {
+  query: string; // Dispatcher-Query-Type (`<feature>:query:<entity>:<verb>`).
+  payload?: Readonly<Record<string, unknown>>;
+  pageSize?: number; // Rows per page — sent as `limit` in the query payload.
+  rows: (data: TData) => TRow[];
+  nextCursor: (data: TData) => string | null; // Pull the next-page cursor from the result; `null` means last page.
+  rowId: (row: TRow, index: number) => string; // Must derive from row content (e.g. `row.id`), not from `index` — a live refresh reorders rows (new/changed rows move to the front).
+  renderRow: (row: TRow) => ReactNode;
+  emptyState?: ReactNode;
+  className?: string;
+  testId?: string;
+  live?: boolean; // Subscribe to SSE events for the entity parsed from `query` (`<feature>:query:<entity>:<verb>`) and refetch the first page on any create/update/delete/restore event, merging it into the already-accumulated rows instead of collapsing them — see `useQuery`'s `live` option for the same convention.
+  selectedId?: string | null; // Row id (as returned by `rowId`) whose position `onSelectionChange` reports.
+  onSelectionChange?: (selection: InfinityListSelection) => void; // Fires when the selected row's position or neighbours change, e.g. for a "message 4 of 6" header with previous/next buttons.
+};
+type InfinityListSelection = { // Position of the selected row among the rows loaded so far.
+  index: number;
+  total: number;
+  prevId: string | null;
+  nextId: string | null;
+  hasMore: boolean;
+};
+type InputProps =
+  | {
+    kind: "text";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    autoFocus?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    placeholder?: string; // Hint text shown when the field is empty.
+    autoComplete?: string; // Browser autofill / native keyboard hint.
+    testId?: string; // Sets `data-testid` on the actual `<input>` so app tests can address the element directly (getByTestId + readOnly/disabled assertions).
+    readOnly?: boolean; // Read-only input (for example, a generated free-tier slug).
+    icon?: FieldIconKey; // Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer/web).
+    prefix?: string; // Resolved inline text before/after the input (EditFieldSpec.prefix/suffix).
+    suffix?: string;
+    fill?: InputFillAction;
+    dataAttributes?: DataAttributes;
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void; // Raw keydown access (e.g. Enter-to-submit at the field instead of the surrounding Form).
+  }
+  | {
+    kind: "code"; // Fixed-length numeric one-time code.
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    length: number;
+    onComplete?: (code: string) => void;
+    autoFocus?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    testId?: string;
+    autoComplete?: string; // Default "one-time-code".
+  }
+  | {
+    kind: "email";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    placeholder?: string;
+    autoComplete?: string; // Default "email".
+    testId?: string;
+  }
+  | {
+    kind: "month"; // Month picker; the value is `YYYY-MM` (empty string when unset).
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    testId?: string;
+  }
+  | {
+    kind: "password";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    placeholder?: string; // Hint text shown when the field is empty (analog to kind:"text").
+    autoComplete?: "current-password" | "new-password"; // "current-password" for login, "new-password" for reset/signup—browser password managers use this to decide whether to save the value.
+    trailingAction?: TrailingInputAction; // Icon button inside the field's trailing edge (clear a stored value, undo a pending removal).
+    testId?: string;
+  }
+  | {
+    kind: "number";
+    id: string;
+    name: string;
+    value: number | "";
+    onChange: (v: number | undefined) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    placeholder?: string; // Hint text shown when the field is empty (analog to kind:"text").
+    testId?: string;
+    icon?: FieldIconKey; // Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer/web).
+    step?: number | "any"; // `<input step>`.
+    locale?: string; // BCP-47 tag for the grouped display and the decimal separator when typing.
+    grouping?: boolean; // `false` shows the value without a thousands separator (e.g. a year).
+    integer?: boolean; // Integer-only entry (bigInt): fractional drafts are not emitted via `onChange`.
+    unit?: string; // Resolved display suffix (static or from a sibling field) — never part of the numeric value.
+    prefix?: string;
+    suffix?: string;
+    fill?: InputFillAction;
+  }
+  | {
+    kind: "range";
+    id: string;
+    name: string;
+    value: number;
+    onChange: (v: number) => void;
+    min: number;
+    max: number;
+    step?: number;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "boolean";
+    id: string;
+    name: string;
+    value: boolean;
+    onChange: (v: boolean) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "file" | "image";
+    id: string;
+    name: string;
+    value: string | null; // FileRef UUID (stored file) or null (no upload).
+    onChange: (fileId: string | null) => void; // Implementations must offer their own remove control that calls `onChange(null)`: FileListField relies on it to drop a file from an `images`/`files` field.
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    accept?: string[]; // Erlaubte Extensions/MIME (z.B.
+    maxSize?: string;
+    entityType?: string; // For the upload POST `/api/files`: the endpoint validates maxSize/accept against the field definition for (entityType, fieldName).
+    uploadActionForm?: string; // Screen QN of the actionForm the field belongs to; sent as `actionForm` instead of `entityType`, so the upload stays pending for that form's field.
+    entityId?: string; // Must be sent as the `entityId` part of the upload so the FileRef is attached to the record (qr overlays and access guards need it).
+    fieldName?: string;
+    imageVariant?: string; // Only for kind:"image" — variant name for the preview (`/api/files/:id/variant/:name`).
+    capture?: "environment" | "user"; // Only for kind:"image" — forwarded to the file input's `capture` attribute so a phone opens the camera instead of the file picker.
+    directory?: boolean; // Web-only folder picker: the picked files (with `webkitRelativePath`) go to `onFilesPicked` and nothing is uploaded.
+    onFilesPicked?: (files: PickedFile[]) => void;
+    pickLabel?: string; // Translated label of the pick button; absent → the upload/change default.
+    testId?: string; // Hidden file input gets `${testId}-input`, the pick button `${testId}-pick`.
+  }
+  | {
+    kind: "files-dropzone"; // Drop zone for a `files` / `images` field: the value is the list of uploaded FileRef ids, the implementation offers multi-pick, drag and drop and a remove control per file.
+    id: string;
+    name: string;
+    value: string[];
+    onChange: (fileIds: string[]) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    accept?: string[];
+    maxSize?: string;
+    maxCount?: number;
+    entityType?: string; // Upload target, same meaning as on the `file` kind.
+    uploadActionForm?: string;
+    entityId?: string;
+    fieldName?: string;
+    testId?: string;
+  }
+  | {
+    kind: "date";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string | undefined) => void;
+    locale?: string; // Locale for display and input parsing.
+    min?: string; // Datumsgrenzen als ISO `yyyy-mm-dd` — begrenzen Picker (Jahres- Dropdown-Range + ausgegraute Tage).
+    max?: string;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "select";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    options: string[] | { value: string; label: string; description?: string; group?: string; disabled?: boolean; }[]; // Allowed values.
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    radioVariant?: "list" | "card"; // `"card"` renders the radio group as bordered cards with label plus optional description per option and always uses the radio group, regardless of option count or `display`.
+    display?: "radio" | "dropdown"; // Requested presentation.
+    optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // Tone per option value; the selected segment of a radio presentation takes its colors.
+  }
+  | ({ kind: "combobox"; id: string; name: string; options: { value: string; label: string; }[]; disabled?: boolean; required?: boolean; hasError?: boolean; placeholder?: string; searchPlaceholder?: string; emptyText?: string; onSearchChange?: (q: string) => void; loading?: boolean; onCreate?: () => void; createLabel?: string; } & ({ multiple?: false; value: string; onChange: (v: string) => void; } | { multiple: true; value: string[]; onChange: (v: string[]) => void; }))
+  | {
+    kind: "money";
+    id: string;
+    name: string;
+    value: number | ""; // Internal format: cents/minor units as an integer (for example, 1299 for 12,99 EUR).
+    onChange: (v: number | undefined) => void;
+    currency?: string; // ISO-4217 currency code, for example "EUR" / "USD" / "CHF".
+    locale?: string; // Locale for number formatting.
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "timestamp";
+    id: string;
+    name: string;
+    value: string; // ISO-8601 datetime string.
+    onChange: (v: string | undefined) => void;
+    wallClock?: boolean; // true = locatedTimestamp (wall-clock without an offset; the server validates z.iso.datetime({local:true})).
+    locale?: string; // Locale for displaying and parsing the date portion.
+    min?: string; // Date bounds as ISO datetimes; they constrain the calendar to day-level granularity.
+    max?: string;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "locatedTimestamp";
+    id: string;
+    name: string;
+    value: { at: string; tz: string; utc?: string; } | ""; // Located-timestamp value: wall-clock `at` (without an offset) plus an IANA `tz`.
+    onChange: (v: { at: string; tz: string; } | undefined) => void;
+    locale?: string; // Locale for the date portion.
+    min?: string; // Date bounds as ISO datetimes; they constrain the calendar.
+    max?: string;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "tz";
+    id: string;
+    name: string;
+    value: string; // IANA zone name, e.g. "Europe/Berlin".
+    onChange: (v: string | undefined) => void;
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+  }
+  | {
+    kind: "textarea";
+    id: string;
+    name: string;
+    value: string;
+    onChange: (v: string) => void;
+    rows?: number; // Visible rows.
+    disabled?: boolean;
+    required?: boolean;
+    hasError?: boolean;
+    placeholder?: string; // Hint text shown when the field is empty (analog to kind:"text").
+    readOnly?: boolean; // Read-only Textarea.
+    onSubmitShortcut?: () => void; // Ctrl/Cmd+Enter submits instead of inserting a newline.
+    dataAttributes?: DataAttributes;
+    onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void; // Raw keydown access (e.g. plain-Enter-submits/Shift+Enter-newline at the field instead of the surrounding Form).
+  }
+;
+type KumikoBuild = {
+  id: string;
+  builtAt: string;
+};
+type KumikoLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & {
+  to: NavTarget;
+};
+type KumikoScreenProps = {
+  schema: FeatureSchema;
+  qn: string;
+  translate?: Translate;
+  entityId?: string;
+  onRowClick?: (row: ListRowViewModel, entityName: string) => void;
+  onCopyLink?: () => Promise<void> | void;
+};
+type LanguageMenuItemsProps = {
+  locales: LocaleOption[];
+  label?: string;
+};
+type LanguageSwitcherProps = {
+  locales: LocaleOption[]; // Selectable locales.
+  icon?: ReactNode; // Icon slot left of the button label.
+  label?: string; // aria-label + title of the trigger.
+  triggerContent?: "code" | "label" | "icon-only"; // What the trigger shows next to the icon: the uppercase code (default), the active locale's label, or the icon only.
+  variant?: "default" | "chip"; // `default`: icon plus code/label button.
+  testId?: string;
+};
+type LiveEvent = {
+  type: string;
+  data: {
+    id?: string; // Absent on anonymous connections: the signal would reveal hidden rows.
+    aggregateType: string;
+    eventType: string;
+    version?: number; // Absent on anonymous connections, like `id`.
+    createdAt: string;
+  };
+};
+type LiveEventSubscriber = (entityName: string, listener: (event: LiveEvent) => void) => () => void; // Subscribes to live events for an entity (aggregateType) and returns the unsubscribe function.
+type LiveEventsProviderProps = {
+  children: ReactNode;
+  value: LiveEventSubscriber;
+};
+type LocaleOption = {
+  code: string; // BCP-47 code, e.g. "de", "en-US", "fr-CA".
+  label: string; // Human-readable label shown in the dropdown.
+};
+type LocaleProviderProps = {
+  resolver: LocaleResolver;
+  fallbackBundles?: TranslationsByLocale[]; // Default bundles supplied by feature plugins.
+  fallbackLocale?: string; // Falls back to fallbackLocale when neither the current-locale nor the key lookup hits in a plugin bundle.
+  children: ReactNode;
+};
+type MenuItemDef =
+  | {
+    kind: "item";
+    id: string;
+    label: string;
+    icon?: ReactNode; // Optional icon displayed before the label (16px).
+    shortcut?: string; // Display-only shortcut hint on the right (monospace, muted).
+    onSelect: () => void;
+    disabled?: boolean;
+    variant?: "default" | "danger"; // "danger" renders the label in red, typically for sign-out or delete actions.
+  }
+  | {
+    kind: "separator";
+  }
+  | {
+    kind: "label";
+    label: string;
+  }
+;
+type ModeSwitchVariant = "outline" | "pill";
+type NavApi = {
+  route: NavRoute | undefined; // Current route — `undefined` when the URL is at the root / there's no route selected.
+  navigate: (target: NavTarget, options?: NavigateOptions) => void; // Push a new route.
+  replace: (target: NavTarget, options?: NavigateOptions) => void; // Replace the current route in place.
+  hrefFor: (target: NavTarget, options?: NavigateOptions) => string; // Build the href a click on {target} would produce.
+  searchParams: Readonly<Record<string, string>>; // Snapshot of the current search params (browser: `?key=value` pairs after the path).
+  setSearchParams: (updates: Readonly<Record<string, string | null>>) => void; // Merges updates into the current search params.
+};
+type NavProviderProps = {
+  children: ReactNode;
+  value: NavApi;
+};
+type NavReparentOverride = {
+  parent: string;
+  order: number;
+};
+type NavRoute = {
+  workspaceId?: string;
+  screenId: string;
+  entityId?: string;
+};
+type NavTarget = ScreenTarget | ObjectTarget;
+type NavTreeProps = {
+  schema: AppSchema | FeatureSchema;
+  user?: {
+    id: string;
+    roles: string[];
+  };
+  testId?: string;
+  allowedNavQns?: ReadonlySet<string>;
+  navBadges?: ReadonlyMap<string, ReactNode>;
+};
+interface NumberFieldProps {
+  label: string;
+  id: string;
+  name: string;
+  value: number | undefined;
+  onChange: (v: number | undefined) => void;
+  required?: boolean;
+  disabled?: boolean;
+  hideLabel?: boolean;
+  testId?: string;
+  grouping?: boolean; // `false` renders without thousands separators (e.g. a year).
+}
+type PdfPreviewSource =
+  | {
+    base64: string;
+  }
+  | {
+    url: string;
+  }
+;
+type PhotoSlotSpec = {
+  id: string;
+  label: string; // The shot this slot asks for ("Front, angled") — the empty slot's caption and the filled thumbnail's alt text.
+  previewUrl?: string; // Set once the app holds the photo; the slot then shows the thumbnail.
+  badge?: string; // Corner tag on a filled slot, e.g. "Cover photo".
+};
+type PhotoSlotsProps = {
+  slots: PhotoSlotSpec[];
+  onUpload: (slotId: string, file: File) => Promise<void>; // Stores the photo for `slotId`.
+  pickHint?: ReactNode; // Second line on an empty slot, e.g. "Camera or gallery".
+  accept?: string[];
+  capture?: "environment" | "user"; // Opens that camera directly on phones; unset keeps camera and gallery.
+  featureFirst?: boolean; // The first slot spans the full row (cover photo).
+  disabled?: boolean;
+  testId?: string;
+};
+type PlanCardActionSlot = {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+};
+type PlanCardLinkSlot = {
+  label: string;
+  href: string;
+  target?: "_blank";
+};
+type PlanCardPrice = {
+  amount: string;
+  period?: string;
+  prefix?: string; // Shown before the amount, e.g. "from" when prices differ per provider.
+  note?: string; // Small line under the price row, e.g. "plus VAT".
+};
+type PlanCardProps = {
+  title: string;
+  description?: string;
+  price?: PlanCardPrice | null; // null renders the price-unavailable state; undefined renders no price row.
+  features?: ReactNode[];
+  current?: boolean;
+  cta?: PlanCardActionSlot;
+  ctaLink?: PlanCardLinkSlot; // Link-styled cta (e.g. contact sales); wins over `cta` when both are set.
+  secondaryAction?: PlanCardActionSlot;
+  variant?: "default" | "compact"; // compact: one-off purchases (e.g. credit packs) — title+price in one row, no feature emphasis, smaller padding.
+  testId?: string;
+};
+type PlanGridProps = {
+  children: ReactNode;
+  testId?: string;
+};
+type PrimitivesProviderProps = {
+  children: ReactNode;
+  value: PrimitivesRegistry;
+};
+type PrimitivesRegistry = CorePrimitives & AppPrimitives;
+type ProfileMenuItem = MenuItemDef;
+type ProfileMenuProps = {
+  user: {
+    id: string;
+    label: string; // Display name or email — the source for initials.
+  };
+  items: ProfileMenuItem[];
+  testId?: string;
+};
+type ProgressListRow = {
+  id: string;
+  label: string;
+  value: string;
+  fraction: number | null; // null renders no bar (nothing to measure against, e.g. an unlimited cap).
+  tone?: "default" | "danger"; // danger colors bar and value.
+  sub?: string; // Small line under the bar, e.g. "42 % repaid".
+};
+type PublicRoute = {
+  path: string; // Exact window.location.pathname match (matched once on mount; every apex page is a full-page reload, no SPA router).
+  component: ReactNode;
+};
+type PublicShellProps = PublicShellCommonProps & ({ variant: "marketing"; notice?: ReactNode; } | { variant: "focus"; progress?: ReactNode; } | { variant: "card"; });
+type PublicShellVariant = "marketing" | "focus" | "card";
+type QueryTableColumn = {
+  field: string;
+  label: string; // Translated header label (resolving the i18n key is the caller's responsibility).
+  type?: string; // Field type for cell formatting.
+};
+type QueryTableProps<TData = unknown> = {
+  query: string; // Dispatcher-Query-Type (`<feature>:query:<entity>:<verb>`).
+  payload?: unknown;
+  live?: boolean; // SSE invalidation — refetches on entity events (useQuery live mode).
+  columns: QueryTableColumn[];
+  rows?: (data: TData) => Readonly<Record<string, unknown>>[]; // Extracts rows from the query result.
+  rowId?: (row: Readonly<Record<string, unknown>>, index: number) => string; // Row ID for keys and row clicks.
+  onRowClick?: DataTableProps["onRowClick"];
+  rowActions?: DataTableProps["rowActions"];
+  emptyState?: ReactNode; // Empty content — defaults to the standard list empty state.
+  toolbarTitle?: ReactNode;
+  toolbarEnd?: ReactNode;
+  testId?: string;
+};
+type RadiusTokens = {
+  sm: string;
+  md: string;
+  lg: string;
+  xl: string;
+};
+interface RangeFieldProps extends FieldBase {
+  value: number;
+  onChange: (v: number) => void;
+  min: number;
+  max: number;
+  step?: number;
+}
+type RenderEditChangeState<TValues extends FormValues> = {
+  values: TValues;
+  changes: Partial<TValues>;
+  dirty: boolean;
+  valid: boolean;
+  submitting: boolean;
+};
+type RenderEditControls<TValues extends FormValues> = {
+  patch: (partial: Partial<TValues>) => void;
+  validate: () => boolean;
+  getValues: () => TValues;
+  submit: () => Promise<void>; // Runs the same pipeline the built-in save button runs: validation, `customSubmit`/`writeCommand`, extension-section persistence, draft discard, state rebase.
+  next: () => void; // Wizard only (no-op elsewhere): validates the current step and advances, like the built-in Next button.
+  back: () => void; // Wizard only (no-op elsewhere): goes back one step without validating.
+};
+type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
+  screen: EntityEditScreenDefinition;
+  i18nScreenId?: string; // Screen id used for the `screen:<id>.title`/`.subtitle` lookups and as the title fallback, when `screen.id` is synthetic (e.g. a secretMint confirm form keeps its own id for the draft key).
+  entity: EntityDefinition;
+  featureName: string;
+  initial: TValues;
+  entityId?: string | null; // Real entity id for extension-section mounts (set-value UI).
+  extensionInitialValues?: Readonly<Record<string, unknown>>; // Already-persisted extension values (e.g. `record.customFields`) for extension-section mounts.
+  writeCommand?: string; // Standard single-write submit path.
+  customSubmit?: (snapshot: FormSnapshot<TValues>) => Promise<SubmitResult<unknown>>; // Override for the submit pipeline.
+  translate?: Translate;
+  ctx?: TCtx;
+  schema?: z.ZodType;
+  onSubmit?: (result: SubmitResult<unknown>, values: TValues) => void; // `values` are the form values at the moment the submit succeeded.
+  payloadMode?: "values" | "changes";
+  buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+  serverFieldPathPrefix?: string; // Prefix to strip from server validation issue paths before mapping them onto form fields — see SubmitConfig.serverFieldPathPrefix.
+  onDelete?: () => Promise<DispatcherError | void> | DispatcherError | void; // Returning the rejected write's error shows it in the form-error banner; returning nothing means the delete went through.
+  onCancel?: () => void;
+  onReload?: () => void;
+  refreshToken?: number; // Bumped by the host after it refetched `initial`.
+  onDirtyChange?: (dirty: boolean) => void; // Fires when the form gains or loses unsaved input (field changes or a dirty extension section).
+  onCopyLink?: () => Promise<void> | void; // Copy-link action — only set in update mode (create mode has no entity id yet, hence no permalink).
+  actions?: RenderEditAction[]; // Header action buttons, rendered before the built-in copy-link/ delete/cancel/save controls.
+  menuActions?: RenderEditAction[]; // Record actions declared with `placement: "menu"`, resolved like `actions`.
+  onRelatedListDrawerAction?: (action: RowActionDrawer, initialValues: Readonly<Record<string, unknown>> | undefined) => void; // Opens a relatedList section row's drawer-kind action.
+  submitLabel?: string; // i18n key for the submit button.
+  submitWithoutChanges?: boolean; // Set by submitPrefilled screens: defined shows the submit button even when no field is editable (all hidden or read-only); `true` also enables it while the form is unchanged.
+  submitVariant?: "primary" | "danger"; // Visual style of the submit button (actionForm `submitStyle`).
+  footerActions?: ActionFormFooterAction[]; // Extra footer buttons (actionForm `footerActions`): each sets its `patch` on the form values, then submits through the normal validate + write path.
+  summary?: {
+    title: string;
+    subtitle?: string;
+  }; // Context box above the drawer form (title + optional subtitle, already resolved).
+  labelAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content inline after the label (e.g. ConfigSourceBadge).
+  fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
+  fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
+  fieldDescription?: (fieldName: string) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
+  fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
+  markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
+  onChange?: (state: RenderEditChangeState<TValues>) => void; // Controlled mode: fires on every values-snapshot change (typing, `patch(...)` from outside) with the current values.
+  onControlsReady?: (controls: RenderEditControls<TValues>) => void; // Controlled mode: called once after mount, hands the caller `patch`/`validate`/`getValues` bound to this RenderEdit instance — addressable from outside without a remount.
+  fields?: string[]; // Renders only these fields (by `field` name from the layout) — section order, title, and visibility still come from the layout, so the caller doesn't duplicate its shape.
+  disabled?: boolean; // Locked state: every rendered field and the submit button go visibly inactive, no write possible.
+  viewMode?: boolean; // Read-only view of an existing record (`EntityEditScreenDefinition.readOnly`): every field is disabled, no submit, discard or dirty footer, and the title resolves `screen:<id>.view.title` first.
+  hideActions?: boolean; // Renders the fields without RenderEdit's own action bar (save, cancel, delete, copy-link).
+  valueDisplay?: "form" | "text"; // "form" (default) — every field renders as its Input widget, disabled when `field.readOnly`, unchanged behavior.
+  hideSectionTitles?: boolean; // Suppresses every section's own title (fields-section header, relatedList Section title) AND the form's own top-level title/subtitle — for a host that already renders that label itself elsewhere (e.g. a tab strip whose label duplicates it, or a page-level header above RenderEdit).
+  fillScreenHeight?: boolean; // Screen body fills the shell height: the form gets `fillHeight` and `stickyActions` (sections scroll, footer pinned).
+  leadContent?: ReactNode; // Rendered first inside the form, above the sections, in the same column and rhythm — for content that belongs to the form but is no field (e.g. the secret a confirm step refers to).
+  submitBlocked?: boolean; // Blocks submit (button and Enter) while fields stay editable — unlike `disabled`, which locks the whole form.
+  formDerivation?: FormDerivationScreen; // actionForm `derive`: derived fields are recomputed into the form state on every change and render read-only.
+  actionFormScreenQn?: string; // QN of the actionForm screen this form renders; its file fields upload as pending for that screen.
+  dirtyFooter?: boolean; // Show the unsaved-changes footer (count, Discard, "Save changes") even without an entity id or a screen-height form — for hosts that edit an existing server-side record through `customSubmit` (configEdit, also when embedded as a dashboard panel).
+  validateOnChange?: boolean; // Validate the edited field right after each change instead of only on submit, so a bounds violation shows at the field while the Save button looks enabled.
+  headerRegion?: ReactNode | ((headerSlot: ReactNode | undefined) => ReactNode); // Extra content rendered above the card, sharing its left padding and width — for a host with its own header region (title/metrics/tabs) that would otherwise render as unpadded siblings before RenderEdit.
+  buildSectionActions?: (actions: RowAction[]) => RenderEditAction[] | undefined; // resolves an `EditFieldsSection`/`EditExtensionSection`/ `EditRelatedListSection`/`EditWriteFormSection`'s own `actions` into already-bound buttons, rendered in that section's title row — same split as `onCopyLink`/header `actions`: RenderEdit has no dispatcher/nav context of its own, so the caller (which does) resolves each RowAction against the record being edited.
+};
+type RenderFieldProps = {
+  field: EditFieldViewModel;
+  issues?: FieldIssue[];
+  onChange: (val: unknown) => void;
+  onSuggest?: (value: string) => void; // Seeds an empty optionsQuery select with the query's default row as a baseline value (not a change).
+  featureName?: string; // Relevant only for type:"reference": the feature name for the lookup query QN (`<feature>:query:<refEntity>:list`).
+  labelAppendix?: ReactNode; // Optional content rendered after the label (for example, ConfigSourceBadge).
+  fieldAppendix?: ReactNode; // Optional content rendered after the input (for example, ConfigCascade).
+  appendixPlacement?: FieldProps["appendixPlacement"];
+  description?: ReactNode;
+  status?: FieldProps["status"];
+  allIssues?: Readonly<Record<string, FieldIssue[]>>; // Flat issues-by-path map (FormSnapshot.errors) — only relevant for type:"embedded" with embeddedListCells, to bucket row-/cell-issues (`${field}.${rowIndex}` / `${field}.${rowIndex}.${cellField}`).
+  valueDisplay?: "form" | "text"; // "form" (default) renders every field as its editable Input, disabled when `field.readOnly` — unchanged behavior.
+  row?: Readonly<Record<string, unknown>>; // Current form values, keyed by field name.
+  changed?: boolean; // Marks the field as modified against the loaded record (edit mode only).
+  layout?: FieldProps["layout"];
+  accent?: boolean;
+  fillDisabled?: boolean; // The surrounding form is locked as a whole: the fill button stays visible but inert, unlike a single readOnly field whose fill button keeps working.
+  hideLabel?: boolean; // Label stays for screen readers only (sr-only).
+};
+type RenderListProps = DataTableTableBlockProps & {
+  screen: EntityListScreenDefinition;
+  entity: Pick<EntityDefinition, "fields" | "derivedFields">;
+  rows: Readonly<Record<string, unknown>>[];
+  featureName: string;
+  translate?: Translate;
+  onRowClick?: (row: ListRowViewModel) => void;
+  emptyState?: ReactNode; // Overrides the default empty box.
+  onCreate?: () => void; // Adds a "+ New" button to the toolbar and uses it as the CTA in the default empty box.
+  createLabel?: string; // Label for the + New button.
+  searchable?: boolean; // Enables a search input in the toolbar.
+  searchPlaceholder?: string; // Placeholder for the search input.
+  description?: string; // Hint at the left of the toolbar (already translated).
+  emptyContent?: ListEmptyStateContent; // Author-declared replacement for the default empty box (already translated).
+  narrowed?: boolean; // Search or filters changed the result; the empty box then says "no matches".
+  defaultFilterActive?: boolean; // Nothing was narrowed by the user, but a default filter is still on; the empty box then offers "show all" instead of "create the first one".
+  itemNounKey?: string; // Plural-forms key for the footer count noun; default is the entity's `:noun` convention key.
+  searchValue?: string; // Current search term (from URL state / the parent).
+  onSearchChange?: (next: string) => void; // Called when the debounced search term changes.
+  sort?: ListSort | null; // Current sorting, or null for the server's default order.
+  onSortChange?: (next: ListSort | null) => void; // Called with the next sort state after a header click.
+  pager?: {
+    page: number;
+    limit: number;
+    total: number;
+    onPageChange: (next: number) => void;
+  }; // Pager props for pagination="pages".
+  onReachEnd?: () => void; // Infinite-scroll wiring for pagination="infinite".
+  loadingMore?: boolean;
+  hasMore?: boolean;
+  rowActions?: DataTableRowAction[]; // Per-row actions in resolved form.
+  rowActionMode?: DataTableRowActionMode; // How the row-action column renders (see `DataTableProps.rowActionMode`).
+  bulk?: DataTableProps["bulk"]; // Forwarded to `DataTableProps.bulk` / `rowTone`.
+  rowTone?: DataTableProps["rowTone"];
+  toolbarActions?: ToolbarActionButton[]; // Toolbar actions in the list header in resolved form.
+  filterFacets?: DataTableFacet[]; // Faceted filter dropdowns.
+  filterValues?: Readonly<Record<string, string[]>>; // Currently selected facet values by field (from URL state).
+  onFilterChange?: (field: string, values: string[]) => void; // Toggles a facet value (sets URL state and refetches).
+  onFilterReset?: () => void; // Reset aller aktiven Facets.
+  dateRangeFacets?: DataTableDateRangeFacet[]; // Time-range filters — forwarded to the DataTable.
+  onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void; // One bound changed (set URL state + refetch).
+  chromeless?: boolean; // Forwarded to `DataTableProps.chromeless` — drops the table's own card frame for a host that already provides one (relatedList in a tabs-mode section).
+  scrollBody?: boolean; // Forwarded to `DataTableProps.scrollBody` — bounds the table height and scrolls rows internally instead of growing the page (relatedList in a tabs-mode section).
+  screenPadding?: boolean; // Forwarded to `DataTableProps.screenPadding` — `true`: the table carries the shared screen padding because it is the screen body (entityList/ projectionList).
+  expandedRowIds?: ReadonlySet<string>; // Forwarded to `DataTableProps.expandedRowIds` / `onToggleRowExpanded` / `renderExpandedRow` (entityList `expandableRow`).
+  onToggleRowExpanded?: (rowId: string) => void;
+  renderExpandedRow?: (row: ListRowViewModel) => ReactNode;
+};
+type ResolverComponent = ComponentType<{ target: TargetRef; onClose: () => void; }>;
+interface ResultColumn<Row> {
+  header: string;
+  align?: "left" | "right";
+  cell: (row: Row) => ReactNode;
+}
+type SectionProps = { // Titled group of fields.
+  id?: string; // DOM id — the scroll target of a form's "on this page" navigation.
+  title?: string; // Optional; without a title, the Section renders only the grouping and no header.
+  subtitle?: ReactNode; // Optional muted subtitle below the title, providing section context rather than only a label (analogous to `FormProps.subtitle`).
+  children: ReactNode;
+  actions?: ReactNode; // Rendered top-right in the title row — never a footer.
+  layout?: "stacked" | "settings-list"; // "settings-list": title + subtitle form a left header column and the children (field rows) the right one on `md:` and up.
+  variant?: "default" | "destructive"; // "destructive" marks the Section as a warning/danger area (e.g. account deletion, restrict processing) — border color only, no content change.
+  testId?: string;
+  icon?: IconKey; // Rendered left of the title, `text-muted-foreground`, same optical size as the title.
+};
+interface SelectFieldProps extends FieldBase {
+  value: string;
+  onChange: (v: string) => void;
+  options: string[] | { value: string; label: string; }[];
+}
+type ShadowTokens = {
+  card: string;
+};
+type SideBySideTableCell = {
+  content: ReactNode;
+  colSpan?: number; // Spans this cell over following columns (a value that is identical on both sides shown once).
+};
+type SideBySideTableColumn = {
+  id: string;
+  label: string;
+};
+type SideBySideTableRow = {
+  id: string;
+  header: ReactNode;
+  cells: SideBySideTableCell[];
+  tone?: "warn"; // Highlights a row that needs attention (e.g. differing values).
+};
+type SidebarBrandProps = {
+  name: string; // Workspace/app name (bold, first line).
+  plan?: string; // Second line — plan, tagline, or tenant (small, dimmed).
+  logo?: ReactNode; // The tile typically contains a Lucide icon.
+  collapsible?: boolean; // Shows the ChevronsUpDown icon only when the app wraps the brand in a dropdown.
+};
+type SidebarProps = {
+  header?: ReactNode; // Header area at the top — typically a workspace avatar, name, and badge.
+  actions?: ReactNode; // Action cluster between the header and nav — typically a "+ Neu" button and search icon.
+  children: ReactNode; // NavTree and free-form sections (e.g. "Your teams" header and sub-items).
+  footer?: ReactNode; // Footer area at the bottom — typically an invite link, help, and plan banner.
+  testId?: string;
+};
+type SidebarUserProps = {
+  name: string;
+  email?: string;
+  avatar?: string; // Avatar URL.
+};
+type SpacingTokens = {
+  card: string;
+};
+type StatDelta = {
+  value: string;
+  direction: "up" | "down";
+  tone?: StatTone;
+};
+type StatTone = DashboardStatTone;
+type StatusBadgeTone = StatusTone | "accent"; // `accent` is a brand-colored call-out (e.g. "3 suggestions"), not a status — hence not part of `StatusTone`, which toasts and select options share.
+type StatusBarEntry = {
+  key: string; // Stable key (z.B.
+  level: number; // Bar height from 0 to 1 (e.g. operational=1, degraded=0.75, outage=0.25).
+  tone: StatusTone;
+  label?: string; // Tooltip text (<title>), supplied translated by the caller.
+};
+type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
+interface TextFieldProps extends FieldBase {
+  value: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+  autoComplete?: string;
+}
+type TextProps = { // Semantic text.
+  variant?: "body" | "small" | "code" | "required-mark" | "muted";
+  decorative?: boolean; // Pure ornament (e.g. a separator glyph): hidden from assistive tech.
+  children: ReactNode;
+  testId?: string;
+};
+interface TextareaFieldProps extends FieldBase {
+  value: string;
+  onChange: (v: string) => void;
+  rows?: number;
+}
+type ThemeMenuItemProps = {
+  lightIcon?: ReactNode;
+  darkIcon?: ReactNode;
+  autoIcon?: ReactNode;
+  titleInDark?: string;
+  titleInLight?: string;
+  titleForAuto?: string;
+  testId?: string;
+};
+type ThemeMode = "light" | "dark";
+type ThemePreference = ThemeMode | "auto"; // "auto" follows the OS color scheme live; light/dark are explicit choices.
+type ThemeToggleProps = {
+  lightIcon?: ReactNode; // Icon for the step to light mode.
+  darkIcon?: ReactNode; // Icon for the step to dark mode.
+  autoIcon?: ReactNode; // Icon for the step to auto mode.
+  titleInDark?: string; // Title/aria-label for the step to light mode.
+  titleInLight?: string; // Title/aria-label for the step to dark mode.
+  titleForAuto?: string; // Title/aria-label for the step to auto mode.
+  testId?: string;
+};
+type TimeseriesHeight = // Pixel height, or one height per viewport class.
+  | number
+  | {
+    narrow: number;
+    wide: number;
+    narrowBelowPx?: number;
+  }
+;
+type TimeseriesPoint = {
+  atMs: number;
+  value: number | null; // null = outage/no value → falls to the baseline for a visible drop.
+};
+type TimeseriesReferenceLine = {
+  value: number; // Same unit as the point values (e.g. a p95 or SLO threshold in ms).
+  label: string; // Translated by the caller.
+  tone?: StatusTone;
+};
+type TimeseriesXAxis = {
+  ticks: number; // Number of evenly spaced time labels (min 2).
+  format: (atMs: number) => string;
+};
+type TimeseriesYAxis = {
+  ticks: number; // Number of gridlines including the zero baseline (min 2).
+  format?: (value: number) => string; // Label text per tick value (unit, locale).
+  unit?: string; // Ready-to-display unit (e.g. "ms"), shown once above the tick labels so `format` can stay unit-free.
+};
+type ToastOptions = {
+  title: string;
+  description?: string;
+  variant?: ToastVariant;
+  docsUrl?: string;
+  docsLinkLabel?: string;
+  requestId?: string;
+};
+type ToastProviderProps = {
+  children: ReactNode;
+};
+type ToastVariant = StatusTone;
+type Tokens = CoreTokens & AppTokens;
+type TokensApi = {
+  tokens: Tokens;
+  mode: ThemeMode; // The scheme currently applied (resolved from the preference when it is "auto").
+  preference?: ThemePreference; // Optional so hand-built TokensApi values (tests, custom providers) stay valid: absent means a plain light/dark implementation, read as `mode`.
+  setPreference?: (preference: ThemePreference) => void;
+  setMode: (mode: ThemeMode) => void; // Explicit choice: leaves "auto".
+  toggleMode: () => void; // Explicit flip of the resolved mode: leaves "auto".
+};
+type TokensProviderProps = {
+  children: ReactNode;
+  value: TokensApi;
+};
+type TopbarProps = {
+  start?: ReactNode;
+  center?: ReactNode;
+  end?: ReactNode;
+  testId?: string;
+};
+type TranslationBundle = Readonly<Record<string, TranslationValue>>; // Map of i18n key → TranslationValue.
+type TranslationsByLocale = Readonly<Record<string, TranslationBundle>>; // Map from locale code (BCP-47, e.g. `"de"`, `"en-US"`) → bundle.
+type UploadZoneProps = {
+  onUpload: (file: File) => Promise<string | undefined | void>; // Uploads a single file (POST + optional follow-up mutation).
+  title: ReactNode;
+  hint?: ReactNode;
+  accept?: string[];
+  multiple?: boolean; // Allow multiple files per pick/drop.
+  capture?: "environment" | "user"; // Forwarded to the file input: a phone opens that camera directly instead of offering camera, gallery and files.
+  disabled?: boolean;
+  testId?: string;
+  describeError?: (cause: unknown) => string; // Turns a failed upload into the row's error text.
+  onRemove?: (value: string) => void; // Controlled use, for a form field: a string returned by `onUpload` becomes the row's value and done rows get a remove button that calls this with it.
+  doneValues?: string[]; // The values the owner currently holds.
+};
+type UseFormOptions<TValues extends FormValues, TCtx = unknown> = FormControllerOptions<TValues, TCtx>;
+type UseFormResult<TValues extends FormValues> = {
+  controller: FormController<TValues>;
+  snapshot: FormSnapshot<TValues>;
+};
+type UseQueryOptions = {
+  enabled?: boolean;
+  live?: boolean;
+  refetchIntervalMs?: number;
+  concurrency?: number;
+};
+type UseQueryResult<TData> = {
+  data: TData | null;
+  error: DispatcherError | null;
+  loading: boolean;
+  refetch: () => Promise<void>;
+};
+type UserRolesProviderProps = {
+  roles: string[] | undefined;
+  children: ReactNode;
+};
+type WorkspaceShellProps = {
+  brand: ReactNode; // Branding / logo on the left side of the topbar.
+  schema: AppSchema | FeatureSchema; // Schema with `workspaces` populated — the engine builds this from registry.getAllWorkspaces() + getWorkspaceNavs().
+  topbarActions?: ReactNode; // Optional topbar end-slot — TenantSwitcher / ThemeToggle / UserMenu.
+  user?: WorkspaceShellUser; // Current user.
+  initialWorkspaceId?: string; // Initial active workspace short id ("admin").
+  sidebarFooter?: ReactNode; // Footer slot at the bottom of the sidebar — profile row, help link, build information.
+  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell.
+  fill?: boolean; // Viewport-fit shell.
+  children: ReactNode; // Screen content.
+};
+type WorkspaceShellUser = {
+  id: string;
+  roles: string[];
+};
+type WorkspaceSwitcherProps = {
+  workspaces: WorkspaceSchema[];
+  activeId: string;
+  onSelect: (workspaceQn: string) => void;
+  testId?: string;
+};
+```
+
+Also exported here, documented in `api/framework-engine.md`: `NavIconKey`
+
+Also exported here, documented in `api/framework-ui-types.md`: `AppSchema`, `FeatureSchema`, `WorkspaceSchema`