@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/agents/api/framework-ui-types.md

@@ -0,0 +1,542 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/ui-types/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/ui-types
+
+Import from `@cosmicdrift/kumiko-framework/ui-types`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown; // Recomputes every derived head field of an action form from its inputs.
+function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): string[]; // Options of a select field that are offered for the given row values, in declaration order.
+function cardColumnRoles<C extends CardRoleColumn>(columns: C[]): CardColumnRoles<C>;
+function computeDerivedCellValue(op: NumericDerivedOp, values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
+function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean; // Evaluates a declarative FieldCondition against the current row/form values.
+function findMissingConditionalRequirements(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): string[]; // Paths of fields (and embedded sub-fields) whose `requiredWhen` holds while the value is missing.
+function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): UnavailableSelectOption[]; // Select values that violate a `conditionalOptions` rule.
+function formalLocaleTag<Locale extends string>(locale: Locale): `${Locale}-x-formal`;
+function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection;
+function isFieldRequired(def: RequiredState, values: Record<string, unknown>): boolean;
+function isFieldVisible(def: FieldStateConditions, values: Record<string, unknown>): boolean;
+function isFormDerivationInputMode(screen: FormDerivationScreen, values: unknown, field: string): boolean; // True when `field` is a `listSum` without `whenEmpty` whose list has no rows: the sum has nothing to add up, so the user types the value.
+function isFormatSpec(r: unknown): r is FormatSpec;
+function isMissingRequiredValue(value: unknown): boolean;
+function isRecordLocked(lockedWhen: FieldCondition | undefined, row: Readonly<Record<string, unknown>>): boolean;
+function isUiAccessGranted(access: AccessRule | undefined, userRoles: string[] | undefined): boolean;
+function isUnchangedValue(a: unknown, b: unknown): boolean;
+function isUnusedFallbackOperand(screen: FormDerivationScreen, values: unknown, field: string): boolean; // True when `field` is only read as a `whenEmpty` operand of `listSum` derivations whose lists all have rows: nothing reads it, so it is locked rather than inviting an input that is silently dropped.
+function isWriteFormEditSection(section: EditSectionSpec): section is EditWriteFormSection;
+function resolveNavParentScreen(screens: ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
+function resolveTranslationValue(value: TranslationValue, locale: string, params?: Readonly<Record<string, unknown>>): string; // Resolve a TranslationValue to display text: a plural entry picks its CLDR category via `Intl.PluralRules` from `params.count`, falling back to `other` when `count` is missing, non-finite, or `locale` is invalid.
+function roundDerivedCellValue(value: number, target: DerivedCellRoundingTarget): number; // Rounds a derived cell's computed value to the precision its target sub-field declares — commercial rounding (round-half-away-from-zero, correct for signed minor-unit money).
+function translationValueOtherText(value: TranslationValue): string; // Text-only reading of a TranslationValue — the CLDR `other` form for a plural entry, or the string as-is.
+function withDerivedCells(row: unknown, derived: Readonly<Record<string, EmbeddedDerivedCellDef>>, targets: Readonly<Record<string, DerivedCellRoundingTarget>>): unknown; // Recomputes every derived cell of an embedded-list row from its raw values, overwriting whatever the client sent instead of merely checking it — the server is the authority for derived cells.
+```
+
+## Constants
+
+```ts
+const ACTION_FORM_ENTITY: "__action-form__"; // Pseudo-entity for actionForm field labels (renderer action-form-shim).
+const ACTION_FORM_PSEUDO_ENTITY: "__action-form__";
+const CARD_META_MAX: 3;
+const LIST_ROW_META_COLUMNS: Readonly<Record<string, ListRowMetaColumnType>>;
+const LIST_ROW_META_REFERENCES: Readonly<Record<string, ListRowMetaReference>>;
+const MAX_BULK_SELECTION: 100; // Most rows one selection can hold; the loaded page caps it further.
+const NO_WIDGET_FIELD_TYPES: FieldDefinition["type"][];
+const PROJECTION_DETAIL_ENTITY: "__projection-detail__"; // Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim).
+const REFERENCE_LOOKUP_SOURCES: Readonly<Record<string, ReferenceLookupSource>>;
+const SYSTEM_REFERENCE_LABELS: Readonly<Record<string, SystemReferenceLabel>>;
+const UNRESOLVED_REFERENCE_LABEL_KEYS: Readonly<Record<string, string>>;
+const WRITE_FORM_SECTION_ENTITY: "__write-form-section__"; // Pseudo-entity for a projectionDetail writeForm section's own fieldDefs (distinct from PROJECTION_DETAIL_ENTITY — the section's fields aren't drawn from the host record's display entity).
+```
+
+## Types
+
+```ts
+type ActionFormFooterAction = {
+  id: string; // Stable id (kebab-case), used for the test id.
+  label: string; // i18n key.
+  icon?: IconKey;
+  variant?: "primary" | "secondary" | "danger"; // Button style.
+  patch: Readonly<Record<string, string | number | boolean | null>>; // Form values set before the submit.
+};
+type ActionFormLoad = {
+  query: string; // Query QN that returns the record.
+  idParam?: string; // Payload key carrying the record id (default "id").
+  singleton?: boolean; // The query picks the row from the caller's tenant/session context, so the form loads without a record id and the query is called WITHOUT `idParam` (same semantics as `ProjectionDetailScreenDefinition.singleton`).
+};
+type ActionFormRedirect = { // Redirect target plus the success-payload field carrying the navigation id.
+  screen: string; // Same target forms as the string `redirect`: short screen ID (same-feature) or a fully-qualified cross-feature screen QN.
+  idFrom: string; // Flat field name in the handler's success payload, e.g. "leaseId".
+  tab?: string; // Section id to open on the target `projectionDetail` with `layout.mode: "tabs"` (the `tab` search param, same as `ToolbarAction` navigate `tab`).
+};
+type ActionFormSuccessFact = { // One key figure of the success box, read from the handler's success payload.
+  field: string; // Flat field name in the handler's success payload.
+  label: string; // Label (i18n key).
+};
+type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & { // A redirect target rendered as a link in the success box.
+  idFrom?: string; // Success-payload field carrying the navigation id.
+  label: string; // Link text (i18n key).
+};
+type AppSchema = {
+  features: FeatureSchema[];
+  workspaces?: WorkspaceSchema[];
+};
+type CustomScreenDefinition = {
+  id: string;
+  type: "custom";
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  renderer: PlatformComponent;
+  routes?: CustomScreenRoute[];
+  listScreenId?: string; // Parent list screen for breadcrumb when this detail is not in nav.
+  access?: AccessRule;
+  dormant?: boolean; // This screen is registered without a self-owned `r.nav()` entry by design — an app opts in by navving it explicitly (e.g. a settings-area self-service screen).
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+};
+type DashboardChartMarkerKind = { // Look of the markers whose `kind` matches: a dashed guide line through the plot plus a colored pin.
+  tone?: DashboardChartTone;
+  color?: string;
+  label?: string; // i18n key; with `markerLegend: "legend"` the chart legend lists the markers of this kind under it.
+};
+type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+  kind: "chart";
+  id: string;
+  label: string;
+  chart: DashboardChartKind;
+  query: string;
+  subtitle?: string; // i18n key under the title, e.g. "7 days, by creation day".
+  seriesTones?: Readonly<Record<string, DashboardChartTone>>; // Series/segment/line key -> tone; unmapped keys fall back to a palette.
+  seriesColors?: Readonly<Record<string, string>>; // Series/segment/line key -> raw CSS color (e.g. "var(--color-debt)"); wins over `seriesTones`.
+  valueFormat?: DashboardCurrencyFormat; // Formats values as currency (minor units): y ticks, legend totals and tooltips on stacked-bars/segment-bars/stacked-area, only the y ticks on timeseries.
+  unit?: string; // i18n key of a unit label.
+  scrollable?: boolean; // Only for chart "stacked-area": fixed width per bucket, plot scrolls horizontally.
+  markerKinds?: Readonly<Record<string, DashboardChartMarkerKind>>; // Only for chart "stacked-area": marker `kind` -> look.
+  legendTotals?: boolean; // Only for chart "stacked-area": false hides the per-series sums in the legend (they mean nothing for balances).
+  ranges?: DashboardChartRanges; // Only for chart "stacked-area": range switch in the panel header.
+  brush?: boolean; // Only for chart "stacked-area": scrubber under the plot to drag the visible window; starts at today.
+  dateFormat?: "day" | "month"; // Only for chart "stacked-area": date format of axis and marker labels.
+  initialWindow?: "default-range" | "from-today"; // Only for chart "stacked-area": window the uncontrolled chart starts in.
+  markerLegend?: "list" | "legend"; // Only for chart "stacked-area": "legend" drops the numbered marker list; pins become plain dots with a tooltip and the legend lists marker kinds (see `markerKinds[].label`).
+  markerLabels?: boolean; // Only for chart "stacked-area": true writes each marker label vertically next to its guide line on wide panels; narrow panels keep the pins.
+};
+type DashboardCurrencyFormat = { // Chart/stat values are minor units, formatted with the user locale.
+  kind: "currency";
+  currency: string;
+  fractionDigits?: number; // Defaults to the currency's own decimals.
+};
+type DashboardDateParam = { // Epoch ms, rendered as a medium date in the user time zone.
+  kind: "date";
+  atMs: number;
+};
+type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+  kind: "feed";
+  id: string;
+  label: string;
+  query: string;
+};
+type DashboardFilterDefinition = {
+  id: string;
+  label: string;
+  kind: "select";
+  placeholder?: string;
+  allLabel?: string; // i18n key for the "(all)" entry.
+  options?: { value: string; label: string; }[];
+  optionsQuery?: string; // Query-Result-Contract: `{ rows: { value: string; label: string }[] }`.
+};
+type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+  kind: "list";
+  id: string;
+  label: string;
+  query: string;
+  columns: ListColumnSpec[];
+};
+type DashboardMoneyParam = { // Minor units (like Money fields), formatted with the user locale.
+  kind: "money";
+  amountMinor: number;
+  currency: string;
+};
+type DashboardPanelDefinition = DashboardStatPanel | DashboardStatGroupPanel | DashboardChartPanel | DashboardListPanel | DashboardFeedPanel | DashboardProgressListPanel | DashboardTextPanel | DashboardCustomPanel | DashboardScreenPanel;
+type DashboardPanelEmptyState = {
+  span?: DashboardPanelSpan;
+  emptyLabel?: string;
+  emptyHint?: string; // Second line under `emptyLabel`.
+};
+type DashboardPanelQueryOptions = {
+  params?: Readonly<Record<string, unknown>>; // Static, author-set query parameters merged on top of the screen's dynamic filterParams — lets a panel pin a value (e.g. a status facet) the screen-wide filter doesn't cover, without needing its own query.
+  ignoreScreenFilter?: boolean; // The screen `filter` value is NOT merged into this panel's query (a tenant picker must not hit sources without a tenant column).
+};
+type DashboardPanelSpan = "half" | "full";
+type DashboardPanelVisibility = {
+  query: string;
+  field: string;
+  eq: string | number | boolean | null;
+};
+type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+  kind: "progress-list";
+  id: string;
+  label: string;
+  query: string;
+};
+type DashboardProgressTone = "default" | "danger";
+type DashboardRefresh = // Polling of the record and all panel queries, never faster than DASHBOARD_MIN_REFRESH_SECONDS.
+  | {
+    seconds: number;
+  }
+  | {
+    field: string;
+  }
+;
+type DashboardRelativeTimeParam = { // Epoch ms, rendered relative to now ("5 minutes ago", "in 30 seconds") in the user locale; the text keeps ticking while it is on screen.
+  kind: "relativeTime";
+  atMs: number;
+};
+type DashboardScopeDefinition = {
+  badge: string;
+  notice?: string;
+};
+type DashboardScreenDefinition = {
+  id: string;
+  type: "dashboard";
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  panels: DashboardPanelDefinition[];
+  record?: DashboardRecordBinding; // Binds the dashboard to one record via a URL search param, see DashboardRecordBinding.
+  actions?: RowAction[]; // Header actions on the bound record (writeHandler, navigate, clientAction).
+  refresh?: DashboardRefresh;
+  filter?: DashboardFilterDefinition;
+  timeRange?: DashboardTimeRangeDefinition; // Segmented control in the toolbar; the value lives in URL search param `id` and is merged into EVERY panel query (also ignoreScreenFilter ones).
+  scope?: DashboardScopeDefinition; // Marks the screen as spanning more than the caller's own scope.
+  showUpdatedAt?: boolean; // Show the "Updated at" timestamp in the toolbar.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type DashboardScreenPanel = {
+  kind: "screen";
+  id: string;
+  screen: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>`.
+  label?: string;
+  visibleWhen?: DashboardPanelVisibility;
+  fallback?: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` embedded in this panel's place when `visibleWhen` is unmet or its query fails (nothing while it loads).
+  chromeless?: boolean; // Render the embedded form without its own card frame and padding, aligned to the dashboard's page grid like a standalone settings screen.
+};
+type DashboardStatGroupPanel = DashboardPanelGate & {
+  kind: "stat-group";
+  id: string;
+  label?: string;
+  subtitle?: string; // i18n key, a line under `label`; the boot validator requires `label`.
+  span?: DashboardPanelSpan;
+  stats: DashboardStatPanel[];
+};
+type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
+  kind: "stat";
+  id: string; // Stable id: kebab-case, unique within the panel set.
+  label: string; // Display text (i18n key).
+  query: string;
+  valueField: string;
+  subField?: string;
+  toneField?: string;
+  valueFormat?: DashboardValueFormat; // Formats a numeric value as currency (minor units) or, with `relativeTime`, as a ticking "5 minutes ago" from epoch ms; ignored for string values.
+  tone?: DashboardStatTone; // Fixed tone when `toneField` is unset or yields none; not applied while the value is 0.
+  sparklineField?: string; // Record field holding `{ atMs, value | null }[]` (MetricResult.points), drawn as a sparkline next to the value.
+  deltaField?: string; // Delta chip (e.g. "↓23 %") next to the label.
+  deltaDirectionField?: string;
+  deltaToneField?: string;
+  icon?: PlatformComponent; // Static icon next to the label.
+  accentColor?: string; // Static CSS color value (e.g. "var(--color-debt)") for the icon chip, passed straight to the tile without a registry lookup.
+};
+type DashboardText = string | DashboardI18nText; // Plain string is displayed as-is; DashboardI18nText is translated by the renderer.
+type DashboardTextBlock =
+  | {
+    kind: "heading";
+    text: string;
+  }
+  | {
+    kind: "paragraph";
+    text: string;
+    emphasis?: "muted" | "strong"; // Default "muted", like body copy inside panels.
+  }
+  | {
+    kind: "list";
+    items: string[];
+  }
+  | {
+    kind: "code";
+    code: string;
+  }
+  | {
+    kind: "hint";
+    text: string;
+  }
+  | {
+    kind: "link";
+    text: string; // Link label (i18n key).
+    screen: string; // Same-feature short id or cross-feature QN `<feature>:screen:<id>`.
+    roles?: string[]; // Show the link only to users holding one of these roles.
+  }
+;
+type DashboardTextPanel = DashboardPanelGate & {
+  kind: "text";
+  id: string;
+  label?: string; // Panel title (i18n key).
+  span?: DashboardPanelSpan;
+  blocks: DashboardTextBlock[];
+};
+type DashboardTextParam = string | number | DashboardI18nText | DashboardMoneyParam | DashboardDateParam | DashboardRelativeTimeParam; // Nested DashboardI18nText params resolve first (e.g. a duration "{years} {months}" with one plural key each); numbers stay raw so plural rules can read `count`.
+type DashboardTimeRangeDefinition = {
+  id: string;
+  options: { value: string; label: string; }[]; // `label` is an i18n key.
+  default: string;
+};
+type DerivedCellRoundingTarget = {
+  type: EmbeddedSubFieldDef["type"];
+  scale?: number;
+};
+type EditExtensionSection = {
+  id?: string; // Kebab-case tab id, used as the `?tab=` value.
+  kind: "extension";
+  title: string;
+  component: PlatformComponent;
+  contributesToFormSubmit?: boolean; // When true, the extension registers via `useExtensionFormSubmit` and the surrounding form's Save button should activate for its dirty state.
+  entityName?: string; // Overrides the host-derived entity name passed to the mounted component.
+  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
+};
+type EditFieldsSection = EditFieldsSectionBase & ({ fields: EditFieldSpec[]; } | { groups: EditFieldGroup[]; }); // Either a flat `fields` grid or titled `groups` cards, never both: the groups branch has no `fields` key, so a raw `.fields` read on a section does not compile — use `sectionFieldSpecs`.
+type EditLayout = {
+  sections: EditSectionSpec[];
+  width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
+  mode?: "single" | "wizard" | "tabs"; // Default "single".
+  variant?: "form" | "settings-list"; // "settings-list" lays each section out as a band with a title column on the left and one hairline-separated row per field (label + help left, control right) — the familiar settings pattern, for screens that are a list of independent preferences rather than one record form.
+  draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
+  wizard?: {
+    aside?: {
+      upNext: true;
+    };
+  }; // Wizard layouts only.
+};
+type EditWriteFormSection = {
+  id?: string; // Kebab-case tab id, used as the `?tab=` value.
+  kind: "writeForm";
+  title?: string;
+  description?: string;
+  columns?: number;
+  icon?: IconKey;
+  fieldDefs: Readonly<Record<string, FieldDefinition>>; // Field-type map for this section's own form — same shape as `ActionFormScreenDefinition.fields`.
+  fields: EditFieldSpec[]; // Rendered fields, in order — same shape as `EditFieldsSection.fields`.
+  handler: string; // Write-handler QN dispatched on submit.
+  submitLabel?: string; // i18n-key for the submit button.
+  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
+};
+type EmbeddedDerivedCellDef = ({ op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; } | { op: "inRange"; from: string[]; inside: string; outside: string; }) & { // A cell computed from other cells of the same row.
+  when?: Exclude<FieldCondition, boolean>; // Row-level condition on a sibling sub-field.
+};
+type EmbeddedListEditSpec = {
+  readOnlyCells?: string[]; // Sub-fields shown as read-only cells; every other cell stays editable.
+  cardHiddenCells?: string[]; // Sub-fields that only steer a row (e.g. the kind that decides which controls appear) and are not shown on phone cards; the desktop table still shows them.
+  fixedRows?: boolean; // `true` keeps the rows as they are: no add, remove, duplicate, move or paste-appended rows.
+};
+type EntityEditAction = RowAction & {
+  placement?: EntityEditActionPlacement;
+};
+type EntityListFacetConfig = {
+  display?: "select" | "chips" | "range"; // `"select"` (default): dropdown with checkboxes.
+  showCounts?: boolean; // Chips show how many rows each option matches (other facets and the search apply).
+  hideEmpty?: boolean; // Chips with zero matching rows are not shown.
+  extraOptions?: EntityListFacetExtraOption[];
+};
+type FeatureSchema = {
+  featureName: string;
+  entities: Readonly<Record<string, EntityDefinition>>;
+  screens: ScreenDefinition[];
+  navs?: NavDefinition[];
+  contentCollections?: QualifiedContentCollection[];
+  translations?: TranslationKeys;
+  workspaces?: WorkspaceSchema[];
+  searchAdapterMissing?: boolean;
+  queryLiveEntities?: Readonly<Record<string, string[]>>;
+};
+type FieldAffix =
+  | string
+  | {
+    field: string;
+  }
+;
+type FieldFillAction = {
+  label: string; // i18n key (falls back to the literal) of the button label.
+  query: string; // Qualified query name, run with the current form values picked by `params`.
+  field: string; // Key in the query result written into the field; the value must be a string or a number, anything else counts as a failed fill.
+  params?: RowFieldExtractor; // Form fields sent as the query payload (none: an empty payload).
+};
+type FieldIconKey = "mail" | "lock" | "hash" | "search" | "user" | "phone" | "calendar" | "link" | "tag" | "building" | "globe" | "key" | "map-pin";
+type FieldRenderer = PlatformComponent | string | FormatSpec;
+type FormDerivationScreen = {
+  fields: Readonly<Record<string, FormFieldDefinition>>;
+  derive?: Readonly<Record<string, FormFieldDerivation>>;
+};
+type FormWidth = "3xl" | "4xl" | "full";
+type Formality = "formal" | "informal";
+type IconKey = NavIconKey;
+type ListBulkAction = { // An action that runs a writeHandler row action once per checkbox-selected row.
+  id: string; // Stable id, kebab-case, unique among the screen's bulk actions.
+  rowAction: string; // Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`.
+  confirm?: string; // i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`.
+};
+type ListEmptyStateSpec = { // Replacement for the default "no rows" box of a list.
+  title: string;
+  description?: string;
+  action?: RowAction;
+};
+type ListSortSpec = {
+  field: string;
+  dir: ListSortDir;
+};
+type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
+type ParsedRefTarget = {
+  featureName: string;
+  entityName: string;
+};
+type PlatformComponent = {
+  react?: unknown;
+  native?: unknown;
+};
+type QualifiedContentCollection = ContentCollectionDefinition & {
+  navQn: string;
+};
+type RecordHeaderSubtitlePart =
+  | string
+  | {
+    field: string;
+    navigate?: MetricNavigate;
+  }
+;
+type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
+  variants?: RelatedListEmptyStateVariant[];
+};
+type RelatedListEmptyStateVariant = { // Empty-state text for one parent-record state, e.g. "still running" vs.
+  when: Exclude<FieldCondition, boolean>;
+  title: string;
+  description?: string;
+};
+type RelatedListRowTone = Exclude<FieldCondition, boolean> & { // Row tint rule: rows where the `FieldCondition` (`{ field, eq }`, `{ field, in }` …) holds get the tone.
+  tone: SelectOptionTone;
+};
+type RelatedListToolbarAction = (Extract<ToolbarAction, { kind: "navigate"; }> & { visible?: FieldCondition; params?: RowFieldExtractor; }) | (Extract<ToolbarAction, { kind: "writeHandler"; }> & { visible?: FieldCondition; params?: RowFieldExtractor; }) | (Extract<ToolbarAction, { kind: "drawer"; }> & { visible?: FieldCondition; params?: RowFieldExtractor; });
+type RowActionClientAction = {
+  kind: "clientAction";
+  id: string;
+  label: string;
+  action: string; // Registered client handler name, `<feature>:<kebab>`, e.g. "auth-email-password:request-password-reset".
+  payload?: RowFieldExtractor; // Payload handed to the handler, picked from the row (or the shown record).
+  confirm?: string; // i18n key for the confirm dialog description.
+  confirmLabel?: string; // i18n key for the confirm button, default `label`.
+  visible?: FieldCondition; // Conditional visibility per row.
+  style?: "primary" | "secondary" | "danger"; // Visual style.
+  icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
+  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
+  successMessage?: string; // i18n key of the toast shown after the handler reported `{ ok: true }` (default `kumiko.clientAction.success`).
+};
+type RowActionDisplay = "button" | "link" | "icon" | "responsive"; // How a row action renders inline in the row-action column.
+type RowActionDrawer = {
+  kind: "drawer";
+  id: string;
+  label: string;
+  screen: string; // Short, unqualified id of an `actionForm` screen in the same feature.
+  params?: RowFieldExtractor; // Declarative prefill extracted from the clicked row.
+  visible?: FieldCondition; // Per-row conditional visibility.
+  style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
+  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
+  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
+  title?: string; // Drawer heading (i18n key) instead of the action `label`.
+  subtitle?: string; // Line under the drawer heading (i18n key or a bare `{name}` template), resolved like `title`.
+  rowClick?: boolean; // Clicking the row opens this drawer with that row's `params`.
+};
+type RowActionMode = "adaptive" | "inline"; // Row-action column layout.
+type RowActionNavigate = RowActionNavigateBase & ({ screen: string; entity?: never; } | { entity: string; screen?: never; }); // Exactly one of `screen` / `entity` — mutual exclusivity is type-enforced (boot validator still rejects both/neither for untyped schemas).
+type RowFieldExtractor = // Declarative row-field extractor — JSON-safe (no function prop, survives GET /api/schema / buildAppSchema).
+  | {
+    pick: string[];
+  }
+  | {
+    map: Readonly<Record<string, string>>;
+  }
+;
+type ScreenFallback = string | ScreenFallbackByReason; // Screen-level `fallback`: one screen for every reason, or one per reason.
+type ScreenFallbackByReason = { [Reason in ScreenFallbackReason]?: string; }; // Per-reason fallback screens (same-feature short id or cross-feature QN).
+type ScreenFallbackReason = "hidden" | "forbidden" | "notFound" | "error"; // Why a screen gate is not open.
+type ScreenSlots = {
+  header?: PlatformComponent;
+  titleAction?: PlatformComponent; // entityEdit / actionForm: rendered on the right of the form title, same row.
+  beforeForm?: PlatformComponent;
+  afterForm?: PlatformComponent;
+  sidebar?: PlatformComponent;
+  footer?: PlatformComponent;
+  footerPrimary?: boolean; // entityEdit wizard: marks `footer` as the sticky-footer primary action (pinned `max-sm:fixed` group on mobile) instead of the non-sticky secondary bucket it falls into by default alongside Back/Cancel.
+  toolbar?: PlatformComponent;
+};
+type ScreenVisibility = DashboardPanelVisibility & {
+  idParam?: string; // Payload key that receives the screen's route id (projectionDetail only).
+};
+type SecretMintConfirmStep = { // Post-reveal proof-of-receipt step.
+  handler: string; // Write-handler QN dispatched when the confirm form is submitted.
+  fields: Readonly<Record<string, FormFieldDefinition>>;
+  layout: EditLayout;
+  carry?: string[]; // Mint success-payload fields merged into the confirm payload (e.g. a short-lived setup token).
+  submitLabel?: string;
+  doneMessage?: string; // i18n key for the banner shown after a successful confirm when the screen declares no `redirect`.
+};
+type SecretsEditScreenDefinition = {
+  id: string;
+  type: "secretsEdit";
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  secretKeys: Readonly<Record<string, string>>; // field id -> qualified secret name (`<feature>:secret:<kebab>`).
+  fieldLabels: Readonly<Record<string, string>>; // field id -> i18n key for the label.
+  fieldHints?: Readonly<Record<string, string>>; // field id -> i18n key for the hint, only where the declaration carries one.
+  requiredFields?: string[]; // field ids whose declaration set `required: true`.
+  fieldAccess?: Readonly<Record<string, AccessRule>>; // field id -> write access derived from the key's `writeRoles`.
+  sections: SecretsEditSection[];
+  access?: AccessRule;
+};
+type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
+type TextFieldDef = PiiAndFieldState & {
+  type: "text";
+  description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
+  maxLength?: number;
+  minLength?: number; // Lower bound enforced by the generated write schema, so short input is rejected by validation instead of reaching the handler.
+  autoComplete?: string; // HTML `autocomplete` token for the rendered input (e.g. "one-time-code"), so browsers and password managers offer or suppress autofill correctly.
+  required?: boolean;
+  searchable?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean; // Allows screen filters on this field.
+  encrypted?: boolean;
+  sensitive?: boolean;
+  writeOnly?: boolean; // Write-only secret (API key): the value is never returned to clients.
+  readAsInstruction?: boolean; // A later run reads this field's value as an instruction — prompt, rule, template.
+  format?: "email" | "url" | "phone" | "password" | "month" | "iban"; // "password" is a pure render hint (masked input) — no storage semantics.
+  default?: string;
+  access?: FieldAccess;
+  multiline?: boolean | { rows?: number; }; // Multiline text causes DefaultInput to render a <textarea> instead of <input type="text">.
+};
+type TranslationValue = string | PluralForms;
+type WorkspaceSchema = {
+  definition: WorkspaceDefinition;
+  navMembers: string[];
+};
+```
+
+Also exported here, documented in `api/framework-engine.md`: `AccessRule`, `ActionFormScreenDefinition`, `ConfigEditScreenDefinition`, `DashboardCustomPanel`, `DashboardI18nText`, `EditFieldSpec`, `EditRelatedListSection`, `EditSectionSpec`, `EntityDefinition`, `EntityEditScreenDefinition`, `EntityListScreenDefinition`, `FieldCondition`, `FieldDefinition`, `ListColumnSpec`, `ListFacetSpec`, `ListTableOptions`, `MetricNavigate`, `NavDefinition`, `NavIconKey`, `ProjectionDetailScreenDefinition`, `ProjectionListScreenDefinition`, `RowAction`, `RowActionWriteHandler`, `ScreenDefinition`, `SecretMintScreenDefinition`, `TargetRef`, `ToolbarAction`, `TreeAction`, `WorkspaceDefinition`, `handlerFieldLabelKey`, `handlerTitleKey`, `isFieldsEditSection`, `isOpenToAllGranted`, `normalizeEditField`, `normalizeListColumn`, `parseRefTarget`, `sectionFieldSpecs`