@cosmicdrift/kumiko-framework 0.414.0 → 0.415.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/agents/api/framework-engine.md +9 -3
  2. package/agents/api/framework-errors.md +1 -1
  3. package/agents/api/framework-ui-types.md +10 -1
  4. package/agents/api/renderer-web.md +20 -3
  5. package/agents/api/types.md +47 -14
  6. package/agents/api.md +2 -2
  7. package/agents/boot-rules.md +7 -5
  8. package/agents/examples/crypto-shredding-hr.md +63 -1
  9. package/agents/examples/record-detail-layout.md +113 -7
  10. package/agents/widgets.md +7 -0
  11. package/dist/api/request-context-internals.d.ts +2 -0
  12. package/dist/api/request-context-scopes.js +9 -2
  13. package/dist/api/request-context.js +1 -1
  14. package/dist/api/routes.js +4 -4
  15. package/dist/api/server-event-dispatcher.js +3 -0
  16. package/dist/db/parent-ref-clause.js +31 -3
  17. package/dist/db/parent-ref-global-hosts.d.ts +4 -1
  18. package/dist/db/parent-ref-global-hosts.js +50 -12
  19. package/dist/db/queries/rls-boot-catalog.js +5 -6
  20. package/dist/db/queries/rls-shape.d.ts +1 -0
  21. package/dist/db/queries/rls-shape.js +21 -6
  22. package/dist/engine/boot-validator/boot-rules.d.ts +16 -6
  23. package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts +2 -2
  24. package/dist/engine/boot-validator/card-meta-overflow-rules.js +2 -2
  25. package/dist/engine/boot-validator/card-meta-overflow.js +7 -5
  26. package/dist/engine/boot-validator/entity-list-screens.js +2 -7
  27. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +2 -2
  28. package/dist/engine/boot-validator/list-row-guidance-rules.js +2 -2
  29. package/dist/engine/boot-validator/list-row-guidance.js +15 -1
  30. package/dist/engine/boot-validator/list-sort-summary-rules.d.ts +2 -2
  31. package/dist/engine/boot-validator/list-sort-summary-rules.js +2 -2
  32. package/dist/engine/boot-validator/list-sort-summary.js +31 -20
  33. package/dist/engine/boot-validator/list-toolbar-options.js +3 -4
  34. package/dist/engine/boot-validator/named-filter-rules.d.ts +10 -0
  35. package/dist/engine/boot-validator/named-filter-rules.js +10 -0
  36. package/dist/engine/boot-validator/projection-list-screens.js +5 -4
  37. package/dist/engine/boot-validator/query-output-guidance.js +1 -0
  38. package/dist/engine/boot-validator/query-refs.js +10 -0
  39. package/dist/engine/boot-validator/screens-actions.js +1 -1
  40. package/dist/engine/named-filter-roles.js +6 -14
  41. package/dist/engine/schema-builder.js +3 -1
  42. package/dist/engine/soft-delete-cleanup.js +2 -0
  43. package/dist/errors/reasons.d.ts +1 -0
  44. package/dist/errors/reasons.js +4 -0
  45. package/dist/i18n/required-surface-keys.js +2 -1
  46. package/dist/jobs/job-runner-execution.js +3 -0
  47. package/dist/jobs/job-runner-types.d.ts +1 -0
  48. package/dist/jobs/job-runner.js +8 -0
  49. package/dist/pipeline/context-services.d.ts +1 -1
  50. package/dist/pipeline/context-services.js +1 -1
  51. package/dist/pipeline/event-dispatcher-delivery.js +3 -0
  52. package/dist/pipeline/event-dispatcher.d.ts +2 -0
  53. package/dist/pipeline/handler-context-phase-denials.js +1 -1
  54. package/dist/pipeline/irreversible-operation-gate.js +36 -10
  55. package/dist/search/meilisearch-adapter-internals.d.ts +2 -0
  56. package/dist/search/meilisearch-adapter-internals.js +5 -0
  57. package/dist/search/meilisearch-adapter.d.ts +1 -0
  58. package/dist/search/meilisearch-adapter.js +3 -2
  59. package/dist/ui-types/card-column-roles.d.ts +2 -0
  60. package/dist/ui-types/card-column-roles.js +15 -0
  61. package/dist/ui-types/index.d.ts +2 -2
  62. package/dist/ui-types/index.js +1 -1
  63. package/package.json +3 -3
  64. package/presets/biome-plugins/no-date-api.grit +3 -1
  65. package/presets/biome-plugins/no-direct-fetch.grit +1 -1
  66. package/presets/biome-plugins/unsafe-json-parse.grit +7 -1
  67. package/presets/biome-rules.json +12 -10
  68. package/src/changes.json +57 -0
@@ -670,10 +670,10 @@ type EntityListScreenDefinition = {
670
670
  namedFilterFacet?: NamedFilterFacetOptions; // Presentation of `namedFilters` in the toolbar; needs `namedFilters`.
671
671
  emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
672
672
  createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
673
- createPlacement?: "header" | "toolbar"; // "toolbar": from `sm` up the create button ends the filter row instead of standing in the header.
673
+ createPlacement?: "header" | "toolbar"; // "toolbar": from `md` up (below md the compact header keeps its "+") the create button ends the filter row instead of standing in the header.
674
674
  toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
675
675
  narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
676
- toolbarActionsPlacement?: "header" | "toolbar"; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
676
+ toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header.
677
677
  itemNounKey?: string; // i18n key of the plural noun for the list size in the phone sort line (`{count}` pluralised).
678
678
  searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
679
679
  searchable?: boolean;
@@ -1002,6 +1002,7 @@ type JobDefinition = {
1002
1002
  escapeHatch?: EscapeHatchDeclaration | undefined;
1003
1003
  tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
1004
1004
  tenantVisibleRun?: { subjectFields?: string[] | undefined; } | undefined;
1005
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler | undefined;
1005
1006
  };
1006
1007
  type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
1007
1008
  type JobEvents = Pick<HandlerEvents, "append" | "load">;
@@ -1051,6 +1052,7 @@ type ListColumnSpec =
1051
1052
  emptyPlaceholder?: false; // `false` leaves an empty cell blank instead of drawing the "—" placeholder.
1052
1053
  hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
1053
1054
  showOnNarrowOnly?: true; // Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
1055
+ narrowInline?: true; // In the compact card, consecutive `narrowInline` columns stand side by side on one line (12px gap, no separator) instead of one line each.
1054
1056
  hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
1055
1057
  pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
1056
1058
  width?: number; // Start width in px.
@@ -1068,12 +1070,14 @@ type ListFacetSpec =
1068
1070
  field: string;
1069
1071
  type: "select";
1070
1072
  label: string;
1073
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1071
1074
  options: { value: string; label: string; }[];
1072
1075
  }
1073
1076
  | {
1074
1077
  field: string;
1075
1078
  type: "boolean";
1076
1079
  label: string;
1080
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1077
1081
  trueLabel: string;
1078
1082
  falseLabel: string;
1079
1083
  }
@@ -1081,6 +1085,7 @@ type ListFacetSpec =
1081
1085
  field: string;
1082
1086
  type: "reference";
1083
1087
  label: string;
1088
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field.
1084
1089
  entity: string; // Entity name (same feature) or `feature:entity` (cross-feature), same convention as `ListColumnSpec.refEntity`.
1085
1090
  labelField?: string; // Row field on the referenced entity shown as the option label (default "id").
1086
1091
  }
@@ -1178,6 +1183,7 @@ type MultiStreamProjectionDefinition = {
1178
1183
  runIn?: RunIn;
1179
1184
  delivery?: "shared" | "per-instance";
1180
1185
  startFrom?: "beginning" | "now";
1186
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
1181
1187
  };
1182
1188
  type NavDefinition = {
1183
1189
  id: string;
@@ -1412,7 +1418,7 @@ type ProjectionListScreenDefinition = {
1412
1418
  rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
1413
1419
  bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
1414
1420
  toolbarActions?: ToolbarAction[];
1415
- toolbarActionsPlacement?: "header" | "toolbar"; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select, instead of standing in the page header.
1421
+ toolbarActionsPlacement?: ListToolbarActionsPlacement; // "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select, instead of standing in the page header.
1416
1422
  toolbarSort?: true; // From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable.
1417
1423
  narrowFacets?: ListNarrowFacets; // "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged.
1418
1424
  pagination?: ListPaginationMode;
@@ -20,7 +20,7 @@ function writeFailure(err: KumikoError): WriteFailure;
20
20
  ## Constants
21
21
 
22
22
  ```ts
23
- const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
23
+ const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; irreversibleOperationWithoutEntryHandler; subjectErased; fileRejected; fileViolatesBindTarget };
24
24
  const frameworkErrorHttpStatus: { validation_error; feature_disabled; access_denied; unauthenticated; not_found; conflict; version_conflict; precondition_failed; record_locked; idempotent_replay; unique_violation; unprocessable; unconfigured; internal_error; member_read_timeout; rate_limited; rate_limit_unavailable };
25
25
  ```
26
26
 
@@ -10,6 +10,7 @@ Import from `@cosmicdrift/kumiko-framework/ui-types`. Types used here but not ex
10
10
  function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown; // Recomputes every derived head field of an action form from its inputs.
11
11
  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.
12
12
  function cardColumnRoles<C extends CardRoleColumn>(columns: C[]): CardColumnRoles<C>;
13
+ function cardMetaLines<C extends CardRoleColumn>(meta: C[]): (C[])[];
13
14
  function computeDerivedCellValue(op: NumericDerivedOp, values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
14
15
  function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean; // Evaluates a declarative FieldCondition against the current row/form values.
15
16
  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.
@@ -427,6 +428,7 @@ type EntityListFacetConfig = {
427
428
  showCounts?: boolean; // Chips show how many rows each option matches (other facets and the search apply).
428
429
  hideEmpty?: boolean; // Chips with zero matching rows are not shown.
429
430
  extraOptions?: EntityListFacetExtraOption[];
431
+ narrowPlacement?: "behind-filter"; // "behind-filter": the facet opens behind the filter icon next to the search field instead of standing as a pill.
430
432
  };
431
433
  type FeatureSchema = {
432
434
  featureName: string;
@@ -468,6 +470,7 @@ type ListBulkAction = { // An action that runs a writeHandler row action once pe
468
470
  type ListColumnHint = {
469
471
  detailField?: string; // Row field with a second, muted line (e.g. the due date as text).
470
472
  narrowDetailField?: string; // Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider").
473
+ narrowField?: string; // Row field shown as the sentence on the phone card instead of the column's own value (a shorter sentence); the table keeps the column value.
471
474
  toneField?: string; // Row field holding a SelectOptionTone; defaults to the screen's `rowToneField`.
472
475
  reasonField?: string; // Row field with a longer reason, shown behind a "Why?" toggle in the cell.
473
476
  reasonOpenField?: string; // Row field (boolean): while true, the `reasonField` text stands open as a box under the row, over the full row width, in the table view (entity/projection lists from `md` up, dashboard lists from `sm` up); the (i) stays and closes it.
@@ -480,7 +483,7 @@ type ListEmptyStateSpec = { // Replacement for the default "no rows" box of a li
480
483
  description?: string;
481
484
  action?: RowAction;
482
485
  };
483
- type ListRowDecoration = { // Computed fields for the loaded rows: one `query` call per page answer with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
486
+ type ListRowDecoration = { // Computed fields for the loaded rows: `query` calls with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`.
484
487
  query: string;
485
488
  params?: Readonly<Record<string, unknown>>;
486
489
  };
@@ -495,6 +498,7 @@ type ListTableSummaryRow = { // The query receives the list's current search, fi
495
498
  query: string; // Qualified query name, e.g. `feature:query:order:summary`.
496
499
  params?: Readonly<Record<string, unknown>>; // Extra payload keys merged over the list's own.
497
500
  };
501
+ type ListToolbarActionsPlacement = (typeof LIST_TOOLBAR_ACTIONS_PLACEMENTS)[number];
498
502
  type OptionsQueryPayload = Readonly<Record<string, OptionsQueryPayloadValue>>;
499
503
  type ParsedRefTarget = {
500
504
  featureName: string;
@@ -525,11 +529,14 @@ type RecordHeaderSubtitlePart =
525
529
  field: string;
526
530
  navigate?: MetricNavigate;
527
531
  format?: FormatSpec; // Formats the raw field value (e.g. `timestamp`); an empty value is still dropped.
532
+ prefix?: string; // i18n key of a text before the value ("Owner "); it stays plain text, a `navigate` link covers only the value.
528
533
  }
529
534
  ;
530
535
  type RecordNotice = {
531
536
  title: string;
532
537
  text?: string;
538
+ narrowTitle?: string; // Shown instead of `title` below `sm`.
539
+ narrowText?: string; // Shown instead of `text` below `sm`.
533
540
  tone?: SelectOptionTone;
534
541
  [field: string]: unknown;
535
542
  };
@@ -552,6 +559,7 @@ type RecordProgressStep = {
552
559
  type RecordStep = {
553
560
  id: string;
554
561
  title: string;
562
+ narrowTitle?: string; // Shown instead of `title` below `sm`.
555
563
  detail?: string;
556
564
  narrowDetail?: string; // Shown instead of `detail` below `sm`.
557
565
  tone?: SelectOptionTone;
@@ -566,6 +574,7 @@ type RecordStepsSpec = {
566
574
  subtitleField?: string; // Record field with a plain-text subtitle.
567
575
  emptyLabel?: string; // i18n key for an empty list, default `kumiko.detail.steps.empty`.
568
576
  narrowLimit?: number; // Below `sm` only the first n steps show; the rest sits behind a "k more steps" toggle.
577
+ narrowMoreLabel?: string; // Plural base key for the toggle of the hidden rest: define `<key>.one` and `<key>.other` (the latter with `{count}`).
569
578
  actions?: RecordGuidanceAction[];
570
579
  };
571
580
  type RecordSummarySpec = { // One emphasized sentence below the header; `field` holds a string.
@@ -114,7 +114,7 @@ function SidebarProvider(props: React.ComponentProps<"div"> & { defaultOpen?: bo
114
114
  function SidebarUser(props: SidebarUserProps): ReactNode;
115
115
  function Sparkline(props: { points: number[]; className?: string; }): ReactNode;
116
116
  function Stack(props: StackProps): ReactNode;
117
- function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
117
+ function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?: string; tone?: StatTone; accentColor?: string; delta?: StatDelta; trend?: string; spark?: number[]; testId?: string; link?: StatLink; navigable?: boolean; inset?: boolean; subBelow?: boolean; boardPadding?: boolean; children?: ReactNode; }): ReactNode; // Icon-bearing metric tile with an optional delta chip, trend line, and sparkline.
118
118
  function StatusBadge(props: { tone: StatusBadgeTone; dot?: boolean; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
119
119
  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.
120
120
  function StepBar(props: { steps: string[]; currentIndex: number; compactLabel: string; onStepSelect?: (index: number) => void; doneSteps?: boolean[]; selectableSteps?: "done" | "all"; narrowLayout?: "label" | "steps"; orientation?: "horizontal" | "vertical" | "stacked"; 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.
@@ -135,6 +135,7 @@ function applyTokensToCssVars(_tokens: Tokens): void; // Historically wrote toke
135
135
  function buildFileUploadFormData(input: FileUploadFormDataInput): FormData;
136
136
  function buildNavRegistrySlice(schema: FeatureSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
137
137
  function buildNavRegistrySliceForApp(app: AppSchema, allowedNavQns?: ReadonlySet<string>): NavRegistrySlice;
138
+ function clearNavCollapseState(): void; // Forgets the collapsed containers and the revealed screen; logout calls it so the next user starts expanded.
138
139
  function clearRememberedListState(): void; // Forgets all remembered list state and the identity marker.
139
140
  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`).
140
141
  function createBrowserDraftStorage(options?: CreateBrowserDraftStorageOptions): DraftStorage; // Default DraftStorage when createKumikoApp boots without one.
@@ -195,6 +196,12 @@ function useUserRoles(): string[] | undefined;
195
196
 
196
197
  ```ts
197
198
  const BROWSER_LOCALE_STORAGE_KEY: "kumiko:locale";
199
+ const DrawnFilter: LucideIcon;
200
+ const DrawnPanel: LucideIcon;
201
+ const DrawnPencil: LucideIcon;
202
+ const DrawnSearch: LucideIcon;
203
+ const DrawnSparkles: LucideIcon;
204
+ const DrawnWand: LucideIcon;
198
205
  const DropdownMenu: FC<Primitive.DropdownMenuProps>;
199
206
  const DropdownMenuPortal: FC<Primitive.DropdownMenuPortalProps>;
200
207
  const DropdownMenuTrigger: ForwardRefExoticComponent<Primitive.DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>>;
@@ -260,6 +267,8 @@ type BannerProps = { // Banner for an inline message or page state (for example,
260
267
  density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
261
268
  icon?: NavIconKey; // Icon left of the text.
262
269
  title?: ReactNode; // Bold heading above `children`, inside the text column.
270
+ narrowTitle?: ReactNode; // Replaces `title` below sm.
271
+ narrowText?: ReactNode; // Replaces `children` below sm and stays visible there even when `inline` drops the text.
263
272
  titleTestId?: string;
264
273
  children?: ReactNode;
265
274
  parts?: { text: string; strong?: boolean; }[]; // Structured text after `children`; `strong` parts render emphasized.
@@ -1547,11 +1556,12 @@ type StepListProps = {
1547
1556
  }; // Badge next to the title, e.g. "Erledigt" for a finished list.
1548
1557
  steps: StepListItem[];
1549
1558
  footerActions?: StepAction[]; // Footer row: a ghost action for the whole list next to the primary next-step action.
1559
+ footerNote?: string; // Quiet line under the footer actions, e.g. "Nothing is saved without you."
1550
1560
  collapsedAfter?: number; // Show only the first n steps plus "und k weitere Schritte" (expands on click).
1551
1561
  collapseWhen?: "always" | "overflow"; // "always" (default) folds after `collapsedAfter`; "overflow" folds a `fill` list only when its steps do not fit its height, then shows as many as fit but at least `collapsedAfter`.
1552
1562
  surface?: "ai" | "plain"; // "ai" (default) = AiSurface background, "plain" = no background.
1553
1563
  fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
1554
- progress?: "full" | "count" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "none" = neither, e.g. when `status` already says the list is done.
1564
+ progress?: "full" | "count" | "total" | "none"; // "full" (default) = "x von y erledigt" plus bar, "count" = only the count, "total" = only "n steps" (rejected ones left out), "none" = neither, e.g. when `status` already says the list is done.
1555
1565
  emptyContent?: ReactNode;
1556
1566
  selection?: StepListSelection; // Adds a checkbox per selectable step, a select-all row and selection footer actions.
1557
1567
  phoneCard?: boolean; // On a phone the list reads as a card: the header sits inside the surface and the steps in a framed white box.
@@ -1561,6 +1571,7 @@ type StepListSelection = {
1561
1571
  selectedIds: string[]; // Explicitly chosen step ids (controlled); prerequisites are added on top.
1562
1572
  onSelectionChange: (selectedIds: string[]) => void;
1563
1573
  actions: StepSelectionAction[]; // Replace `footerActions` while at least one step is selected.
1574
+ compact?: true; // Phone-card style: no select-all row, the actions stay visible at 0 selected (disabled unless `ignoresSelection`), a muted header and left-aligned footer.
1564
1575
  };
1565
1576
  type StepSelectability =
1566
1577
  | {
@@ -1576,7 +1587,9 @@ type StepSelectability =
1576
1587
  ;
1577
1588
  type StepSelectionAction = {
1578
1589
  id: string;
1579
- label: string; // Without a number: the list appends " (n)" with the effective selection size.
1590
+ label: string; // Without a number: the list appends " (n)" with the effective selection size (see `labelForCount`).
1591
+ labelForCount?: (count: number) => string; // Replaces the appended " (n)": the label for the effective selection size.
1592
+ ignoresSelection?: true; // No counter, never disabled by an empty selection (e.g. "Review one by one"); `onClick` still gets the selection.
1580
1593
  onClick: (stepIds: string[]) => void; // Receives the effective selection in list order, prerequisites included.
1581
1594
  variant?: "primary" | "secondary" | "ghost";
1582
1595
  disabled?: boolean;
@@ -1591,6 +1604,7 @@ type StepTag = {
1591
1604
  label: string;
1592
1605
  tone?: "accent" | "muted" | "warn" | "ok" | "bad";
1593
1606
  afterWaiting?: boolean; // A note about the step's history (e.g. just changed) reads after what it waits for.
1607
+ side?: true; // Sits in the right column of the row, above a trailing link (e.g. a risk chip over "Preview").
1594
1608
  };
1595
1609
  interface TextFieldProps extends FieldBase {
1596
1610
  value: string;
@@ -1773,6 +1787,9 @@ type WorkspaceShellProps = {
1773
1787
  focusRailNavQns?: string[]; // Top-level nav QNs the focus rail shows as tiles; the others sit behind a "More" tile that opens the full sidebar.
1774
1788
  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell.
1775
1789
  fill?: boolean; // Viewport-fit shell.
1790
+ contentSurface?: "card" | "background"; // Surface behind the screen content.
1791
+ navStyle?: ShellNavStyle; // `"plain"` renders the sidebar without leading icons while expanded (the focus rail and the collapsed rail keep them), with uppercase group labels, quiet active entries, a panel-symbol sidebar trigger and a 58px title bar.
1792
+ notificationBellPlacement?: "header" | "overflow"; // `"header"` (default) draws the notification bell in the title bar; `"overflow"` moves it into the "…" menu, which then shows on every width.
1776
1793
  children: ReactNode; // Screen content.
1777
1794
  };
1778
1795
  type WorkspaceShellUser = {
@@ -1276,6 +1276,7 @@ type JobRunner = {
1276
1276
  handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
1277
1277
  attachDispatcher(ref: DispatchWriteRef): void;
1278
1278
  countPendingJobs(): Promise<number>;
1279
+ isJobPending?(jobName: string, jobId: string): Promise<boolean>;
1279
1280
  };
1280
1281
  type JobRunnerOptions = {
1281
1282
  registry: Registry;
@@ -1436,6 +1437,7 @@ type EventConsumer = {
1436
1437
  featureName?: string;
1437
1438
  delivery?: "shared" | "per-instance";
1438
1439
  startFrom?: "beginning" | "now";
1440
+ irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
1439
1441
  };
1440
1442
  type EventConsumerBatchHandler = (events: StoredEvent[], ctx: AppContext, turn: BatchTurnControl) => Promise<void>;
1441
1443
  type EventConsumerErrorPolicy = {
@@ -1534,6 +1536,7 @@ type CardRoleColumn = {
1534
1536
  type?: string;
1535
1537
  renderer?: unknown;
1536
1538
  hideOnNarrow?: boolean;
1539
+ narrowInline?: boolean;
1537
1540
  fileDisplay?: {
1538
1541
  kind: string;
1539
1542
  };
@@ -1678,6 +1681,21 @@ type ScreenTarget = {
1678
1681
  };
1679
1682
  ```
1680
1683
 
1684
+ ## packages/renderer/src/card-options.ts
1685
+
1686
+ ```ts
1687
+ type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar.
1688
+ padded?: boolean; // Body-Padding (px-6 py-6).
1689
+ radius?: "lg" | "xl"; // Eckenradius.
1690
+ footerBordered?: boolean; // Separates the footer with `border-t` and `bg-muted/30`.
1691
+ footerInset?: boolean; // Footer horizontal padding.
1692
+ fillHeight?: boolean; // Joins the ancestor fillHeight flex chain — a tabs-mode relatedList table sizing to the panel instead of the page — instead of normal document-flow height.
1693
+ framed?: boolean; // false drops border, background, shadow and radius but keeps padding and header slots — a panel inside a host surface such as a tab panel.
1694
+ screenBody?: boolean; // The card is the whole screen body (secretMint reveal and done phase): no frame, the shared screen insets and width of form screens, children stacked with a gap.
1695
+ headerLayout?: "stacked" | "inline"; // "inline": title and subtitle on one baseline row at 16px inset, compact padding (the board's side panel).
1696
+ };
1697
+ ```
1698
+
1681
1699
  ## packages/renderer/src/components/form-pending-uploads.tsx
1682
1700
 
1683
1701
  ```ts
@@ -1695,6 +1713,10 @@ type ListEmptyStateContent = {
1695
1713
  type NamedFilterEmptyContent = {
1696
1714
  title: string;
1697
1715
  description?: string;
1716
+ describedByQuery?: {
1717
+ query: string;
1718
+ describe: (params: Readonly<Record<string, unknown>>) => string;
1719
+ }; // The description needs params from a query; it renders only once the query returned an object.
1698
1720
  onReset: () => void;
1699
1721
  };
1700
1722
  ```
@@ -1826,6 +1848,7 @@ type DataTableFacet = {
1826
1848
  display?: "select"; // Chips only: "select" renders the chips as one single-choice dropdown instead of a row of toggles.
1827
1849
  showCounts?: boolean; // Chips only: show each chip's `count` next to its label.
1828
1850
  hideEmpty?: boolean; // Chips only: hide chips whose `count` is 0 (unless pressed).
1851
+ narrowPlacement?: "behind-filter"; // Below `sm` the facet opens behind the filter icon next to the search field instead of standing as a pill.
1829
1852
  onSearchChange?: (query: string) => void; // Present: the options come from a server-side search (reference facets), so the dropdown shows a search field and reports the typed term instead of filtering `options` itself.
1830
1853
  searching?: boolean; // The search is loading; the option list may still show the previous term's rows.
1831
1854
  };
@@ -1833,6 +1856,7 @@ type DataTableFacetChip = {
1833
1856
  id: string;
1834
1857
  label: string; // Translated chip label.
1835
1858
  values: string[]; // Selection a click sets; `[]` clears the facet.
1859
+ separatorAfter?: boolean; // Select display: a divider line follows this chip.
1836
1860
  count?: number; // Matching row count, undefined while unknown.
1837
1861
  };
1838
1862
  ```
@@ -2278,6 +2302,7 @@ type ListColumnFileDisplay = // How a list cell shows a FileRef value (id or id
2278
2302
  type ListColumnHintViewModel = {
2279
2303
  detailField?: string;
2280
2304
  narrowDetailField?: string; // `ListColumnHint.narrowDetailField`: replaces `detailField` in the phone card.
2305
+ narrowField?: string; // `ListColumnHint.narrowField`: replaces the sentence value in the phone card.
2281
2306
  toneField?: string;
2282
2307
  reasonField?: string;
2283
2308
  reasonOpenField?: string;
@@ -2303,6 +2328,7 @@ type ListColumnViewModel = {
2303
2328
  highlighted?: boolean; // Set by the caller at runtime (not schema-derived) to emphasize one column — e.g. the currently selected base-year column in a multi-year statement grid.
2304
2329
  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
2305
2330
  showOnNarrowOnly?: boolean; // Mirrors `ListColumnSpec.showOnNarrowOnly`: the table layout skips the column.
2331
+ narrowInline?: boolean; // Mirrors `ListColumnSpec.narrowInline`: the card draws consecutive such columns on one line.
2306
2332
  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
2307
2333
  fileDisplay?: ListColumnFileDisplay; // Set for file/image columns: from the entity field type, or from a `{ format: "image" | "file" }` renderer.
2308
2334
  hint?: ListColumnHintViewModel; // "To do" cell (`ListColumnSpec.hint`), `emptyLabel` already translated.
@@ -2348,6 +2374,7 @@ type MetricProps = { // Compact label/value tile (record-detail metrics band).
2348
2374
  tone?: DashboardStatTone;
2349
2375
  icon?: NavIconKey;
2350
2376
  sub?: string; // Small muted line under the value (see `MetricSpec.subField`).
2377
+ narrowSub?: string; // Replaces `sub` below `sm` (see `MetricSpec.subFieldNarrow`).
2351
2378
  };
2352
2379
  ```
2353
2380
 
@@ -2367,7 +2394,7 @@ type RecordStepsProps = { // "Next steps" panel; an item's `reason` sits behind
2367
2394
  narrowLimit?: number; // Below the sm breakpoint only this many steps show; the rest sits behind a toggle.
2368
2395
  moreLabel?: (hiddenCount: number) => string; // Toggle label for the hidden steps; receives their count.
2369
2396
  lessLabel?: string;
2370
- items: { id: string; title: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2397
+ items: { id: string; title: string; narrowTitle?: string; detail?: string; narrowDetail?: string; tone?: SelectOptionTone; reason?: string; reasonOpen?: true; reasonTitle?: string; actions?: ReactNode; moreActions?: ReactNode; }[];
2371
2398
  count?: number; // Total number of steps, shown small beside the heading even when `narrowLimit` shortens the list.
2372
2399
  testId?: string;
2373
2400
  };
@@ -2415,15 +2442,6 @@ type ButtonBaseProps = {
2415
2442
  iconEnd?: NavIconKey; // Icon after the label (e.g. "Continue →").
2416
2443
  dataAttributes?: DataAttributes;
2417
2444
  };
2418
- type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar.
2419
- padded?: boolean; // Body-Padding (px-6 py-6).
2420
- radius?: "lg" | "xl"; // Eckenradius.
2421
- footerBordered?: boolean; // Separates the footer with `border-t` and `bg-muted/30`.
2422
- footerInset?: boolean; // Footer horizontal padding.
2423
- fillHeight?: boolean; // Joins the ancestor fillHeight flex chain — a tabs-mode relatedList table sizing to the panel instead of the page — instead of normal document-flow height.
2424
- framed?: boolean; // false drops border, background, shadow and radius but keeps padding and header slots — a panel inside a host surface such as a tab panel.
2425
- screenBody?: boolean; // The card is the whole screen body (secretMint reveal and done phase): no frame, the shared screen insets and width of form screens, children stacked with a gap.
2426
- };
2427
2445
  type CardSlots = { // Card slots are named content regions, all optional.
2428
2446
  header?: ReactNode;
2429
2447
  title?: ReactNode;
@@ -2718,6 +2736,12 @@ type DefaultAppShellUser = {
2718
2736
  };
2719
2737
  ```
2720
2738
 
2739
+ ## packages/renderer/src/web/layout/shell-style.tsx
2740
+
2741
+ ```ts
2742
+ type ShellNavStyle = "default" | "plain";
2743
+ ```
2744
+
2721
2745
  ## packages/renderer/src/web/layout/sidebar-panel.tsx
2722
2746
 
2723
2747
  ```ts
@@ -3180,6 +3204,8 @@ type ExtensionSelectorDef = {
3180
3204
  panels?: ExtensionSelectorPanel[];
3181
3205
  };
3182
3206
  type ExtensionSelectorPanel = DashboardCustomPanel | Omit<DashboardScreenPanel, "label">;
3207
+ const IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES: ["rebuildable-derived-data", "high-risk-or-cron-pipeline", "per-dispatch-record-key"];
3208
+ type IrreversibleWithoutEntryHandler = (typeof IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES)[number];
3183
3209
  type JobBackoff =
3184
3210
  | JobBackoffStrategy
3185
3211
  | {
@@ -4116,7 +4142,6 @@ type ContextServices = { // Infrastructure the app wired at boot, as the handler
4116
4142
  _notifyFactory?: NotifyFactory;
4117
4143
  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4118
4144
  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
4119
- _deliveryAttemptLogFactory?: DeliveryAttemptLogFactory;
4120
4145
  _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
4121
4146
  _escapeHatchAuditSink?: EscapeHatchAuditSink;
4122
4147
  extensions: Readonly<Record<string, unknown>>;
@@ -4256,6 +4281,7 @@ type JobRunnerRef = {
4256
4281
  handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
4257
4282
  handleCatchUpEvent?(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
4258
4283
  dispatch?(jobName: string, payload: Record<string, unknown>, meta?: { priority?: number; jobId?: string; }): Promise<unknown>;
4284
+ isJobPending?(jobName: string, jobId: string): Promise<boolean>;
4259
4285
  };
4260
4286
  type JobTriggerEvent = {
4261
4287
  id: string;
@@ -4533,7 +4559,7 @@ type Logger = {
4533
4559
  ```ts
4534
4560
  type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
4535
4561
  appendEvent: AppendEventFn<TMap>;
4536
- unsafeAppendEvent: UnsafeAppendEventFn;
4562
+ unsafeAppendEvent: (args: Parameters<UnsafeAppendEventFn>[0] & { expectedVersion?: number; }) => Promise<void>;
4537
4563
  loadAggregate: (aggregateId: string, options?: { asOf?: Temporal.Instant; }) => Promise<StoredEvent[]>;
4538
4564
  registry: Registry;
4539
4565
  files?: FileContext;
@@ -4552,6 +4578,8 @@ type ListSortDir = "asc" | "desc";
4552
4578
  type NamedFilterFacetOptions = { // How the named filters appear in the toolbar: toggle chips (default) or one single-choice select.
4553
4579
  display?: "chips" | "select";
4554
4580
  showCounts?: boolean; // Ask the list query for each filter's hit count and show it next to the label.
4581
+ hideEmpty?: boolean; // Select entries with zero hits are left out (the active one and "all" stay).
4582
+ narrowPlacement?: "behind-filter"; // "behind-filter": the select opens behind the filter icon next to the search field instead of standing as a pill.
4555
4583
  label?: string; // i18n key for the select's label, e.g. "To do".
4556
4584
  };
4557
4585
  type NamedListFilterCondition = {
@@ -4568,11 +4596,13 @@ type NamedListFilterRef = { // Screen-side reference to an entity-defined named
4568
4596
  id: string;
4569
4597
  label: string;
4570
4598
  sort?: ListSortSpec; // Order while this filter is active and the URL carries no sort of its own; wins over `defaultSort`.
4599
+ separatorAfter?: boolean; // Select display: draws a divider line below this entry in the dropdown.
4571
4600
  emptyState?: {
4572
4601
  title: string;
4573
4602
  description?: string;
4574
- }; // Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; both are i18n keys.
4575
- roles?: string[]; // Set by the framework from the entity filter's role rule; the chip is offered only to users holding one of them.
4603
+ paramsQuery?: string;
4604
+ }; // Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; `title` and `description` are i18n keys.
4605
+ access?: AccessRule; // Set by the framework from the entity filter's access rule; the client offers the chip only where `isUiAccessGranted` allows it.
4576
4606
  };
4577
4607
  type NamedListFilterScope = {
4578
4608
  ctx: HandlerContext;
@@ -5011,6 +5041,7 @@ type EntityListFacetExtraOption = { // An extra choice on a facet next to the fi
5011
5041
  label: string; // i18n key.
5012
5042
  values: string[]; // Option values this choice selects; `[]` selects nothing, i.e. no filter.
5013
5043
  position?: "start" | "end"; // Where the chip sits relative to the field's own options.
5044
+ separatorAfter?: boolean; // Draws a divider line below this choice in the select dropdown (e.g. after a "needs action" bundle).
5014
5045
  };
5015
5046
  type ListColumnDisplay = "bar" | "badge" | "datetime" | "button";
5016
5047
  type ListPaginationMode = "pages" | "infinite" | false;
@@ -5056,6 +5087,7 @@ const LIST_COLUMN_PINS: ["left", "right"];
5056
5087
  const LIST_NARROW_FACETS: ["pills"];
5057
5088
  const LIST_TABLE_DENSITIES: ["comfortable", "compact", "relaxed"];
5058
5089
  const LIST_TABLE_FRAMES: ["card"];
5090
+ const LIST_TOOLBAR_ACTIONS_PLACEMENTS: ["header", "toolbar"];
5059
5091
  type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
5060
5092
  type ListNarrowFacets = (typeof LIST_NARROW_FACETS)[number];
5061
5093
  type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
@@ -5090,6 +5122,7 @@ type MetricSpec = {
5090
5122
  tone?: DashboardStatTone; // Tile color as on dashboard stat panels; not applied while the value is 0.
5091
5123
  toneField?: string; // Record field of the detail query holding a SelectOptionTone; a valid value overrides `tone`, also at value 0.
5092
5124
  subField?: string; // Record field of the detail query shown as a small line under the value; the value stays the number.
5125
+ subFieldNarrow?: string; // Record field shown instead of `subField` below `sm` ("of 2,850 €" instead of "0 of 2,850.00 €").
5093
5126
  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
5094
5127
  format?: FormatSpec; // Formats the displayed value (e.g. `date`, `enumOption`); the tone still resolves on the raw value.
5095
5128
  };
package/agents/api.md CHANGED
@@ -10,11 +10,11 @@ Format: one line per function or constant, object and options types as property
10
10
  | --- | --- | --- |
11
11
  | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 446 |
12
12
  | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
- | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 178 |
13
+ | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 180 |
14
14
  | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 157 |
15
15
  | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 41 |
16
16
  | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
17
- | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 372 |
17
+ | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 379 |
18
18
  | `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 23 |
19
19
  | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 72 |
20
20
  | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |
@@ -650,7 +650,7 @@
650
650
  | --- | --- | --- | --- |
651
651
  | <a id="list-button-column-in-list-table"></a>`list/button-column-in-list-table` | display "button" is drawn only in dashboard list panels; entityList and projectionList tables (RenderList) keep a row button as a rowAction. | Declare the button as a rowAction with display: "button" or remove display: "button" from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
652
652
  | <a id="list-button-column-without-link"></a>`list/button-column-without-link` | A column with display "button" has a link (linkScreenField or refEntity) to draw as the button. | Set linkScreenField or refEntity on the column, or remove display: "button". | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
653
- | <a id="list-card-meta-overflow"></a>`list/card-meta-overflow` | A card list shows at most the maximum number of meta columns. | Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true. | `packages/framework/src/engine/boot-validator/card-meta-overflow-rules.ts` |
653
+ | <a id="list-card-meta-overflow"></a>`list/card-meta-overflow` | A card list shows at most the maximum number of meta lines. | Reduce each list to the maximum number of meta lines or mark the other columns hideOnNarrow: true. | `packages/framework/src/engine/boot-validator/card-meta-overflow-rules.ts` |
654
654
  | <a id="list-column-renderer-component-invalid"></a>`list/column-renderer-component-invalid` | A column renderer's react.__component is a non-empty string. | Set react.__component to the name of a client columnRenderers entry. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
655
655
  | <a id="list-column-renderer-react-not-object"></a>`list/column-renderer-react-not-object` | A column renderer's react branch is an object. | Use { react: { __component: "Name" } }. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
656
656
  | <a id="list-column-sortable-inert"></a>`list/column-sortable-inert` | A column only sets sortable where the screen type honors it. | Remove sortable from the column. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
@@ -663,9 +663,11 @@
663
663
  | <a id="list-guidance-field-empty"></a>`list/guidance-field-empty` | rowToneField, linkParamsField and the hint field names are non-empty strings. | Name a row field or remove the option. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
664
664
  | <a id="list-hint-column-display"></a>`list/hint-column-display` | A hint column owns its cell rendering and sets no display. | Remove display or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
665
665
  | <a id="list-hint-column-empty-placeholder"></a>`list/hint-column-empty-placeholder` | A hint column shows hint.emptyLabel for an empty value and sets no emptyPlaceholder. | Remove emptyPlaceholder, or name the empty sentence with hint.emptyLabel. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
666
- | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity or badgeToneField. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
666
+ | <a id="list-hint-column-link"></a>`list/hint-column-link` | A hint column owns its cell rendering and sets no linkScreenField, linkParamsField, refEntity, badgeToneField or badgeDot. | Remove the link or badge option, or move the hint to its own column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
667
667
  | <a id="list-hint-column-renderer"></a>`list/hint-column-renderer` | A hint column owns its cell rendering and sets no renderer. | Remove renderer or hint from the column. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
668
668
  | <a id="list-link-params-without-screen-field"></a>`list/link-params-without-screen-field` | linkParamsField only parametrizes the linkScreenField target. | Set linkScreenField on the column or remove linkParamsField. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
669
+ | <a id="list-named-filter-empty-state-params-query-empty"></a>`list/named-filter-empty-state-params-query-empty` | A named filter's emptyState.paramsQuery is a non-empty query QN. | Name the query or remove paramsQuery from the emptyState. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
670
+ | <a id="list-named-filter-empty-state-params-query-without-description"></a>`list/named-filter-empty-state-params-query-without-description` | A named filter's emptyState.paramsQuery feeds the description, so it needs one. | Set emptyState.description (an i18n key with {params}) or remove paramsQuery. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
669
671
  | <a id="list-named-filter-empty-state-title-empty"></a>`list/named-filter-empty-state-title-empty` | A named filter's emptyState.title is a non-empty i18n key. | Name the title key or remove emptyState from the filter. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
670
672
  | <a id="list-named-filter-facet-without-filters"></a>`list/named-filter-facet-without-filters` | namedFilterFacet only presents the screen's namedFilters. | Declare namedFilters on the screen or remove namedFilterFacet. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
671
673
  | <a id="list-named-filter-sort-not-listed"></a>`list/named-filter-sort-not-listed` | A named filter's sort.field is one of the listed columns. | Pick a field from columns or add it there. | `packages/framework/src/engine/boot-validator/named-filter-rules.ts` |
@@ -679,15 +681,15 @@
679
681
  | <a id="list-related-read-only-with-row-interaction"></a>`list/related-read-only-with-row-interaction` | A readOnly relatedList section declares no rowClick or rowActions. | Remove readOnly or the row interaction. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
680
682
  | <a id="list-related-row-click-no-detail"></a>`list/related-row-click-no-detail` | A relatedList rowClick entity target has a screen declaring detailFor for it. | Add detailFor to the screen that shows the entity. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
681
683
  | <a id="list-related-toolbar-visible-when"></a>`list/related-toolbar-visible-when` | relatedList toolbarActions use visible instead of visibleWhen. | Use visible, a condition on the enclosing record. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
682
- | <a id="list-row-decoration-ids-missing"></a>`list/row-decoration-ids-missing` | The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call. | Add `ids: z.array(z.string())` to the decoration query's schema. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
684
+ | <a id="list-row-decoration-ids-missing"></a>`list/row-decoration-ids-missing` | The rowDecoration query's input schema declares `ids`, the row ids the list sends with every call. | Add `ids: z.array(z.string())` to the decoration query's schema; `.max(...)` must cover at least the list page size; the list asks in batches of the first page size. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
683
685
  | <a id="list-row-decoration-query-empty"></a>`list/row-decoration-query-empty` | rowDecoration.query is a non-empty query QN. | Name the decoration query or remove rowDecoration. | `packages/framework/src/engine/boot-validator/list-row-guidance-rules.ts` |
684
686
  | <a id="list-screen-id-unresolved"></a>`list/screen-id-unresolved` | listScreenId names a mounted screen. | Fix the listScreenId or mount the list screen. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
685
687
  | <a id="list-screen-unreachable"></a>`list/screen-unreachable` | A screen without a nav entry has a resolvable list, or is marked dormant. | Declare listScreenId, add a standalone r.nav() pointing at it, or set dormant: true. | `packages/framework/src/engine/boot-validator/screens-lists-rules.ts` |
686
- | <a id="list-sort-option-not-sortable"></a>`list/sort-option-not-sortable` | Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when sort is an enum, lists every option field. | Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
688
+ | <a id="list-sort-option-not-sortable"></a>`list/sort-option-not-sortable` | Every sortOptions field is a listed, sortable column (entityList); a projectionList's query takes sort and sortDirection and, when they are enums, lists every option field and dir. | Mark the field sortable and list it as a column, or give the projectionList's query sort and sortDirection parameters that accept the option fields. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
687
689
  | <a id="list-sort-options-default-not-listed"></a>`list/sort-options-default-not-listed` | A defaultSort is one of the sortOptions, so the select opens on an entry. | Add the defaultSort field and dir to sortOptions or change defaultSort. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
688
690
  | <a id="list-sort-options-invalid"></a>`list/sort-options-invalid` | sortOptions is not empty and lists each field and dir once. | Remove sortOptions, or list each field and dir pair once. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
689
691
  | <a id="list-summary-row-on-related-list"></a>`list/summary-row-on-related-list` | A relatedList section or expandableRow sets no table.summaryRow; only entityList and projectionList screens have a list payload to carry it. | Remove summaryRow from the relatedList, or put the summary on the list screen itself. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
690
- | <a id="list-summary-row-query-accepts-list-keys"></a>`list/summary-row-query-accepts-list-keys` | The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters). | Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
692
+ | <a id="list-summary-row-query-accepts-list-keys"></a>`list/summary-row-query-accepts-list-keys` | The summaryRow query's Zod schema accepts every list key the screen sends (search, namedFilter, filters) and every summaryRow.params key. | Add the missing keys to the query schema (or reuse the list query's filter shape) and apply them, or drop the feature on the screen. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
691
693
  | <a id="list-summary-row-query-unknown"></a>`list/summary-row-query-unknown` | table.summaryRow.query names a registered query handler. | Use the qualified name of a query handler (feature:query:name) or remove summaryRow. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
692
694
  | <a id="list-summary-row-shape"></a>`list/summary-row-shape` | table.summaryRow is an object with a query string and optional params object. | Write table.summaryRow as { query: "feature:query:order:summary" }. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |
693
695
  | <a id="list-summary-row-with-totals"></a>`list/summary-row-with-totals` | A table sets summaryRow or totals, not both; two footers under one table read as two answers. | Drop totals and put the figures into the summary query, or drop summaryRow. | `packages/framework/src/engine/boot-validator/list-sort-summary-rules.ts` |