@cosmicdrift/kumiko-framework 0.410.0 → 0.412.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-db.md +1 -1
  2. package/agents/api/framework-engine.md +50 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/framework-ui-types.md +10 -0
  5. package/agents/api/renderer-web.md +113 -10
  6. package/agents/api/types.md +30 -0
  7. package/agents/api.md +3 -3
  8. package/agents/boot-rules.md +4 -0
  9. package/agents/examples/api-docs.md +702 -0
  10. package/agents/examples/realtime-sse.md +37 -2
  11. package/agents/examples/record-detail-layout.md +35 -2
  12. package/agents/examples/wizard-form.md +96 -5
  13. package/agents/examples.md +1 -0
  14. package/agents/features.md +6 -0
  15. package/agents/widgets.md +6 -0
  16. package/dist/api/auth-middleware.d.ts +1 -0
  17. package/dist/api/index.d.ts +3 -0
  18. package/dist/api/index.js +3 -0
  19. package/dist/api/pat-auth-reject.d.ts +7 -0
  20. package/dist/api/pat-auth-reject.js +7 -0
  21. package/dist/api/server-middleware.js +2 -1
  22. package/dist/compliance/sub-processors.js +2 -2
  23. package/dist/config/index.d.ts +25 -0
  24. package/dist/config/index.js +28 -1
  25. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  26. package/dist/db/event-store-executor-read-paging.js +2 -1
  27. package/dist/db/queries/session-advisory-lock.js +3 -0
  28. package/dist/db/read-gate-clause.js +26 -7
  29. package/dist/db/table-builder.d.ts +1 -2
  30. package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
  31. package/dist/engine/boot-validator/list-table-options.js +1 -0
  32. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
  33. package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
  34. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  35. package/dist/engine/boot-validator/screens-forms.js +60 -3
  36. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  37. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  38. package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
  39. package/dist/engine/boot-validator/screens-lists.js +2 -2
  40. package/dist/engine/define-feature.js +3 -0
  41. package/dist/engine/entity-list-runtime-options.js +12 -0
  42. package/dist/engine/factories.d.ts +2 -0
  43. package/dist/engine/feature-builder-state.d.ts +2 -1
  44. package/dist/engine/feature-builder-state.js +1 -0
  45. package/dist/engine/index.d.ts +5 -2
  46. package/dist/engine/index.js +4 -1
  47. package/dist/engine/project-app-schema-for-roles.js +11 -10
  48. package/dist/engine/registry-facade.js +13 -0
  49. package/dist/engine/screen-helpers.d.ts +1 -0
  50. package/dist/engine/screen-helpers.js +1 -1
  51. package/dist/engine/webhook-contracts.d.ts +12 -0
  52. package/dist/engine/webhook-contracts.js +172 -0
  53. package/dist/engine/webhook-events.d.ts +34 -0
  54. package/dist/engine/webhook-events.js +71 -0
  55. package/dist/errors/docs-url.js +2 -19
  56. package/dist/errors/error-codes.d.ts +20 -0
  57. package/dist/errors/error-codes.js +19 -0
  58. package/dist/errors/index.d.ts +2 -0
  59. package/dist/errors/index.js +1 -0
  60. package/dist/i18n/required-surface-keys.d.ts +4 -0
  61. package/dist/i18n/required-surface-keys.js +15 -0
  62. package/dist/pipeline/context-services.d.ts +1 -0
  63. package/dist/pipeline/context-services.js +1 -0
  64. package/dist/pipeline/handler-context-scope.js +5 -1
  65. package/dist/pipeline/user-live-signals.d.ts +5 -0
  66. package/dist/pipeline/user-live-signals.js +20 -0
  67. package/package.json +3 -3
  68. package/src/changes.json +78 -0
@@ -109,7 +109,7 @@ function listEventTenantIds(db: AnyDb): Promise<string[]>;
109
109
  function loadSnapshotJson(path: string): Snapshot | null;
110
110
  function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
111
111
  function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
112
- function physicalColumnName(table: Table, field: string): string;
112
+ function physicalColumnName(table: unknown, field: string): string;
113
113
  function primaryKey(opts: { columns: ColumnHandle[]; name?: string; }): PrimaryKeyDescriptor;
114
114
  function readDatabaseNow(db: TenantDb): Promise<Date>; // Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree.
115
115
  function recordEventsOwnedExclusivelyByTenant(db: DbRunner, aggregateType: string, aggregateId: string, tenantId: string): Promise<boolean>;
@@ -35,7 +35,7 @@ function createDecimalField<R extends true | false = false>(config: { precision:
35
35
  function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
36
36
  function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
37
37
  function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
38
- function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
38
+ function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
39
39
  function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
40
40
  function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
41
41
  function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
@@ -60,6 +60,7 @@ function createTextField<R extends true | false = false>(overrides: Partial<Omit
60
60
  function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TimestampFieldDef & { required: R; }; // UTC instant for events occurring at a specific point in time (createdAt, loginAt, actualPickupAt).
61
61
  function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TzFieldDef & { required: R; }; // IANA time-zone name (for example, "Europe/Berlin").
62
62
  function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
63
+ function createWebhookContractResolver(features: FeatureDefinition[]): WebhookContractResolver; // Works on the feature list so a boot check, which has no registry, resolves the same contracts.
63
64
  function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
64
65
  function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
65
66
  function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
@@ -95,9 +96,11 @@ function findForbiddenMembershipRole(roles: string[]): string | undefined;
95
96
  function findForbiddenRoleAssignment(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
96
97
  function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: string[]): string[] | undefined;
97
98
  function findTierResolverUsage(features: FeatureDefinition[]): RegistrarExtensionRegistration | undefined;
99
+ function formatWebhookPayloadIssues(issues: WebhookPayloadIssue[]): string;
98
100
  function from(ref: OwnershipRef, column?: string): FromRule;
99
101
  function getStep(kind: StepKind): StepDef | undefined;
100
102
  function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void; // Asserts a state transition is allowed.
103
+ function handlerDescriptionKey(handlerQn: string): string;
101
104
  function handlerFieldLabelKey(handlerQn: string, fieldName: string): string;
102
105
  function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;
103
106
  function handlerTitleKey(handlerQn: string): string;
@@ -131,6 +134,7 @@ function parseQn(value: string): ParsedQn;
131
134
  function parseRefTarget(raw: string, currentFeature: string): ParsedRefTarget;
132
135
  function parseRefTargetEntityName(raw: string): string;
133
136
  function parseTenantId(value: unknown): TenantId | null;
137
+ function parseWebhookPayload(contract: Pick<WebhookEventContract, "payload">, payload: unknown): WebhookPayloadResult; // Delivery sends the returned payload, never the input: zod strips keys the contract does not declare, so a field added to the source row cannot leak into a webhook by accident.
134
138
  function projectAppSchemaForRoles(schema: AppSchema, roles: string[]): AppSchema;
135
139
  function qn(scope: string, type: QnType, name: string): string;
136
140
  function readClaim<T extends ClaimKeyType>(user: SessionUser, handle: ClaimKeyHandle<T>): ClaimKeyJsType<T> | undefined;
@@ -149,6 +153,7 @@ function setFields(table: ProjectionTable, fields: Record<string, unknown> | ((e
149
153
  function stepsPipeline<TPayload = unknown, TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>>(closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => StepInstance[]): PipelineDef<TPayload, TData, TAwaits>;
150
154
  function templateVariablesToZod(variables: TemplateVariables): z.ZodObject;
151
155
  function tenantChannel(tenantId: TenantId): string;
156
+ function toEntityWebhookPayload(contract: Pick<WebhookEventContract, "payload" | "verb">, event: { aggregateId: string; payload: Readonly<Record<string, unknown>>; }): WebhookPayloadResult; // Maps a stored entity lifecycle event to the contract's payload: the aggregate id joins the event payload, and the contract parse drops every field it does not release, personal ones included, even when the event payload carries them.
152
157
  function toKebab(input: string): string;
153
158
  function typedPayload<TPayload>(event: { type: string; payload: Record<string, unknown>; }, eventDef: EventDef<TPayload>): TPayload;
154
159
  function unwrapWorkflowStepError(error: unknown): unknown;
@@ -157,6 +162,8 @@ function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<
157
162
  function validateBoot(rawFeatures: FeatureDefinition[], options?: ValidateBootOptions): void; // Validates all feature configurations at boot time.
158
163
  function validateBundledListsOptions(options: unknown): void;
159
164
  function walkStepInstances(steps: StepInstance[], where: string): Generator<StepInstance, void, void>;
165
+ function webhookEventDescriptionKey(webhookEventQn: string): string;
166
+ function webhookEventFieldKey(webhookEventQn: string, fieldPath: string): string; // `fieldPath` is the payload row name as the docs list it, nested fields dotted.
160
167
  function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>; // Server counterpart of an actionForm's `derive`: recomputes the derived head fields before the schema validates them, so client-sent totals never count.
161
168
  function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T>; // Override the success-side `data` of a WriteResult while forwarding the failure half untouched.
162
169
  ```
@@ -170,6 +177,7 @@ const BUILT_IN_MEMBERSHIP_ROLES: string[]; // Every membership role the engine r
170
177
  const CODEMOD_PLACEHOLDER_REASON_MARKER: "state the operator use case here";
171
178
  const ConfigScopes: { system: "system"; tenant: "tenant"; user: "user"; };
172
179
  const DEFAULT_CURRENCIES: ["EUR", "USD", "GBP", "CHF", "JPY", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "NZD", "CNY", "INR"];
180
+ const DEFAULT_LIST_LIMIT: 50;
173
181
  const DEFAULT_LOCALES: ["de", "en", "es"];
174
182
  const DELIVERY_FAILURE_CODES;
175
183
  const DELIVERY_SKIP_REASONS: ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
@@ -559,6 +567,7 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
559
567
  softDelete?: boolean;
560
568
  tenancy?: T; // "tenant" (default): auto-filtered by every db accessor.
561
569
  systemStream?: boolean; // This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the creator's tenant.
570
+ webhookEvents?: boolean; // Lets token scopes release `<entity>.created/.updated/.deleted` as webhook events.
562
571
  eventVersion?: number; // Schema version stamped on every lifecycle event (default 1, integer 1..999).
563
572
  eventMigrations?: EntityEventMigration[]; // One step per version, fromVersion → fromVersion+1.
564
573
  searchWeight?: number;
@@ -706,6 +715,7 @@ type FeatureDefinition = {
706
715
  referenceData: ReferenceDataDef[];
707
716
  notifications: Readonly<Record<string, NotificationDefinition>>;
708
717
  events: Readonly<Record<string, EventDef>>;
718
+ webhookEvents?: Readonly<Record<string, WebhookEventDef>>; // Public webhook contracts from r.defineWebhookEvent, keyed by QN.
709
719
  eventMigrations: Readonly<Record<string, EventMigrationDef[]>>;
710
720
  configReads: string[];
711
721
  handlerEntityMappings: Readonly<Record<string, string>>;
@@ -763,6 +773,7 @@ type FeatureRegistrar<TFeature extends string = string> = { // `TFeature` is the
763
773
  notification(definition: { name: string; trigger?: { on: NameOrRef; }; recipient?: NotificationRecipientFn; data?: NotificationDataFn; templates?: Readonly<Record<string, NotificationTemplateFn>>; variables?: TemplateVariables; record?: NotificationRecordMapping; template?: Readonly<Record<string, NotificationTemplateBody>>; meta?: Readonly<Record<string, NotificationTemplateMeta>>; localizedTemplate?: () => NotificationLocalizedTemplate; renamedFrom?: string[]; systemOnly?: boolean; unsubscribe?: boolean; tenantTransport?: boolean; }): void;
764
774
  translations(def: TranslationsDef): void;
765
775
  defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: { version?: number; piiFields: EventPiiStance; migrations?: { fromVersion: number; toVersion: number; transform: EventUpcastFn | DeclarativeEventMigration; }[]; }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
776
+ defineWebhookEvent(definition: { name: string; description: string; payload: z.ZodObject; version: number; wireName?: string; }): WebhookEventHandle;
766
777
  readsConfig(...qualifiedKeys: string[]): void;
767
778
  readsConfig(options: { keys: string[]; }): void;
768
779
  referenceData(entity: NameOrRef, data: Record<string, unknown>[], options?: { upsertKey?: string; }): void;
@@ -1061,6 +1072,7 @@ type ListTableOptions = { // Opt-in table behaviour of a list.
1061
1072
  pinning?: boolean; // Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`.
1062
1073
  resizing?: boolean; // Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize.
1063
1074
  keyboardNavigation?: boolean; // Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click.
1075
+ compactHeader?: boolean; // Renders the header row smaller (12px) and semibold.
1064
1076
  density?: {
1065
1077
  default?: ListTableDensity; // Row density on first visit.
1066
1078
  userChoice?: boolean; // Shows the density choice in the view menu and remembers it per session.
@@ -1457,6 +1469,8 @@ type Registry = {
1457
1469
  getJob(qualifiedName: string): JobDefinition | undefined;
1458
1470
  getAllJobs(): ReadonlyMap<string, JobDefinition>;
1459
1471
  getEvent(qualifiedName: string): EventDef | undefined;
1472
+ getWebhookEventContract(qualifiedName: string): WebhookEventContract | undefined;
1473
+ getWebhookEventContracts(): WebhookEventContract[];
1460
1474
  getEventUpcasters(): ReadonlyMap<string, { currentVersion: number; chain: ReadonlyMap<number, EventUpcastFn>; }>;
1461
1475
  getExtension(name: string): RegistrarExtensionDef | undefined;
1462
1476
  getExtensionUsages(extensionName: string): RegistrarExtensionRegistration[];
@@ -1527,6 +1541,7 @@ type RowActionWriteHandler = {
1527
1541
  confirm?: string; // i18n key for the confirm dialog description.
1528
1542
  confirmLabel?: string; // i18n key for the confirm button text in the dialog.
1529
1543
  visible?: FieldCondition; // Conditional visibility per row.
1544
+ showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
1530
1545
  style?: "primary" | "secondary" | "danger"; // Visual style.
1531
1546
  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
1532
1547
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
@@ -1770,6 +1785,40 @@ type ValidationError = {
1770
1785
  error: string;
1771
1786
  };
1772
1787
  type ValidationHookFn = (data: Readonly<Record<string, unknown>>) => ValidationError[] | null;
1788
+ type WebhookContractResolver = {
1789
+ get(qualifiedName: string): WebhookEventContract | undefined; // Declared contract, or one derived from an entity lifecycle event (`entity.verb`).
1790
+ declared(): WebhookEventContract[]; // Declared contracts only, sorted by QN.
1791
+ };
1792
+ type WebhookEntityVerb = "created" | "updated" | "deleted"; // Lifecycle verbs of an entity that can be released as webhook events.
1793
+ type WebhookEventContract = { // Public payload contract of a webhook event: declared by a feature or derived from an entity.
1794
+ qn: string;
1795
+ wireName: string; // The event name receivers see in the delivered webhook: `wireName` of a declared event, `entity.verb` of a derived one.
1796
+ description: string;
1797
+ payload: z.ZodObject;
1798
+ version: number;
1799
+ origin: "declared" | "entity";
1800
+ entity?: string;
1801
+ verb?: WebhookEntityVerb;
1802
+ };
1803
+ type WebhookEventHandle = {
1804
+ name: string;
1805
+ payload: z.ZodObject;
1806
+ version: number;
1807
+ };
1808
+ type WebhookPayloadIssue = {
1809
+ path: string;
1810
+ message: string;
1811
+ };
1812
+ type WebhookPayloadResult =
1813
+ | {
1814
+ ok: true;
1815
+ payload: Record<string, unknown>;
1816
+ }
1817
+ | {
1818
+ ok: false;
1819
+ issues: WebhookPayloadIssue[];
1820
+ }
1821
+ ;
1773
1822
  type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = { // Workflow definition — the result of defineWorkflow().
1774
1823
  __kind: "workflow";
1775
1824
  name: string;
@@ -21,6 +21,7 @@ function writeFailure(err: KumikoError): WriteFailure;
21
21
 
22
22
  ```ts
23
23
  const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
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 };
24
25
  ```
25
26
 
26
27
  ## Classes
@@ -103,6 +104,7 @@ type FieldIssue = {
103
104
  i18nKey: string;
104
105
  params?: Readonly<Record<string, unknown>>;
105
106
  };
107
+ type FrameworkErrorCode = keyof typeof frameworkErrorHttpStatus;
106
108
  type WriteErrorInfo = {
107
109
  code: string;
108
110
  httpStatus: number;
@@ -322,6 +322,10 @@ type EditExtensionSection = {
322
322
  id?: string; // Kebab-case tab id, used as the `?tab=` value.
323
323
  kind: "extension";
324
324
  title: string;
325
+ description?: string; // Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`.
326
+ subtitle?: string; // Wizard layouts only: short line under this step's title in the step rail and the "up next" box.
327
+ upNextHint?: string; // Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`.
328
+ summaryField?: string; // Wizard layouts only: field whose formatted value shows under the step label once the step is done.
325
329
  component: PlatformComponent;
326
330
  contributesToFormSubmit?: boolean; // When true, the extension registers via `useExtensionFormSubmit` and the surrounding form's Save button should activate for its dirty state.
327
331
  entityName?: string; // Overrides the host-derived entity name passed to the mounted component.
@@ -334,11 +338,15 @@ type EditLayout = {
334
338
  width?: FormWidth; // Default "4xl" (a centered column, narrower than list chrome), unless the app overrides it via `createKumikoApp({ screenWidth })`.
335
339
  mode?: "single" | "wizard" | "tabs"; // Default "single".
336
340
  variant?: "form" | "settings-list"; // "settings-list" lays each section out as a band with a title column on the left and one hairline-separated row per field (label + help left, control right) — the familiar settings pattern, for screens that are a list of independent preferences rather than one record form.
341
+ hideRequiredMarker?: boolean; // Hides the asterisk after required field labels.
337
342
  draft?: boolean; // Persists in-progress wizard state as a resumable draft instead of discarding it on navigation away.
338
343
  wizard?: {
339
344
  aside?: {
340
345
  upNext: true;
346
+ finishDescription?: string;
341
347
  };
348
+ saveAndCloseOnCreate?: boolean; // Also offers "Save and close" while creating a record (default: update mode only).
349
+ submitDisabledWhen?: FieldCondition; // Disables the finish button (and blocks the submit) while the condition holds on the form values.
342
350
  }; // Wizard layouts only.
343
351
  };
344
352
  type EditWriteFormSection = {
@@ -458,6 +466,7 @@ type RowActionClientAction = {
458
466
  confirm?: string; // i18n key for the confirm dialog description.
459
467
  confirmLabel?: string; // i18n key for the confirm button, default `label`.
460
468
  visible?: FieldCondition; // Conditional visibility per row.
469
+ showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
461
470
  style?: "primary" | "secondary" | "danger"; // Visual style.
462
471
  icon?: IconKey; // Overrides the id-based default icon, see `RowActionWriteHandler.icon`.
463
472
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
@@ -471,6 +480,7 @@ type RowActionDrawer = {
471
480
  screen: string; // Short, unqualified id of an `actionForm` screen in the same feature.
472
481
  params?: RowFieldExtractor; // Declarative prefill extracted from the clicked row.
473
482
  visible?: FieldCondition; // Per-row conditional visibility.
483
+ showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
474
484
  style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
475
485
  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
476
486
  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
@@ -18,13 +18,14 @@ function Avatar(props: AvatarProps): ReactNode;
18
18
  function BareFormProvider(props: { children: ReactNode; }): ReactNode;
19
19
  function BooleanField(props: BooleanFieldProps): ReactNode; // Checkbox/Switch = Field(layout:"inline") + Input(kind:"boolean").
20
20
  function Card(props: CardProps): ReactNode;
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.
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; label?: string; columns?: 1 | 2 | 3 | 4; variant?: "check" | "radio"; testId?: string; }): ReactNode; // Card-styled radio group for mutually exclusive choices that need a description or price line.
22
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.
23
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.
24
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.
25
+ function Composer(props: ComposerProps): ReactNode; // Chat input: a label-less textarea with a text send button inside the field frame, bottom right.
25
26
  function DateField(props: DateFieldProps): ReactNode; // Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd.
26
27
  function DefaultAppShell(props: DefaultAppShellProps): ReactNode;
27
- function DetailList(props: { rows: { id?: string; label: string; value: ReactNode; emphasize?: boolean; }[]; testId?: string; }): ReactNode; // Read-only key-value list for detail views (dimmed label on the left, value on the right).
28
+ function DetailList(props: { valueWeight?: "medium" | "normal"; layout?: "default" | "sidebar"; rows: { id?: string; label: string; value: ReactNode; emphasize?: boolean; }[]; testId?: string; }): ReactNode; // Read-only key-value list for detail views (dimmed label on the left, value on the right).
28
29
  function DispatcherProvider(props: DispatcherProviderProps): ReactNode;
29
30
  function Drawer(props: DrawerProps): ReactNode; // Slide-in panel beside a list (e.g. mail reader next to the inbox) — thin wrapper over the Sheet primitive with header/body/footer slots so screens skip per-route Radix boilerplate.
30
31
  function DropdownMenuCheckboxItem(props: ComponentPropsWithoutRef<typeof Primitive.CheckboxItem>): ReactNode;
@@ -53,7 +54,7 @@ function MessageReader(props: MessageReaderProps): ReactNode; // Mail thread wit
53
54
  function MessageThread(props: MessageThreadProps): ReactNode; // Mail conversation, oldest first: older messages fold to one line, the last one is open on a sheet.
54
55
  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
56
  function MobileTopBar(props: MobileTopBarProps): ReactNode; // Phone-only bar for focused screens: the shell header is hidden there, so the screen brings its own.
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>.
57
+ function ModeSwitch<T extends string>(props: { value: T | null; options: { value: T; label: string; count?: number; disabled?: boolean; tone?: "warning"; }[]; onChange: (value: T) => void; ariaLabel?: string; variant?: ModeSwitchVariant; segmentWidth?: "auto" | "wide"; className?: string; testId?: string; }): ReactNode; // Segmented control for mutually exclusive modes—the prominent alternative to the buried <select>.
57
58
  function NavProvider(props: NavProviderProps): ReactNode;
58
59
  function NavTree(props: NavTreeProps): ReactNode;
59
60
  function NumberField(props: NumberFieldProps): ReactNode; // Number field = Field + Input(kind:"number"); avoids repeating the id/name/value/onChange wiring at each screen.
@@ -63,6 +64,8 @@ function PhotoSlots(props: PhotoSlotsProps): ReactNode; // Guided photo capture:
63
64
  function PlainContentEditor(props: ContentEditorProps): ReactNode;
64
65
  function PlanCard(props: PlanCardProps): ReactNode;
65
66
  function PlanGrid(props: PlanGridProps): ReactNode;
67
+ function PresenceAvatars(props: PresenceAvatarsProps): ReactNode; // Small round avatars of the people on a row, with "+n" for the rest; for list rows.
68
+ function PresenceNotice(props: PresenceNoticeProps): ReactNode; // One quiet line above a record: who else is on it and for how long.
66
69
  function PrimitivesProvider(props: PrimitivesProviderProps): ReactNode;
67
70
  function ProfileMenu(props: ProfileMenuProps): ReactNode;
68
71
  function ProgressBar(props: { value: number; tone?: ProgressTone; size?: "default" | "thin"; ariaLabel?: string; className?: string; testId?: string; }): ReactNode; // Progress bar, `value` 0..1 (clamped).
@@ -77,13 +80,14 @@ function ResizableHandle(props: ResizablePrimitive.SeparatorProps & { withHandle
77
80
  function ResizablePanel(props: ResizablePrimitive.PanelProps): JSX.Element;
78
81
  function ResizablePanelGroup(props: ResizablePrimitive.GroupProps): JSX.Element;
79
82
  function ResultPanel(props: { title: string; subtitle?: string; empty?: boolean; emptyText?: ReactNode; rows?: { label: string; value: ReactNode; emphasize?: boolean; }[]; footer?: ReactNode; children?: ReactNode; testId?: string; }): ReactNode; // Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes).
80
- function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
83
+ function ResultTable<Row>(props: { columns: ResultColumn<Row>[]; rows: Row[]; rowKey: (row: Row, index: number) => string; testId?: string; className?: string; card?: boolean; footer?: ResultTableFooterRow[]; compactHeader?: boolean; }): ReactNode; // Static, prop-driven result table for calculated rows (tranches, scenarios).
81
84
  function ScreenWidthProvider(props: { width: FormWidth | undefined; children: ReactNode; }): ReactNode;
82
85
  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.
86
+ function SectionNavLayout(props: SectionNavLayoutProps): ReactNode; // Content column plus an "On this page" navigation in a right column (from xl), for custom screens.
83
87
  function SelectField(props: SelectFieldProps): ReactNode; // Select field = Field + Input(kind:"select").
84
88
  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
89
  function SenderSheet(props: { children: ReactNode; testId?: string; compact?: boolean; }): ReactNode; // The white sheet alone, for a frame that holds several sheets (PDF pages, thumbnails).
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.
90
+ function SideBySideTable(props: { caption: string; rowHeaderLabel: string; columns: SideBySideTableColumn[]; rows: SideBySideTableRow[]; rowHeaderWidth?: number; rowHeaderTone?: "muted" | "foreground"; 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.
87
91
  function Sidebar(props: SidebarProps): ReactNode;
88
92
  function SidebarBrand(props: SidebarBrandProps): ReactNode;
89
93
  function SidebarMenu(props: React.ComponentProps<"ul">): React.JSX.Element;
@@ -154,6 +158,8 @@ function useIsViewportBelow(breakpointPx: number): boolean;
154
158
  function useLiveEvents(): LiveEventSubscriber; // Hook for a useQuery-like consumer.
155
159
  function useLocale(): LocaleResolver; // Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes.
156
160
  function useNav(): NavApi;
161
+ function usePresence(props: UsePresenceOptions): UsePresenceResult; // Announces the user on one record: a heartbeat right away and every 15 s, a leave when the record closes.
162
+ function usePresenceList(props: UsePresenceListOptions): UsePresenceListResult; // Who else is on each of the given rows, for badges in a list.
157
163
  function usePrimitives(): PrimitivesRegistry;
158
164
  function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;
159
165
  function useResolvers(): ReadonlyMap<string, ResolverComponent>;
@@ -225,15 +231,21 @@ type AvatarProps = {
225
231
  id: string; // Stable identifier—the source for the background-color hash.
226
232
  label: string; // Full name or email—the initials are extracted from this value.
227
233
  size?: AvatarSize;
234
+ shape?: AvatarShape; // Default square; round suits inline presence markers.
228
235
  testId?: string;
229
236
  };
230
- type AvatarSize = "sm" | "md" | "lg";
237
+ type AvatarShape = "square" | "round";
238
+ type AvatarSize = "xs" | "sm" | "md" | "lg";
231
239
  type BannerProps = { // Banner for an inline message or page state (for example, "Loading…" or "Screen not found").
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`).
240
+ variant?: "error" | "info" | "loading" | "warning" | "primary" | "hint" | "ok"; // "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`), "ok" for a completed state (e.g. "Done, nothing left to do here").
241
+ density?: "default" | "compact"; // "compact" is one line: the title reads inline before the text.
242
+ icon?: NavIconKey; // Icon left of the text.
233
243
  title?: ReactNode; // Bold heading above `children`, inside the text column.
234
244
  titleTestId?: string;
235
- children: ReactNode;
245
+ children?: ReactNode;
246
+ parts?: { text: string; strong?: boolean; }[]; // Structured text after `children`; `strong` parts render emphasized.
236
247
  actions?: ReactNode; // Optional—additional buttons or elements to the right of the text (for example, "Neu laden").
248
+ actionsPlacement?: "end" | "below"; // Where `actions` sit: `end` (default) right of the text, `below` under it.
237
249
  padded?: boolean; // Adds outer spacing around the banner for page states where it renders alone in the main area (KumikoScreen "not-found", "loading", etc.).
238
250
  testId?: string;
239
251
  id?: string; // Set when a `<Field>` wraps this Banner as its control (no actual input exists for the label to target — see render-field.tsx's unsupported-field-type fallback).
@@ -292,6 +304,17 @@ interface ComparisonMetric<Col> {
292
304
  value: (col: Col, index: number) => ReactNode;
293
305
  bestIndex?: (cols: Col[]) => number; // Index of the best column for this row (highlighted); -1 = none.
294
306
  }
307
+ type ComposerProps = {
308
+ value: string;
309
+ onChange: (value: string) => void;
310
+ onSubmit: () => void;
311
+ placeholder?: string;
312
+ disabled?: boolean;
313
+ submitLabel: string; // Text of the send button.
314
+ docked?: boolean; // Sticks to the bottom of a full-height flex-column parent so it stays visible while the thread scrolls; it also covers the bottom padding of the screen scroll.
315
+ rows?: number;
316
+ testId?: string;
317
+ };
295
318
  type CorePrimitives = {
296
319
  Button: ComponentType<ButtonProps>;
297
320
  Banner: ComponentType<BannerProps>;
@@ -520,6 +543,18 @@ type FloatingPanelGeometry = {
520
543
  width: number;
521
544
  height: number;
522
545
  };
546
+ type FloatingPanelPlacement =
547
+ | {
548
+ mode: "free";
549
+ }
550
+ | {
551
+ mode: "fixed";
552
+ rightPx: number;
553
+ bottomPx: number;
554
+ widthPx: number;
555
+ heightPx: number;
556
+ }
557
+ ;
523
558
  type FloatingPanelProps = {
524
559
  title: ReactNode; // Header content; the header is the move handle.
525
560
  headerActions?: ReactNode; // Header buttons (dock, minimize, close).
@@ -530,6 +565,9 @@ type FloatingPanelProps = {
530
565
  minHeightPx?: number;
531
566
  maxWidthPx?: number; // Default: viewport width minus twice the margin.
532
567
  maxHeightPx?: number; // Default: viewport height minus twice the margin.
568
+ placement?: FloatingPanelPlacement; // "fixed" anchors the panel to the bottom right: no drag, no resize, nothing persisted.
569
+ bodyLayout?: "scroll" | "fill"; // "scroll" (default) pads and scrolls the body; "fill" gives children the whole body to pad and scroll themselves.
570
+ surface?: "default" | "ai"; // "ai" paints header and body with the AI surface.
533
571
  testId?: string;
534
572
  };
535
573
  type FontTokens = {
@@ -579,8 +617,8 @@ type HeaderActionGroupProps = {
579
617
  children: ReactNode;
580
618
  className?: string;
581
619
  };
582
- type HeadingProps = { // Heading with two roles: `page` is a page title (web: h1), while `section` is a group subheading (web: h2 with uppercase and muted styling).
583
- variant?: "page" | "section";
620
+ type HeadingProps = { // Heading with three roles: `page` is a page title (web: h1), `section` is a group subheading (web: h2 with uppercase and muted styling) and `group` is a plain 16px semibold sub-title (web: h2, normal case).
621
+ variant?: "page" | "section" | "group";
584
622
  children: ReactNode;
585
623
  testId?: string;
586
624
  };
@@ -1106,6 +1144,17 @@ type PlanGridProps = {
1106
1144
  children: ReactNode;
1107
1145
  testId?: string;
1108
1146
  };
1147
+ type PresenceAvatarsProps = {
1148
+ entries: PresenceEntry[];
1149
+ max?: number;
1150
+ testId?: string;
1151
+ };
1152
+ type PresenceNoticeProps = {
1153
+ entries: PresenceEntry[];
1154
+ describe?: (entry: PresenceEntry) => ReactNode; // Replaces the default "is looking at this / is editing this" text of the first entry.
1155
+ nowMs?: number; // Fixed "now" in epoch ms; without it the notice follows the clock once a minute.
1156
+ testId?: string;
1157
+ };
1109
1158
  type PrimitivesProviderProps = {
1110
1159
  children: ReactNode;
1111
1160
  value: PrimitivesRegistry;
@@ -1314,10 +1363,17 @@ interface ResultColumn<Row> {
1314
1363
  align?: "left" | "right";
1315
1364
  cell: (row: Row) => ReactNode;
1316
1365
  }
1366
+ type SectionNavLayoutProps = {
1367
+ items: FormSectionNavItem[]; // One entry per section; `id` must equal the DOM `id` of the section element in `children`.
1368
+ children: ReactNode;
1369
+ width?: keyof typeof screenFormColumnWidthClassName; // Content column width, default "4xl".
1370
+ testId?: string;
1371
+ };
1317
1372
  type SectionProps = { // Titled group of fields.
1318
1373
  id?: string; // DOM id — the scroll target of a form's "on this page" navigation.
1319
1374
  title?: string; // Optional; without a title, the Section renders only the grouping and no header.
1320
1375
  subtitle?: ReactNode; // Optional muted subtitle below the title, providing section context rather than only a label (analogous to `FormProps.subtitle`).
1376
+ subtitleBelowLgOnly?: boolean; // Shows the subtitle only below the `lg` breakpoint: a wizard's step rail carries the same text from `lg` up.
1321
1377
  children: ReactNode;
1322
1378
  actions?: ReactNode; // Rendered top-right in the title row — never a footer.
1323
1379
  layout?: "stacked" | "settings-list"; // "settings-list": title + subtitle form a left header column and the children (field rows) the right one on `md:` and up.
@@ -1406,6 +1462,8 @@ type StepListItem = {
1406
1462
  };
1407
1463
  sources?: StepSource[]; // Where the step comes from, e.g. "Quelle: Seite 3, § 5" (caller-localized); each renders as a link under the description.
1408
1464
  highlighted?: boolean; // Marks the step the reader is looking at (warm background).
1465
+ selectable?: StepSelectability; // Read only when the list has `selection`.
1466
+ dependsOn?: string[]; // Ids of prerequisite steps; selecting this step selects them too.
1409
1467
  actions?: StepAction[]; // Rendered only while status is "open".
1410
1468
  };
1411
1469
  type StepListProps = {
@@ -1423,9 +1481,35 @@ type StepListProps = {
1423
1481
  fill?: boolean; // Stretch to the container height: steps scroll in the middle, the footer stays pinned at the bottom.
1424
1482
  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
1483
  emptyContent?: ReactNode;
1484
+ selection?: StepListSelection; // Adds a checkbox per selectable step, a select-all row and selection footer actions.
1426
1485
  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
1486
  testId?: string;
1428
1487
  };
1488
+ type StepListSelection = {
1489
+ selectedIds: string[]; // Explicitly chosen step ids (controlled); prerequisites are added on top.
1490
+ onSelectionChange: (selectedIds: string[]) => void;
1491
+ actions: StepSelectionAction[]; // Replace `footerActions` while at least one step is selected.
1492
+ };
1493
+ type StepSelectability =
1494
+ | {
1495
+ kind: "selectable";
1496
+ }
1497
+ | {
1498
+ kind: "missing-input";
1499
+ reason: string;
1500
+ }
1501
+ | {
1502
+ kind: "none";
1503
+ }
1504
+ ;
1505
+ type StepSelectionAction = {
1506
+ id: string;
1507
+ label: string; // Without a number: the list appends " (n)" with the effective selection size.
1508
+ onClick: (stepIds: string[]) => void; // Receives the effective selection in list order, prerequisites included.
1509
+ variant?: "primary" | "secondary" | "ghost";
1510
+ disabled?: boolean;
1511
+ pending?: boolean;
1512
+ };
1429
1513
  type StepSource = {
1430
1514
  label: string;
1431
1515
  onClick: () => void;
@@ -1452,6 +1536,7 @@ interface TextareaFieldProps extends FieldBase {
1452
1536
  value: string;
1453
1537
  onChange: (v: string) => void;
1454
1538
  rows?: number;
1539
+ placeholder?: string;
1455
1540
  }
1456
1541
  type ThemeMenuItemProps = {
1457
1542
  lightIcon?: ReactNode;
@@ -1560,6 +1645,24 @@ type UseFormResult<TValues extends FormValues> = {
1560
1645
  controller: FormController<TValues>;
1561
1646
  snapshot: FormSnapshot<TValues>;
1562
1647
  };
1648
+ type UsePresenceListOptions = {
1649
+ entity: string;
1650
+ ids: string[];
1651
+ enabled?: boolean;
1652
+ };
1653
+ type UsePresenceListResult = {
1654
+ byId: Readonly<Record<string, PresenceEntry[]>>;
1655
+ };
1656
+ type UsePresenceOptions = {
1657
+ entity: string;
1658
+ id: string;
1659
+ activity: PresenceActivity;
1660
+ focus?: string; // Which part of the record the user is on, e.g. `field:title`.
1661
+ enabled?: boolean;
1662
+ };
1663
+ type UsePresenceResult = {
1664
+ others: PresenceEntry[];
1665
+ };
1563
1666
  type UseQueryOptions = {
1564
1667
  enabled?: boolean;
1565
1668
  live?: boolean;
@@ -1806,6 +1806,7 @@ type DataTableTableBlock = { // The DataTable props a screen's `table` block fee
1806
1806
  view?: DataTableViewOptions; // View menu (column picker, density); absent = no menu.
1807
1807
  resetAll?: DataTableResetAll; // Replaces the facet reset with one that also covers sort, search and page size.
1808
1808
  exportList?: DataTableExport; // Present: the toolbar has an export button (web only).
1809
+ compactHeader?: boolean; // Smaller (12px) semibold header row.
1809
1810
  serverGroups?: DataTableServerGroups; // Present: the rows are grouped on the server; replaces pager and infinite scroll.
1810
1811
  totals?: DataTableTotals; // Present: a footer row with the server-computed totals of the filtered list.
1811
1812
  notice?: DataTableListNotice; // Present: the toolbar says the answer is incomplete and asks to narrow the list.
@@ -3339,6 +3340,7 @@ type ParentVisibilityGateOption = {
3339
3340
  };
3340
3341
  type ParentVisibilityOption = {
3341
3342
  entities: ReadonlyMap<string, EntityDefinition>;
3343
+ readModelEntities?: ReadonlyMap<string, { entity: EntityDefinition; table: SchemaTable; }>;
3342
3344
  canReadEntity?: (entityName: string) => boolean;
3343
3345
  resolveTable?: (entityName: string) => SchemaTable;
3344
3346
  };
@@ -3459,6 +3461,13 @@ type UiHints = {
3459
3461
  recommended?: boolean;
3460
3462
  configurableOptions?: UiHintOption[];
3461
3463
  };
3464
+ type WebhookEventDef = { // What `r.defineWebhookEvent` stores; `qn` is `<feature>:<name>`.
3465
+ qn: string;
3466
+ wireName: string;
3467
+ description: string;
3468
+ payload: z.ZodObject;
3469
+ version: number;
3470
+ };
3462
3471
  ```
3463
3472
 
3464
3473
  ## packages/types/src/field-state-conditions.ts
@@ -3950,6 +3959,7 @@ type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
3950
3959
  type ContextServices = { // Infrastructure the app wired at boot, as the handler or job sees it.
3951
3960
  redis?: Redis;
3952
3961
  cacheSync?: CacheSyncBus;
3962
+ userLiveSignals?: UserLiveSignals;
3953
3963
  jobRunner?: JobRunnerRef;
3954
3964
  searchAdapter?: SearchAdapter;
3955
3965
  entityCache?: EntityCache;
@@ -3980,6 +3990,9 @@ type HandlerTenants = {
3980
3990
  writeTarget?: (tenantId: TenantId) => TenantWriteTarget; // Write target for ANOTHER tenant: a tenant-mode db bound to it plus the `streamTenantId` to hand the executor, so the event actor stays the operator.
3981
3991
  };
3982
3992
  type JobLifecycle = Pick<HandlerLifecycle, "signal">;
3993
+ type UserLiveSignals = { // Addressed live signal: the SSE frame reaches only the listed users of the caller's own tenant.
3994
+ push(userIds: string[], signal: { type: string; entity?: string; id?: string; }): Promise<void>;
3995
+ };
3983
3996
  ```
3984
3997
 
3985
3998
  ## packages/types/src/handlers.ts
@@ -4164,6 +4177,7 @@ type SessionUserOrigin = "member-resolution";
4164
4177
  type SharedContextFields = {
4165
4178
  redis?: Redis;
4166
4179
  cacheSync?: CacheSyncBus;
4180
+ userLiveSignals?: UserLiveSignals;
4167
4181
  jobRunner?: JobRunnerRef;
4168
4182
  configResolver?: ConfigResolver;
4169
4183
  config?: ConfigAccessor;
@@ -4611,6 +4625,19 @@ type PersonalSubject =
4611
4625
  ;
4612
4626
  ```
4613
4627
 
4628
+ ## packages/types/src/presence-types.ts
4629
+
4630
+ ```ts
4631
+ type PresenceActivity = "viewing" | "editing";
4632
+ type PresenceEntry = {
4633
+ userId: string;
4634
+ displayName: string;
4635
+ activity: PresenceActivity;
4636
+ focus?: string;
4637
+ since: string; // ISO timestamp from which the user has been in this activity and focus.
4638
+ };
4639
+ ```
4640
+
4614
4641
  ## packages/types/src/projection.ts
4615
4642
 
4616
4643
  ```ts
@@ -4794,6 +4821,8 @@ type EditFieldsSectionBase = {
4794
4821
  icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
4795
4822
  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
4796
4823
  subtitle?: string; // Short line (i18n key) under this step's title in the wizard step rail and in the "up next" box.
4824
+ upNextHint?: string; // Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`.
4825
+ summaryField?: string; // Wizard layouts only: field of this section whose formatted value shows under the step label in the step rail once the step is done.
4797
4826
  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
4798
4827
  };
4799
4828
  type EntityEditActionPlacement = "inline" | "menu";
@@ -4823,6 +4852,7 @@ type RowActionNavigateBase = {
4823
4852
  params?: RowFieldExtractor; // Declarative URL search params extracted from the clicked row.
4824
4853
  tab?: string; // Section id of the tab to activate on the target projectionDetail (layout.mode "tabs"); merged into the navigate search params next to returnTo.
4825
4854
  visible?: FieldCondition; // Conditional visibility per row.
4855
+ showOnTabs?: string[]; // projectionDetail header action only: shown while one of these tab (section) ids is active.
4826
4856
  style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
4827
4857
  rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
4828
4858
  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
package/agents/api.md CHANGED
@@ -8,13 +8,13 @@ Format: one line per function or constant, object and options types as property
8
8
 
9
9
  | Import path | File | Exports |
10
10
  | --- | --- | --- |
11
- | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 426 |
12
- | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 25 |
11
+ | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 440 |
12
+ | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
13
  | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 156 |
14
14
  | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 151 |
15
15
  | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |
16
16
  | `@cosmicdrift/kumiko-framework/seeding` | `api/framework-seeding.md` | 6 |
17
- | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 325 |
17
+ | `@cosmicdrift/kumiko-renderer/web` | `api/renderer-web.md` | 344 |
18
18
  | `@cosmicdrift/kumiko-testing/stack` | `api/testing-stack.md` | 22 |
19
19
  | `@cosmicdrift/kumiko-testing/helpers` | `api/testing-helpers.md` | 71 |
20
20
  | `@cosmicdrift/kumiko-dev-server/testing` | `api/dev-server-testing.md` | 5 |
@@ -366,7 +366,10 @@
366
366
  | <a id="form-tab-title-missing"></a>`form/tab-title-missing` | Every tab section has a non-empty title. | Give each tab section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
367
367
  | <a id="form-tabs-too-few-sections"></a>`form/tabs-too-few-sections` | A tabs layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
368
368
  | <a id="form-tabs-unsupported-screen-type"></a>`form/tabs-unsupported-screen-type` | Tabs layout is used only on projectionDetail and entityEdit screens. | Use mode: "wizard" or "single". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
369
+ | <a id="form-wizard-option-without-wizard"></a>`form/wizard-option-without-wizard` | layout.wizard.saveAndCloseOnCreate, submitDisabledWhen, aside.finishDescription and section summaryField are set only on a wizard layout. | Remove the option or set mode: "wizard". | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
369
370
  | <a id="form-wizard-step-title-missing"></a>`form/wizard-step-title-missing` | Every wizard section has a non-empty title. | Give each wizard section a title. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
371
+ | <a id="form-wizard-submit-condition-field-unknown"></a>`form/wizard-submit-condition-field-unknown` | layout.wizard.submitDisabledWhen names a field of the layout. | Use a field name declared in one of the sections. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
372
+ | <a id="form-wizard-summary-field-unknown"></a>`form/wizard-summary-field-unknown` | A wizard section summaryField names a field of that section. | Use a field name declared in the section. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
370
373
  | <a id="form-wizard-too-few-sections"></a>`form/wizard-too-few-sections` | A wizard layout has at least two sections. | Add a section or use another mode. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
371
374
  | <a id="form-write-form-section-unsupported"></a>`form/write-form-section-unsupported` | Inline form layouts have no writeForm sections. | Move the section to a projectionDetail screen or remove it. | `packages/framework/src/engine/boot-validator/screens-forms-layout-rules.ts` |
372
375
  | <a id="form-write-only-field"></a>`form/write-only-field` | Inline form fields do not declare writeOnly. | Remove writeOnly; use format: "password" for a masked input. | `packages/framework/src/engine/boot-validator/screens-forms-rules.ts` |
@@ -642,6 +645,7 @@
642
645
 
643
646
  | Rule | Summary | Fix | Source |
644
647
  | --- | --- | --- | --- |
648
+ | <a id="projection-detail-action-show-on-tabs-invalid"></a>`projection-detail/action-show-on-tabs-invalid` | A header action showOnTabs is non-empty, names section ids of the screen and needs layout.mode "tabs". | List existing section ids or remove showOnTabs. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
645
649
  | <a id="projection-detail-extension-contributes-to-form-submit"></a>`projection-detail/extension-contributes-to-form-submit` | A projectionDetail extension section does not set contributesToFormSubmit. | Omit contributesToFormSubmit and persist through the extension's own dispatcher writes. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
646
650
  | <a id="projection-detail-extension-entity-name-missing"></a>`projection-detail/extension-entity-name-missing` | A projectionDetail extension section declares entityName. | Set entityName to the domain entity the extension persists against. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |
647
651
  | <a id="projection-detail-header-with-record-title-field"></a>`projection-detail/header-with-record-title-field` | A projectionDetail with a header sets no recordTitleField. | Drop recordTitleField; header.title names the record. | `packages/framework/src/engine/boot-validator/screens-kind-projection-detail-rules.ts` |