@cosmicdrift/kumiko-framework 0.406.0 → 0.410.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 (212) hide show
  1. package/AGENTS.md +4 -2
  2. package/agents/api/framework-db.md +1 -0
  3. package/agents/api/framework-engine.md +17 -2
  4. package/agents/api/framework-ui-types.md +15 -0
  5. package/agents/api/renderer-web.md +156 -2
  6. package/agents/api/types.md +113 -71
  7. package/agents/api.md +4 -4
  8. package/agents/boot-rules.md +744 -0
  9. package/agents/examples/anonymous-access.md +23 -1
  10. package/agents/examples/contact.md +173 -0
  11. package/agents/examples/delivery-notifications.md +34 -1
  12. package/agents/examples/record-detail-layout.md +13 -2
  13. package/agents/examples/search.md +65 -3
  14. package/agents/examples/secrets-demo.md +96 -2
  15. package/agents/examples/tenant-inactivity.md +138 -0
  16. package/agents/examples.md +2 -0
  17. package/agents/features-index.md +4 -0
  18. package/agents/features.md +25 -1
  19. package/agents/widgets.md +12 -1
  20. package/dist/api/export/export-rows.js +1 -0
  21. package/dist/compliance/index.d.ts +1 -1
  22. package/dist/db/event-store-executor-read-where.js +15 -5
  23. package/dist/db/index.d.ts +1 -1
  24. package/dist/db/index.js +1 -1
  25. package/dist/db/migrate-generator.js +3 -1
  26. package/dist/db/queries/event-consumer.js +11 -7
  27. package/dist/db/queries/event-store.d.ts +2 -1
  28. package/dist/db/queries/event-store.js +25 -6
  29. package/dist/db/queries/rls-boot-catalog.js +3 -1
  30. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  31. package/dist/db/queries/session-advisory-lock.js +23 -0
  32. package/dist/db/query.js +7 -10
  33. package/dist/db/row-level-security-connection.js +4 -2
  34. package/dist/engine/access.js +5 -1
  35. package/dist/engine/active-membership.js +1 -0
  36. package/dist/engine/boot-validator/access-declarations.js +76 -33
  37. package/dist/engine/boot-validator/action-wiring.js +8 -6
  38. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  39. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  40. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  41. package/dist/engine/boot-validator/agent-effect.js +20 -0
  42. package/dist/engine/boot-validator/boot-context.js +5 -1
  43. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  44. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  45. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  46. package/dist/engine/boot-validator/boot-phases.js +3 -1
  47. package/dist/engine/boot-validator/boot-rules.d.ts +2624 -0
  48. package/dist/engine/boot-validator/boot-rules.js +58 -0
  49. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  50. package/dist/engine/boot-validator/config-deps.js +71 -23
  51. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  52. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  53. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  54. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  55. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  56. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  57. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  58. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  59. package/dist/engine/boot-validator/detail-screens.js +10 -4
  60. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  61. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  62. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  63. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  64. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  65. package/dist/engine/boot-validator/entity-handler.js +259 -355
  66. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  67. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  68. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  69. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  70. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  71. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  72. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  73. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  74. package/dist/engine/boot-validator/entity-select.js +197 -0
  75. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  76. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  77. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  78. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  79. package/dist/engine/boot-validator/field-conditions.js +67 -22
  80. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  81. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  82. package/dist/engine/boot-validator/form-derivations.js +52 -18
  83. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  84. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +77 -0
  85. package/dist/engine/boot-validator/handler-declaration-rules.js +77 -0
  86. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  87. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  88. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  89. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  90. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  91. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  92. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  93. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  94. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  95. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  96. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  97. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  98. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  99. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  100. package/dist/engine/boot-validator/list-table-options.js +33 -13
  101. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  102. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  103. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  104. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  105. package/dist/engine/boot-validator/nav-rules.js +42 -0
  106. package/dist/engine/boot-validator/nav.js +33 -17
  107. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  108. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  109. package/dist/engine/boot-validator/ownership.js +28 -12
  110. package/dist/engine/boot-validator/parent-ref.js +32 -20
  111. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  112. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  113. package/dist/engine/boot-validator/query-refs.js +20 -10
  114. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  115. package/dist/engine/boot-validator/query-rules.js +37 -0
  116. package/dist/engine/boot-validator/read-gate.js +14 -10
  117. package/dist/engine/boot-validator/record-owned.js +5 -1
  118. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  119. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  120. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  121. package/dist/engine/boot-validator/screens-actions.js +169 -93
  122. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  123. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  124. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  125. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  126. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  127. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  128. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  129. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  130. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  131. package/dist/engine/boot-validator/screens-forms.js +240 -112
  132. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  133. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  134. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  135. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  136. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  137. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  138. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  139. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  140. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  141. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  142. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  143. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  144. package/dist/engine/boot-validator/screens-lists.js +90 -45
  145. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  146. package/dist/engine/boot-validator/screens-rules.js +57 -0
  147. package/dist/engine/boot-validator/screens.js +17 -12
  148. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  149. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  150. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  151. package/dist/engine/boot-validator/workspaces.js +11 -5
  152. package/dist/engine/boot-validator/zod-shape.js +6 -2
  153. package/dist/engine/entity-handlers.d.ts +1 -0
  154. package/dist/engine/entity-handlers.js +3 -0
  155. package/dist/engine/entity-list-runtime-options.js +23 -29
  156. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  157. package/dist/engine/factories.d.ts +1 -1
  158. package/dist/engine/factories.js +4 -3
  159. package/dist/engine/index.d.ts +4 -2
  160. package/dist/engine/index.js +2 -0
  161. package/dist/engine/project-app-schema-for-roles.js +29 -14
  162. package/dist/engine/registry-facade.js +7 -8
  163. package/dist/engine/registry-validate.js +5 -1
  164. package/dist/engine/soft-delete-cleanup.d.ts +1 -0
  165. package/dist/engine/soft-delete-cleanup.js +5 -0
  166. package/dist/engine/steps/describe-workflow-step-error.js +1 -0
  167. package/dist/es-ops/operations-schema.d.ts +1 -1
  168. package/dist/event-store/ensure-dead-letter-table.d.ts +2 -0
  169. package/dist/event-store/ensure-dead-letter-table.js +10 -0
  170. package/dist/event-store/rebuild-dead-letter.js +2 -8
  171. package/dist/event-store/upcaster-dead-letter.js +2 -8
  172. package/dist/files/copy-pending-file-refs-to-tenant.d.ts +28 -0
  173. package/dist/files/copy-pending-file-refs-to-tenant.js +87 -0
  174. package/dist/files/file-routes.d.ts +1 -1
  175. package/dist/files/file-routes.js +21 -6
  176. package/dist/files/index.d.ts +2 -0
  177. package/dist/files/index.js +1 -0
  178. package/dist/i18n/required-surface-keys.js +1 -0
  179. package/dist/jobs/job-runner-helpers.js +1 -0
  180. package/dist/jobs/job-runner.js +7 -12
  181. package/dist/logging/utils.js +30 -60
  182. package/dist/observability/metrics-handle.js +10 -21
  183. package/dist/pipeline/cascade-handler.js +7 -6
  184. package/dist/pipeline/dispatch-query.js +18 -5
  185. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  186. package/dist/pipeline/dispatch-shared.js +3 -1
  187. package/dist/pipeline/dispatch-write.js +10 -12
  188. package/dist/pipeline/dispatcher.js +12 -14
  189. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  190. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  191. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  192. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  193. package/dist/pipeline/event-dispatcher.js +28 -21
  194. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  195. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  196. package/dist/pipeline/system-hooks.d.ts +4 -1
  197. package/dist/pipeline/system-hooks.js +79 -6
  198. package/dist/pipeline/system-identity-switch.js +10 -7
  199. package/dist/search/build-search-snippet.d.ts +9 -0
  200. package/dist/search/build-search-snippet.js +40 -0
  201. package/dist/search/index.d.ts +1 -0
  202. package/dist/search/index.js +1 -0
  203. package/dist/search/meilisearch-adapter.d.ts +32 -0
  204. package/dist/search/meilisearch-adapter.js +153 -56
  205. package/dist/search/meilisearch-chunking.d.ts +21 -0
  206. package/dist/search/meilisearch-chunking.js +96 -0
  207. package/dist/search/reindex-entity.d.ts +1 -0
  208. package/dist/search/reindex-entity.js +97 -52
  209. package/dist/ui-types/index.d.ts +1 -1
  210. package/dist/upgrade-cli.js +3 -14
  211. package/package.json +3 -3
  212. package/src/changes.json +79 -0
package/AGENTS.md CHANGED
@@ -100,8 +100,10 @@ that holds global data calls `r.systemScope()`.
100
100
  `{ access: { roles: ["Admin", "User"] } }`, or
101
101
  `{ access: { openToAll: { reason: "<why every signed-in user may>" } } }`.
102
102
  Screens and nav entries can narrow visibility further with their own
103
- `access`. Anonymous endpoints use the `anonymous` role. Field level and row
104
- level rules exist as well (see the table below).
103
+ `access`. Anonymous endpoints use the `anonymous` role; add `anySignedIn: true`
104
+ (`{ roles: ["anonymous"], anySignedIn: true }`) so a visitor who is signed in
105
+ passes whatever roles the session carries. Field level and row level rules
106
+ exist as well (see the table below).
105
107
  An `openToAll` write handler whose payload contains personal fields must
106
108
  say that every tenant member may write them:
107
109
  `{ openToAll: { reason: "...", personalData: "tenant-members" } }`. The
@@ -143,6 +143,7 @@ function text(name: string): ColumnBuilder<string>;
143
143
  function timestamp(name: string, _opts?: { withTimezone?: boolean; mode?: "string" | "date"; }): ColumnBuilder<Temporal.Instant | string>;
144
144
  function toPostgresArrayLiteral(values: PostgresArrayElement[]): string;
145
145
  function transaction<T>(db: AnyDb, fn: (tx: DbTx) => Promise<T>): Promise<T>;
146
+ function tryWithSessionAdvisoryLock<T>(db: AnyDb, key: number, fn: () => Promise<T>): Promise<TryAdvisoryLockResult<T>>;
146
147
  function uniqueIndex(name: string): IndexBuilder;
147
148
  function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: unknown[]): Promise<TRow[]>;
148
149
  function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
@@ -43,7 +43,7 @@ function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type" | keyof
43
43
  function createImagesField(overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImagesFieldDef;
44
44
  function createJsonbField(overrides?: Partial<Omit<JsonbFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): JsonbFieldDef;
45
45
  function createLocatedTimestampField<R extends true | false = false>(overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): LocatedTimestampFieldDef & { required: R; }; // Wall-clock time at a place as one atomic field.
46
- function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & { required?: R; }): EntityLongTextFieldDef & { required: R; };
46
+ function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | "searchable" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & { required?: R; }): EntityLongTextFieldDef & { required: R; };
47
47
  function createMoneyField<R extends true | false = false>(overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R; }): MoneyFieldDef & { required: R; };
48
48
  function createMultiSelectField<const TOptions extends string[]>(opts: { options: TOptions; } & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): MultiSelectFieldDef<TOptions>; // Multi-select field — N values from a fixed option list.
49
49
  function createNumberField<R extends true | false = false>(overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): NumberFieldDef & { required: R; }; // Numeric field — `double precision` column by default (fractional values allowed end to end).
@@ -90,6 +90,7 @@ function extensionUsageEscapeHatchReason(usage: Pick<RegistrarExtensionRegistrat
90
90
  function fieldToZod(field: FieldDefinition, currencies: string[], opts?: { applyDefaults?: boolean; isUpdate?: boolean; }): z.ZodTypeAny;
91
91
  function filterEntriesAfter(entries: ChangelogEntry[], version: string): ChangelogEntry[];
92
92
  function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
93
+ function findEntity(features: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;
93
94
  function findForbiddenMembershipRole(roles: string[]): string | undefined;
94
95
  function findForbiddenRoleAssignment(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
95
96
  function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: string[]): string[] | undefined;
@@ -133,6 +134,7 @@ function parseTenantId(value: unknown): TenantId | null;
133
134
  function projectAppSchemaForRoles(schema: AppSchema, roles: string[]): AppSchema;
134
135
  function qn(scope: string, type: QnType, name: string): string;
135
136
  function readClaim<T extends ClaimKeyType>(user: SessionUser, handle: ClaimKeyHandle<T>): ClaimKeyJsType<T> | undefined;
137
+ function readSoftDeleteGraceDays(config: ((qualifiedKey: string) => Promise<unknown>) | undefined): Promise<number>;
136
138
  function referenceGroupLabels(ctx: HandlerContext, user: SessionUser, sourceTableName: string, groupByField: string, keys: AggregateKey[], db: TenantDb): Promise<ReadonlyMap<string, string>>;
137
139
  function requireTierResolverPlugin(usage: RegistrarExtensionRegistration): TierResolverPlugin;
138
140
  function resolveAgentExposure(def: { description?: string; agent?: AgentHandlerHints; }, kind: "query" | "write"): AgentExposure; // Fail-closed: a handler without a `description` stays invisible to the agent unless it opts in explicitly.
@@ -200,6 +202,8 @@ const QnTypes: { write; query; hook; job; notify; event; channel; config; secret
200
202
  const SECURITY_BASELINE_FEATURE_NAMES: ["sessions", "crypto-shredding", "rate-limiting", "audit"];
201
203
  const SELECTED_EXTENSIONS_QUERY: "config:query:config-value:selected-extensions";
202
204
  const SETTINGS_HUB_FEATURE: "config";
205
+ const SOFT_DELETE_DEFAULT_GRACE_DAYS: 30;
206
+ const SOFT_DELETE_GRACE_DAYS_KEY: "soft-delete:config:grace-days";
203
207
  const STEP_DISPATCHED_TYPE: "kumiko:system:step.dispatched";
204
208
  const STEP_DISPATCH_AGGREGATE_TYPE: "step-dispatch";
205
209
  const STEP_DISPATCH_FAILED_TYPE: "kumiko:system:step.dispatch-failed";
@@ -272,12 +276,14 @@ type ActionFormScreenDefinition = {
272
276
  summary?: {
273
277
  title: string;
274
278
  subtitle?: string;
279
+ params?: Readonly<Record<string, string>>;
275
280
  }; // Context box above the fields (i18n keys).
276
281
  submitStyle?: "primary" | "danger"; // Visual style of the submit button.
277
282
  successMessage?: string; // i18n key of a confirmation shown above the form after a successful submit when the screen stays put (no `redirect`, not drawer-hosted).
278
283
  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful submit: either a short ID (e.g. "item-list" — same feature, the nav-router resolves to the full path) or a fully-qualified cross-feature QN (`<feature>:screen:<id>`).
279
284
  successLinks?: ActionFormSuccessLink[]; // Links shown in the success box after a successful submit while the screen stays put.
280
285
  successFacts?: ActionFormSuccessFact[]; // Key figures from the handler's success payload, shown in the success box while the screen stays put (e.g. charged/skipped/failed of a batch run).
286
+ successItems?: ActionFormSuccessItems; // One hint per entry of a success-payload array, each with its own link (e.g. "this file is already in the inbox" with "Open" per uploaded file).
281
287
  resetOnSuccess?: boolean; // Reset the form to its initial values after a successful submit (prefill kept, typed values cleared).
282
288
  load?: ActionFormLoad; // Load the initial values from a query.
283
289
  cancelTarget?: string | false; // Target of the Cancel button.
@@ -285,9 +291,11 @@ type ActionFormScreenDefinition = {
285
291
  slots?: ScreenSlots;
286
292
  access?: AccessRule;
287
293
  };
294
+ type AgentEffect = "proposal"; // "proposal": the write only changes a suggestion that a person still approves elsewhere, so the agent may run it without its own approval step.
288
295
  type AgentHandlerHints = { // Per-handler hints for the AI-agent manifest.
289
296
  expose?: boolean;
290
297
  risk?: AgentRisk;
298
+ effect?: AgentEffect;
291
299
  };
292
300
  type AgentRisk = "low" | "mid" | "high";
293
301
  type AppContext = SharedContextFields & {
@@ -384,13 +392,14 @@ type ConfigEditScreenDefinition = {
384
392
  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
385
393
  scope: "tenant" | "system" | "user"; // scope for config:write:set calls.
386
394
  configKeys: Readonly<Record<string, string>>; // Map: form field name (short, as referenced in the layout) → fully qualified config key (`<feature>:config:<short>`).
387
- secretKeys?: Readonly<Record<string, string>>; // Field name → qualified secret key (`<feature>:secret:<short>`), tenant scope only.
395
+ secretKeys?: Readonly<Record<string, string>>; // Field name → qualified secret key (`<feature>:secret:<short>`), tenant or system scope (system: platform-wide, SystemAdmin only), never user scope.
388
396
  fields: Readonly<Record<string, FieldDefinition>>; // Form shape per field name.
389
397
  layout: EditLayout; // Layout: sections with field refs.
390
398
  fieldLabels?: Readonly<Record<string, string>>; // Optional per-field label i18n key (field name → key).
391
399
  fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
392
400
  requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
393
401
  submitLabel?: string; // i18n key for the submit button.
402
+ actions?: ConfigEditAction[]; // Handler buttons drawn as their own row after `afterField` (settings-list layout).
394
403
  slots?: ScreenSlots;
395
404
  access?: AccessRule;
396
405
  };
@@ -502,6 +511,7 @@ type EditFieldSpec =
502
511
  fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
503
512
  refEntity?: string; // Marks this field as a reference lookup instead of a plain value — for projectionDetail fields, which have no `EntityDefinition` to carry a real `reference` field type.
504
513
  refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
514
+ format?: "email" | "phone"; // Text format for projectionDetail fields, which have no `EntityDefinition` to carry it: a read-only value renders as a `mailto:`/`tel:` link.
505
515
  embeddedList?: EmbeddedListEditSpec; // Embedded-list fields only (`createEmbeddedListField`).
506
516
  prefill?: EditFieldPrefill; // Fills an empty value when the create form opens; the update form and values from URL params or a handoff are never touched.
507
517
  }
@@ -867,6 +877,7 @@ type HandlerContext<TMap extends object = KumikoEventTypeMap> = {
867
877
  user: SessionUser; // The active SessionUser for the handler call, exposed as a convenience alias for `event.user`.
868
878
  rateLimitDigest?: (value: string) => string; // Keyed digest for handler-owned rate-limit keys, so Redis never holds a plaintext or plainly hashed identifier.
869
879
  includeDeleted?: boolean;
880
+ onlyDeleted?: boolean;
870
881
  dispatch: HandlerDispatch;
871
882
  hasFeature: (featureName: string) => Promise<boolean>;
872
883
  events: HandlerEvents<TMap>;
@@ -1199,6 +1210,7 @@ type NotifyJobDispatcher = {
1199
1210
  type NotifyOptions = {
1200
1211
  to?: string | string[] | { tenant: TenantId; };
1201
1212
  route?: Readonly<Record<string, string>>;
1213
+ channels?: string[];
1202
1214
  data?: Readonly<Record<string, unknown>>;
1203
1215
  priority?: NotifyPriority;
1204
1216
  idempotencyKey?: string;
@@ -1503,6 +1515,7 @@ type RoleAccessPersonalData = "public-intake";
1503
1515
  type RoleAccessRule = {
1504
1516
  roles: string[];
1505
1517
  personalData?: RoleAccessPersonalData;
1518
+ anySignedIn?: true;
1506
1519
  };
1507
1520
  type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
1508
1521
  type RowActionWriteHandler = {
@@ -1635,12 +1648,14 @@ type TemplateScalarVariableDef = (TemplateVariableCommon & { type: "text"; examp
1635
1648
  type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef | TemplateImagesVariableDef;
1636
1649
  type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
1637
1650
  type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<TenantDestroyHookResult | void>;
1651
+ type TenantDataDestroyPhase = "app-data" | "tenant-row";
1638
1652
  interface TenantDataHookCtx {
1639
1653
  db: ExecutorManagedTenantDb;
1640
1654
  registry: Registry;
1641
1655
  tenantId: TenantId;
1642
1656
  deadlineAt?: number;
1643
1657
  fileProviderResolver?: FileProviderResolver;
1658
+ heldFileRefIds?: ReadonlySet<string>;
1644
1659
  log?: (message: string) => void;
1645
1660
  }
1646
1661
  type TenantDestroyHookResult =
@@ -74,14 +74,28 @@ type ActionFormSuccessFact = { // One key figure of the success box, read from t
74
74
  field: string; // Flat field name in the handler's success payload.
75
75
  label: string; // Label (i18n key).
76
76
  };
77
+ type ActionFormSuccessItems = { // Per-entry hints of the success box, read from an array in the handler's success payload.
78
+ field: string; // Flat field name of an array in the success payload.
79
+ link?: ActionFormSuccessLink; // Link of each hint.
80
+ };
77
81
  type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & { // A redirect target rendered as a link in the success box.
78
82
  idFrom?: string; // Success-payload field carrying the navigation id.
83
+ params?: Readonly<Record<string, string>>; // URL search params of the target, each read from a success-payload field (`{ cmd: "duplicateOfId" }` opens `?cmd=<duplicateOfId>`).
79
84
  label: string; // Link text (i18n key).
80
85
  };
81
86
  type AppSchema = {
82
87
  features: FeatureSchema[];
83
88
  workspaces?: WorkspaceSchema[];
84
89
  };
90
+ type ConfigEditAction = { // A button row on a configEdit form that calls a write handler with `{}` (for example "send a test").
91
+ id: string; // Unique within the screen; used for the test id.
92
+ handler: string; // Qualified name of a write handler (`<feature>:write:<name>`).
93
+ label: string;
94
+ description?: string;
95
+ buttonLabel: string;
96
+ afterField: string; // Field (from the layout) after which the row is drawn.
97
+ successMessage?: string; // Shown after a successful call; without it a success stays silent.
98
+ };
85
99
  type CustomScreenDefinition = {
86
100
  id: string;
87
101
  type: "custom";
@@ -420,6 +434,7 @@ type RecordHeaderSubtitlePart =
420
434
  | {
421
435
  field: string;
422
436
  navigate?: MetricNavigate;
437
+ format?: FormatSpec; // Formats the raw field value (e.g. `timestamp`); an empty value is still dropped.
423
438
  }
424
439
  ;
425
440
  type RelatedListEmptyStateSpec = ListEmptyStateSpec & { // The first `variants` entry whose `when` holds for the parent record replaces `title` and `description`; `action` stays.
@@ -8,14 +8,18 @@ Import from `@cosmicdrift/kumiko-renderer/web`. Types used here but not exported
8
8
 
9
9
  ```ts
10
10
  function ActionMenu(props: ActionMenuProps): ReactNode;
11
+ function AiSurface(props: { children: ReactNode; title?: string; label?: string; testId?: string; as?: "section" | "aside" | "div"; }): ReactNode; // Light blue area that marks content as AI-generated.
11
12
  function AiTextArea(props: AiTextAreaProps): ReactNode; // Multi-line variant of {@link AiTextField}.
12
13
  function AiTextField(props: AiTextFieldProps): ReactNode; // Single-line AI text field — ghost-text completion + correct/translate/ rewrite toolbar.
13
14
  function AppLayout(props: AppLayoutProps): ReactNode;
15
+ function AttachmentCard(props: Omit<MessageAttachment, "id"> & { testId?: string; }): ReactNode; // Full-width attachment row with a thumbnail box, name, second line and an "open original" link or button.
16
+ function AttachmentChip(props: MessageAttachment & { testId?: string; }): ReactNode; // File chip with icon, name and a second line; renders as link, button or plain box depending on href/onOpen.
14
17
  function Avatar(props: AvatarProps): ReactNode;
15
18
  function BareFormProvider(props: { children: ReactNode; }): ReactNode;
16
19
  function BooleanField(props: BooleanFieldProps): ReactNode; // Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean").
17
20
  function Card(props: CardProps): ReactNode;
18
21
  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.
22
+ function ClampedText(props: { children: ReactNode; lines?: number; moreLabelKey?: string; maxHeightPx?: number; testId?: string; }): ReactNode; // Clamps content to `lines`; the toggle shows only while the content actually overflows.
19
23
  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.
20
24
  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.
21
25
  function DateField(props: DateFieldProps): ReactNode; // Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd.
@@ -45,13 +49,16 @@ function LanguageSwitcher(props: LanguageSwitcherProps): ReactNode;
45
49
  function LiveEventsProvider(props: LiveEventsProviderProps): ReactNode;
46
50
  function LoadingState(props: { rows?: number; className?: string; testId?: string; }): ReactNode; // Loading state with skeleton rows styled like cards; `rows` controls the height.
47
51
  function LocaleProvider(props: LocaleProviderProps): ReactNode;
52
+ function MessageReader(props: MessageReaderProps): ReactNode; // Mail thread with an optional tab per attachment; the tab bar only exists when there are attachment tabs.
53
+ function MessageThread(props: MessageThreadProps): ReactNode; // Mail conversation, oldest first: older messages fold to one line, the last one is open on a sheet.
48
54
  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.
55
+ function MobileTopBar(props: MobileTopBarProps): ReactNode; // Phone-only bar for focused screens: the shell header is hidden there, so the screen brings its own.
49
56
  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>.
50
57
  function NavProvider(props: NavProviderProps): ReactNode;
51
58
  function NavTree(props: NavTreeProps): ReactNode;
52
59
  function NumberField(props: NumberFieldProps): ReactNode; // Number field = Field + Input(kind:"number"); avoids repeating the id/name/value/onChange wiring at each screen.
53
60
  function PageSection(props: PageSectionProps): ReactNode;
54
- function PdfPreview(props: { source: PdfPreviewSource; testId?: string; }): ReactNode;
61
+ function PdfPreview(props: PdfPreviewProps): ReactNode; // PDF pages rendered with pdf.js; pages render lazily as they scroll into view.
55
62
  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.
56
63
  function PlainContentEditor(props: ContentEditorProps): ReactNode;
57
64
  function PlanCard(props: PlanCardProps): ReactNode;
@@ -74,6 +81,8 @@ function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; ro
74
81
  function ScreenWidthProvider(props: { width: FormWidth | undefined; children: ReactNode; }): ReactNode;
75
82
  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.
76
83
  function SelectField(props: SelectFieldProps): ReactNode; // Select field = Field + Input(kind:"select").
84
+ function SenderFrame(props: { children: ReactNode; label?: string; testId?: string; }): ReactNode; // Sand frame with one white sheet inside, for content that mimics a letter or mail.
85
+ function SenderSheet(props: { children: ReactNode; testId?: string; compact?: boolean; }): ReactNode; // The white sheet alone, for a frame that holds several sheets (PDF pages, thumbnails).
77
86
  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.
78
87
  function Sidebar(props: SidebarProps): ReactNode;
79
88
  function SidebarBrand(props: SidebarBrandProps): ReactNode;
@@ -89,6 +98,7 @@ function StatCard(props: { icon?: ReactNode; label: string; value: string; sub?:
89
98
  function StatusBadge(props: { tone: StatusBadgeTone; children: ReactNode; className?: string; testId?: string; }): ReactNode; // Pill badge with a status dot.
90
99
  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.
91
100
  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.
101
+ function StepList(props: StepListProps): ReactNode; // Ordered plan of steps with status icons, progress header and per-step actions.
92
102
  function TextField(props: TextFieldProps): ReactNode; // Text field = Field + Input(kind:"text").
93
103
  function TextareaField(props: TextareaFieldProps): ReactNode; // Multi-line text field = Field + Input(kind:"textarea").
94
104
  function ThemeMenuItem(props: ThemeMenuItemProps): ReactNode; // Theme toggle as a dropdown entry, for a user menu that carries the shell controls.
@@ -147,6 +157,7 @@ function useNav(): NavApi;
147
157
  function usePrimitives(): PrimitivesRegistry;
148
158
  function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;
149
159
  function useResolvers(): ReadonlyMap<string, ResolverComponent>;
160
+ function useShellFocusMode(): void; // Screen side: call while the screen is mounted to get the focused shell.
150
161
  function useStore<T>(store: Store<T>): T;
151
162
  function useStoreSelector<T, S>(store: Store<T>, select: (snapshot: T) => S, equals?: (a: S, b: S) => boolean): S;
152
163
  function useToast(): ToastApi;
@@ -197,6 +208,7 @@ type ActionMenuProps = {
197
208
  interface AiTextAreaProps extends AiTextFieldBaseProps {
198
209
  rows?: number;
199
210
  }
211
+ type AiTextEndAction = InputEndAction;
200
212
  interface AiTextFieldProps extends AiTextFieldBaseProps {}
201
213
  type AppLayoutProps = {
202
214
  topbar?: ReactNode; // Optional.
@@ -217,7 +229,7 @@ type AvatarProps = {
217
229
  };
218
230
  type AvatarSize = "sm" | "md" | "lg";
219
231
  type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
220
- 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`).
232
+ variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint"; // "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`), "hint" for a quiet aside on a muted background (e.g. per-entry results of a submit, with an "Open" link in `actions`).
221
233
  title?: ReactNode; // Bold heading above `children`, inside the text column.
222
234
  titleTestId?: string;
223
235
  children: ReactNode;
@@ -430,6 +442,7 @@ type DefaultAppShellProps = {
430
442
  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badges per navigation item (bare nav-id → ReactNode), passed through to NavTree.
431
443
  headerActions?: ReactNode; // Right-aligned slot in the topbar (next to the breadcrumb) — for ThemeToggle, global actions, and similar controls.
432
444
  sidebarFooter?: ReactNode; // Footer slot at the bottom of the sidebar — profile row, help link, or plan banner.
445
+ focusRailNavQns?: string[]; // Top-level nav QNs the focus rail shows as tiles; the others sit behind a "More" tile that opens the full sidebar.
433
446
  fill?: boolean; // Viewport-fit shell.
434
447
  children: ReactNode; // Screen content rendered inside SidebarInset.
435
448
  };
@@ -580,6 +593,7 @@ type InfinityListProps<TData = unknown, TRow = Readonly<Record<string, unknown>>
580
593
  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).
581
594
  renderRow: (row: TRow) => ReactNode;
582
595
  emptyState?: ReactNode;
596
+ endContent?: ReactNode; // Scrolls with the rows, after the last loaded one, e.g. a hint under search hits.
583
597
  className?: string;
584
598
  testId?: string;
585
599
  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.
@@ -612,6 +626,7 @@ type InputProps =
612
626
  prefix?: string; // Resolved inline text before/after the input (EditFieldSpec.prefix/suffix).
613
627
  suffix?: string;
614
628
  fill?: InputFillAction;
629
+ endAction?: InputEndAction;
615
630
  dataAttributes?: DataAttributes;
616
631
  onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void; // Raw keydown access (e.g. Enter-to-submit at the field instead of the surrounding Form).
617
632
  }
@@ -917,6 +932,61 @@ type MenuItemDef =
917
932
  label: string;
918
933
  }
919
934
  ;
935
+ type MessageAttachment = {
936
+ id: string;
937
+ name: string;
938
+ meta?: string; // Second line, e.g. "Foto, 1,2 MB" or "PDF, 4 Seiten".
939
+ kind?: "image" | "pdf" | "file"; // Icon only.
940
+ onOpen?: () => void;
941
+ href?: string;
942
+ thumbnailUrl?: string; // Preview image; AttachmentCard shows it instead of the kind icon.
943
+ };
944
+ type MessageBody =
945
+ | {
946
+ kind: "text";
947
+ text: string;
948
+ }
949
+ | {
950
+ kind: "html";
951
+ html: string;
952
+ fallbackText?: string;
953
+ }
954
+ ;
955
+ type MessageReaderProps = {
956
+ thread: MessageThreadProps;
957
+ attachmentTabs?: MessageReaderTab[]; // One tab per attachment ("Anhang 1: Vertrag.pdf"); without tabs no tab bar is shown.
958
+ activeTabId?: string; // "mail" = the thread; default "mail".
959
+ onTabChange?: (id: string) => void;
960
+ testId?: string;
961
+ };
962
+ type MessageReaderTab = {
963
+ id: string;
964
+ label: string;
965
+ icon?: ReactNode; // Shown before the label in the tab strip.
966
+ detail?: string; // Small muted text after the label, e.g. "4 Seiten".
967
+ render: () => ReactNode;
968
+ };
969
+ type MessageThreadProps = {
970
+ messages: ThreadMessage[]; // Oldest first.
971
+ clampLines?: number; // Lines before "Mehr anzeigen" on a long text body.
972
+ remoteImages?: "blocked" | "allowed"; // External images in html bodies.
973
+ showHeaders?: boolean; // false drops author, address and time above open messages, for hosts whose page head already names them.
974
+ foldOlderTogether?: boolean; // Phone reading: older messages fold into one "n earlier mails" toggle instead of a row each, and a clamped mail offers "read the whole mail".
975
+ testId?: string;
976
+ };
977
+ type MobileTopBarProps = {
978
+ label: string; // Screen label, e.g. "Posteingang · 1 von 5 offen".
979
+ back?: {
980
+ label: string;
981
+ onClick: () => void;
982
+ }; // Chevron button before the label; label is its aria-label.
983
+ status?: {
984
+ label: string;
985
+ tone: StatusBadgeTone;
986
+ }; // Chip before the actions, e.g. "KI an".
987
+ actions?: ReactNode; // Trailing controls, e.g. an overflow menu trigger.
988
+ testId?: string;
989
+ };
920
990
  type ModeSwitchVariant = "outline" | "pill";
921
991
  type NavApi = {
922
992
  route: NavRoute | undefined; // Current route — `undefined` when the URL is at the root / there's no route selected.
@@ -962,6 +1032,24 @@ interface NumberFieldProps {
962
1032
  testId?: string;
963
1033
  grouping?: boolean; // `false` renders without thousands separators (e.g. a year).
964
1034
  }
1035
+ type PdfMatchInfo = {
1036
+ count: number;
1037
+ index: number; // 0-based index of the active match.
1038
+ };
1039
+ type PdfPreviewProps = {
1040
+ source: PdfPreviewSource;
1041
+ testId?: string;
1042
+ variant?: "stacked" | "viewer"; // "stacked" = all pages under each other.
1043
+ searchTerm?: string; // Highlights matches in the text layer; the viewer opens on the first hit and shows "Treffer n von m".
1044
+ initialPage?: number; // 1-based page to open on.
1045
+ onPageChange?: (page: number) => void;
1046
+ matchIndex?: number; // Viewer only: 0-based active match, controlled by the host (e.g. its own "Treffer 1 von 3" stepper).
1047
+ onMatchesChange?: (info: PdfMatchInfo) => void; // Viewer only: reports the match count and active index whenever either changes.
1048
+ hideSearchBar?: boolean; // Viewer only: hides the toolbar's own search controls.
1049
+ markTerm?: string; // Viewer only: marks a passage without opening the search, e.g. the clause a step was read from.
1050
+ fill?: boolean; // Viewer only: take the container's height without the 480px floor, for hosts whose layout sizes the pane.
1051
+ pagesOnly?: boolean; // Viewer only: just the pages on the frame, without thumbnail rail and toolbar.
1052
+ };
965
1053
  type PdfPreviewSource =
966
1054
  | {
967
1055
  base64: string;
@@ -1131,6 +1219,7 @@ type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
1131
1219
  fieldAppendix?: (fieldName: string) => ReactNode | undefined; // Per-field extra content below the input (e.g. ConfigCascadeView).
1132
1220
  fieldAppendixPlacement?: "above-control" | "below-control"; // Placement of every `fieldAppendix` relative to its control.
1133
1221
  fieldDescription?: (fieldName: string) => ReactNode | undefined; // Per-field help text rendered under the label (translated by the caller).
1222
+ rowAfterField?: (fieldName: string, state: { dirty: boolean; }) => ReactNode | undefined; // Extra full-width row drawn right after a field's cell (configEdit actions).
1134
1223
  fieldAccent?: (fieldName: string) => boolean; // Marks fields whose value is set at this level; drawn by `settings-list` rows.
1135
1224
  markChangedFields?: boolean; // Edit-mode "changed" markers also for screens without an entity id (configEdit loads its values from a query, not a record).
1136
1225
  onChange?: (state: RenderEditChangeState<TValues>) => void; // Controlled mode: fires on every values-snapshot change (typing, `patch(...)` from outside) with the current values.
@@ -1293,6 +1382,60 @@ type StatusBarEntry = {
1293
1382
  label?: string; // Tooltip text (<title>), supplied translated by the caller.
1294
1383
  };
1295
1384
  type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
1385
+ type StepAction = {
1386
+ id: string;
1387
+ label: string;
1388
+ onClick: () => void;
1389
+ variant?: "primary" | "secondary" | "ghost";
1390
+ disabled?: boolean;
1391
+ pending?: boolean;
1392
+ };
1393
+ type StepListItem = {
1394
+ id: string;
1395
+ title: string;
1396
+ description?: string;
1397
+ status: StepStatus;
1398
+ lockedReason?: string; // Shown for "locked" as muted tag "Wartet auf: ..." and as the icon's accessible name.
1399
+ tags?: StepTag[];
1400
+ meta?: string;
1401
+ link?: {
1402
+ label: string;
1403
+ href?: string;
1404
+ onClick?: () => void;
1405
+ placement?: "trailing" | "below"; // "below" puts an action that changes the step (e.g. taking a rejection back) under its text; default is the trailing link to what the step made.
1406
+ };
1407
+ sources?: StepSource[]; // Where the step comes from, e.g. "Quelle: Seite 3, § 5" (caller-localized); each renders as a link under the description.
1408
+ highlighted?: boolean; // Marks the step the reader is looking at (warm background).
1409
+ actions?: StepAction[]; // Rendered only while status is "open".
1410
+ };
1411
+ type StepListProps = {
1412
+ title: string;
1413
+ subtitle?: string; // Second line under the title, e.g. who completed the list and when.
1414
+ status?: {
1415
+ label: string;
1416
+ tone: StatusBadgeTone;
1417
+ }; // Badge next to the title, e.g. "Erledigt" for a finished list.
1418
+ steps: StepListItem[];
1419
+ footerActions?: StepAction[]; // Footer row: a ghost action for the whole list next to the primary next-step action.
1420
+ collapsedAfter?: number; // Show only the first n steps plus "und k weitere Schritte" (expands on click).
1421
+ 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`.
1422
+ surface?: "ai" | "plain"; // "ai" (default) = AiSurface background, "plain" = no background.
1423
+ fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
1424
+ 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.
1425
+ emptyContent?: ReactNode;
1426
+ 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.
1427
+ testId?: string;
1428
+ };
1429
+ type StepSource = {
1430
+ label: string;
1431
+ onClick: () => void;
1432
+ };
1433
+ type StepStatus = "done" | "open" | "locked" | "running" | "rejected" | "failed";
1434
+ type StepTag = {
1435
+ label: string;
1436
+ tone?: "accent" | "muted" | "warn" | "ok" | "bad";
1437
+ afterWaiting?: boolean; // A note about the step's history (e.g. just changed) reads after what it waits for.
1438
+ };
1296
1439
  interface TextFieldProps extends FieldBase {
1297
1440
  value: string;
1298
1441
  onChange: (v: string) => void;
@@ -1330,6 +1473,16 @@ type ThemeToggleProps = {
1330
1473
  titleForAuto?: string; // Title/aria-label for the step to auto mode.
1331
1474
  testId?: string;
1332
1475
  };
1476
+ type ThreadMessage = {
1477
+ id: string;
1478
+ author: string; // "Anna Schneider" or the caller's "Du".
1479
+ address?: string;
1480
+ direction: "incoming" | "outgoing"; // Outgoing messages get the reply icon in the collapsed row.
1481
+ timeLabel: string; // Preformatted by the caller ("Heute 09:41").
1482
+ body: MessageBody;
1483
+ attachments?: MessageAttachment[];
1484
+ teaser?: string; // Plain-text preview the host derived, e.g. without the greeting; shown instead of the clamped body while a folded thread has the mail closed.
1485
+ };
1333
1486
  type TimeseriesHeight = // Pixel height, or one height per viewport class.
1334
1487
  | number
1335
1488
  | {
@@ -1430,6 +1583,7 @@ type WorkspaceShellProps = {
1430
1583
  user?: WorkspaceShellUser; // Current user.
1431
1584
  initialWorkspaceId?: string; // Initial active workspace short id ("admin").
1432
1585
  sidebarFooter?: ReactNode; // Footer slot at the bottom of the sidebar — profile row, help link, build information.
1586
+ focusRailNavQns?: string[]; // Top-level nav QNs the focus rail shows as tiles; the others sit behind a "More" tile that opens the full sidebar.
1433
1587
  navBadges?: ReadonlyMap<string, ReactNode>; // Runtime badge slot per nav leaf (bare nav id), same as DefaultAppShell.
1434
1588
  fill?: boolean; // Viewport-fit shell.
1435
1589
  children: ReactNode; // Screen content.