@cosmicdrift/kumiko-framework 0.393.0 → 0.395.0

package/agents/features.md

@@ -82,7 +82,7 @@ Runtime on/off switch for the auth-email-password self-signup flow. Handler-less
 
 ## billing-foundation
 
-Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.
+Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-paddle` unless you are writing a new payment provider.
 
 Category: billing
 
@@ -389,7 +389,7 @@ Requires: `tenant-lifecycle`
 
 ## inbound-provider-imap
 
-Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the "Connect mailbox" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.
+Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a shared mailbox through the "Connect mailbox" form on the mail accounts list and members a personal one through the same form on "My mail accounts" (`connect-mailbox` and `connect-my-mailbox` check the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.
 
 Category: notifications
 
@@ -473,7 +473,7 @@ Secrets:
 
 ## managed-pages
 
-Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.
+Tenant-editable, server-rendered public pages with per-tenant branding. Stores one `page` (Markdown or editor-document HTML body, per `bodyFormat`) per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core and document bodies through the template-resolver document sanitizer, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.
 
 Category: content
 
@@ -622,9 +622,17 @@ Category: infrastructure
 
 Requires: `secrets`
 
-## subscription-dodo
+## subscription-mollie
+
+Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType="first"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.
+
+Category: billing
+
+Requires: `billing-foundation`
+
+## subscription-paddle
 
-Dodo Payments provider plugin for `billing-foundation`. Dodo acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key and webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant), plus a `billingLive` master switch and an `environment` key (test | live). `environment` is its own key because Dodo serves test and live mode from different API hosts and a live key must never hit the test host or the other way round; `billingLive` only decides whether checkouts are offered at all. All four are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionDodoFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env to secrets bridge fallbacks (`DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true. Webhooks arrive at `/api/subscription/webhook/dodo` and are verified per the Standard Webhooks spec (HMAC-SHA256 over id, timestamp and the raw body, 5 minute tolerance); events for products outside `priceToTier` or without tenant metadata are dropped. Implements hosted checkout, customer portal, cancel and resume, `retrievePrices` (10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `plan_changed` webhook to move the tier. A plan switch in Dodo requires all plan products to belong to one Product Collection.
+Paddle Billing provider plugin for `billing-foundation`. Paddle acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key, webhook secret and tenant binding key from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant), the public Paddle.js `client-token`, a `billingLive` master switch and an `environment` key (sandbox | live). `environment` is its own key because Paddle serves sandbox and live from different API hosts and a live key must never hit the sandbox host or the other way round; `billingLive` only decides whether checkouts are offered at all. All of them are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionPaddleFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret`/`tenantBindingKey`/`clientToken` options are env to config bridge fallbacks (`PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TENANT_BINDING_KEY`, `PADDLE_CLIENT_TOKEN`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, and billing counts as enabled only with API key and binding key present. Webhooks arrive at `/webhooks/subscription/paddle` when mounted through the server-runtime `billing.paddle` boot option, or at `/api/subscription/webhook/paddle` when `createSubscriptionWebhookRoute` is mounted by hand and are verified with the `Paddle-Signature` header (HMAC-SHA256 over `ts:rawBody` keyed with the raw secret, any `h1` may match, 5 minute tolerance). Paddle.js can open checkouts with arbitrary `customData` from the browser, so `custom_data.tenantId` is only trusted together with `tenantBinding`, an HMAC of the tenant id under the binding key; events without a valid binding, for prices outside `priceToTier` or without a tenant are dropped. Rotating the binding key makes the webhooks of existing subscriptions fail that check until they are re-bound. Paddle has no hosted checkout page, so the feature serves the Default Payment Link itself at `/billing/paddle-checkout` (the Default Payment Link in the Paddle dashboard must point to `<APP_BASE_URL>/billing/paddle-checkout`; it is the only source, because checkouts are created without a `checkout.url`). Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries `quantity` and the app has to multiply its credits by it: an anonymous page with its own CSP that loads Paddle.js from cdn.paddle.com, the one external script this framework allows, and opens the overlay for the transaction. Implements checkout, customer portal, cancel and resume, `retrievePrices` (batched, 10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `subscription.updated` webhook to move the tier.
 
 Category: billing
 
@@ -636,17 +644,11 @@ Config keys:
 | --- | --- | --- | --- |
 | `api-key` | text | system |  |
 | `billing-live` | boolean | system | `false` |
-| `environment` | select | system | `test` |
+| `client-token` | text | system |  |
+| `environment` | select | system | `sandbox` |
+| `tenant-binding-key` | text | system |  |
 | `webhook-secret` | text | system |  |
 
-## subscription-mollie
-
-Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType="first"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.
-
-Category: billing
-
-Requires: `billing-foundation`
-
 ## subscription-stripe
 
 Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog), `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), `retrieveSubscription` (live provider-side snapshot for the `sync-subscriptions` backfill job, mapped identically to the webhook path), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).
@@ -671,7 +673,7 @@ Category: data
 
 ## template-resolver
 
-Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with `access` are always served. A collection mounted without `access` is SystemAdmin only. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
+Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with `access` are always served. A collection mounted without `access` is SystemAdmin only. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area that stores text, `document` a WYSIWYG document editor that stores sanitized HTML (bold, italic, headings, lists, links, variable chips). Both offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
 
 Category: notifications
 

package/agents/widgets.md

@@ -77,7 +77,6 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `ResizablePanelGroup` |  |
 | `ResultPanel` | Result section for a calculator: SectionCard with an empty state (Banner) or a metric list (DetailList) plus optional extras (table, notes). |
 | `ResultTable` | Static, prop-driven result table for calculated rows (tranches, scenarios). |
-| `RichContentEditor` |  |
 | `ScreenWidthProvider` |  |
 | `SectionCard` | Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens. |
 | `SelectField` | Select field = Field + Input(kind:"select"). |
@@ -115,6 +114,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | --- | --- |
 | `useBrowserNavApi` | React hook that builds a NavApi from browser history. |
 | `useBrowserTokensApi` | Builds a TokensApi for the browser. |
+| `useDispatchTarget` | Recommended production dispatch. |
 | `useDispatcher` |  |
 | `useDispatcherStatus` |  |
 | `useDraft` | Form state for calculator screens: a draft object plus `patch` for partial updates, and `field(name)` that provides `{ id, name, value, onChange }` props ready for field widgets (NumberField/MoneyField/PercentField). |

package/dist/api/entity-read-access.d.ts

@@ -1,5 +1,6 @@
 import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
 import type { OwnershipMap } from "@cosmicdrift/kumiko-types/ownership";
 import type { Registry } from "../engine/types/index.ts";
+export declare function assertNoAggregateTypeKeyCollisions(registry: Registry): void;
 export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;
 export declare function collectEntityRowReadMaps(registry: Registry): ReadonlyMap<string, OwnershipMap>;

package/dist/api/entity-read-access.js

@@ -1,12 +1,26 @@
+import { toKebab } from "@cosmicdrift/kumiko-types/kebab-case";
+// Both collectors key by the entity name and its kebab-case form, so two registered names that
+// fold to the same key (billing.period / billingPeriod) would merge their rules or overwrite each
+// other's row maps: fail at boot instead of leaking or hiding signals.
+export function assertNoAggregateTypeKeyCollisions(registry) {
+    const nameByKey = new Map();
+    for (const entityName of registry.getAllEntities().keys()) {
+        for (const key of new Set([entityName, toKebab(entityName)])) {
+            const other = nameByKey.get(key);
+            if (other !== undefined && other !== entityName) {
+                throw new Error(`Entities "${other}" and "${entityName}" map to the same live-signal aggregate type "${key}"; rename one of them.`);
+            }
+            nameByKey.set(key, entityName);
+        }
+    }
+}
 // Access rules of the query handlers that let a role read an entity (the
 // handler's own entity or one it declares via liveEntities). A live signal
 // carries the id of every row of the entity, so a signed-in connection gets it
 // only when one of these rules grants its roles. An aggregate type without a
 // reading query has no entry and is never put on the tenant channel.
-function toKebabCase(name) {
-    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
 export function collectEntityReadAccess(registry) {
+    assertNoAggregateTypeKeyCollisions(registry);
     const rulesByEntity = new Map();
     for (const [handlerName, handler] of registry.getAllQueryHandlers()) {
         const entities = new Set(handler.liveEntities ?? []);
@@ -16,7 +30,7 @@ export function collectEntityReadAccess(registry) {
         for (const entityName of entities) {
             // Executors may write under the kebab-case form of the camelCase r.entity() name
             // (document-extract for documentExtract); the signal carries that aggregate type.
-            for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+            for (const aggregateType of new Set([entityName, toKebab(entityName)])) {
                 const rules = rulesByEntity.get(aggregateType) ?? [];
                 rules.push(handler.access);
                 rulesByEntity.set(aggregateType, rules);
@@ -28,12 +42,13 @@ export function collectEntityReadAccess(registry) {
 // Entities whose own access.read narrows rows per role (e.g. Driver sees only assigned rows).
 // A signal for such an entity must not name ids to a role that does not read every row.
 export function collectEntityRowReadMaps(registry) {
+    assertNoAggregateTypeKeyCollisions(registry);
     const mapsByEntity = new Map();
     for (const [entityName, entity] of registry.getAllEntities()) {
         const readMap = entity.access?.read;
         if (readMap === undefined || Object.keys(readMap).length === 0)
             continue;
-        for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+        for (const aggregateType of new Set([entityName, toKebab(entityName)])) {
             mapsByEntity.set(aggregateType, readMap);
         }
     }

package/dist/api/server-event-dispatcher.js

@@ -2,9 +2,11 @@ import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { runsInLane } from "../engine/run-in.js";
 import { createTenantFileContext } from "../files/file-handle.js";
+import { catchUpEventTypesOf, createCatchUpJobEventConsumer, } from "../pipeline/catch-up-job-consumer.js";
 import { createEventDispatcher, } from "../pipeline/event-dispatcher.js";
+import { createJobTriggerEventConsumer } from "../pipeline/job-trigger-consumer.js";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
-import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
+import { createAccessInvalidationEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 export function createServerEventDispatcher(deps) {
     const { options, context, sseBroker, observability, fileProviderResolver, instanceId } = deps;
@@ -27,7 +29,8 @@ export function createServerEventDispatcher(deps) {
         context,
         fileProviderResolver,
     });
-    const consumers = [...systemConsumers, ...mspConsumers];
+    const catchUpJobConsumers = buildCatchUpJobConsumers(options, baseDb);
+    const consumers = [...systemConsumers, ...mspConsumers, ...catchUpJobConsumers];
     const { disabled: dispatcherDisabled, systemConsumers: _systemConsumersOpt, ...dispatcherTunables } = options.eventDispatcher ?? {};
     let eventDispatcher;
     if (consumers.length > 0 && baseDb && !dispatcherDisabled) {
@@ -82,6 +85,24 @@ function buildSystemEventConsumers(options, sseBroker, searchAdapter) {
     }
     return systemConsumers;
 }
+function buildCatchUpJobConsumers(options, baseDb) {
+    const jobRunner = options.dispatcherOptions?.jobRunner;
+    if (!jobRunner || !baseDb)
+        return [];
+    const upcast = { db: baseDb, upcasters: options.registry.getEventUpcasters() };
+    if (!(options.eventDispatcher?.systemConsumers?.jobTrigger ?? true))
+        return [];
+    const processLane = options.processLane ?? "worker";
+    const consumers = [];
+    for (const [jobName, jobDef] of options.registry.getAllJobs()) {
+        if (!("on" in jobDef.trigger) || !jobDef.trigger.catchUp)
+            continue;
+        if (!runsInLane(jobDef.runIn, processLane))
+            continue;
+        consumers.push(createCatchUpJobEventConsumer(jobRunner, jobName, options.registry.getJobFeature(jobName), catchUpEventTypesOf(jobDef.trigger), upcast));
+    }
+    return consumers;
+}
 function buildMultiStreamProjectionConsumers(options, deps) {
     const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
     const mspJobs = jobRunnerForTriggers?.dispatch

package/dist/compliance/profiles.js

@@ -35,7 +35,7 @@ const RAW_PROFILES = {
     "eu-dsgvo": {
         key: "eu-dsgvo",
         region: "EU",
-        label: "EU — DSGVO Standard",
+        label: "EU — GDPR standard",
         userRights: {
             gracePeriod: { days: 30 },
             restrictionAllowed: true,
@@ -69,7 +69,7 @@ const RAW_PROFILES = {
     "swiss-dsg": {
         key: "swiss-dsg",
         region: "CH",
-        label: "Schweiz — Bundesgesetz über den Datenschutz (rev. 2023)",
+        label: "Switzerland — Federal Act on Data Protection (rev. 2023)",
         extends: "eu-dsgvo",
         notifications: {
             languages: ["de", "fr", "it", "en"],
@@ -84,7 +84,7 @@ const RAW_PROFILES = {
     "de-hr-dsgvo-hgb": {
         key: "de-hr-dsgvo-hgb",
         region: "DE",
-        label: "Deutschland HR — DSGVO + HGB + Personalakten",
+        label: "Germany HR — GDPR + HGB + personnel files",
         extends: "eu-dsgvo",
         userRights: {
             gracePeriod: { days: 30 },
@@ -121,7 +121,7 @@ const RAW_PROFILES = {
     "minimal-no-region": {
         key: "minimal-no-region",
         region: "—",
-        label: "Minimal — kein Compliance-Profile (NICHT für Production)",
+        label: "Minimal — no compliance profile (NOT for production)",
         userRights: {
             gracePeriod: { days: 30 },
             restrictionAllowed: false,

package/dist/crypto/index.d.ts

@@ -4,6 +4,7 @@ export { InMemoryKmsAdapter } from "./in-memory-kms-adapter.ts";
 export { isSelfPiiField } from "./is-self-pii-field.ts";
 export { resolvePlatformKeks } from "./kek-source.ts";
 export { KeyAlreadyExistsError, KeyErasedError, type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, type SubjectId, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.ts";
+export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.ts";
 export { type KmsWiring, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.ts";
 export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.ts";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.ts";

package/dist/crypto/index.js

@@ -4,6 +4,7 @@ export { InMemoryKmsAdapter } from "./in-memory-kms-adapter.js";
 export { isSelfPiiField } from "./is-self-pii-field.js";
 export { resolvePlatformKeks } from "./kek-source.js";
 export { KeyAlreadyExistsError, KeyErasedError, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForUser, } from "./kms-adapter.js";
+export { ENCRYPTION_UNAVAILABLE_CODE, EncryptionUnavailableError } from "./kms-outage.js";
 export { requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
 export { createPgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";

package/dist/crypto/kms-outage.d.ts

@@ -0,0 +1,8 @@
+import { KumikoError } from "../errors/kumiko-error.ts";
+export declare const ENCRYPTION_UNAVAILABLE_CODE = "encryption_unavailable";
+export declare class EncryptionUnavailableError extends KumikoError {
+    readonly code = "encryption_unavailable";
+    readonly httpStatus = 503;
+    constructor(cause?: Error);
+}
+export declare function classifyKmsOutage<T>(call: () => Promise<T>): Promise<T>;

package/dist/crypto/kms-outage.js

@@ -0,0 +1,33 @@
+import { KumikoError } from "../errors/kumiko-error.js";
+import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError } from "./kms-adapter.js";
+export const ENCRYPTION_UNAVAILABLE_CODE = "encryption_unavailable";
+// The key store failed (database, Key Manager, network), so nothing could be encrypted or decrypted.
+// A caller retries later: the outage says nothing about the record it was writing.
+export class EncryptionUnavailableError extends KumikoError {
+    code = ENCRYPTION_UNAVAILABLE_CODE;
+    httpStatus = 503;
+    constructor(cause) {
+        super({
+            message: "the PII key store is unavailable",
+            i18nKey: "errors.internal",
+            ...(cause && { cause }),
+        });
+    }
+}
+function isKeyStateError(error) {
+    return (error instanceof KeyErasedError ||
+        error instanceof KeyNotFoundError ||
+        error instanceof KeyAlreadyExistsError);
+}
+// Key-state errors are answers of a working key store and keep their own type for the callers that
+// branch on them; everything else thrown by the adapter is the store itself failing.
+export async function classifyKmsOutage(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (isKeyStateError(error) || error instanceof KumikoError)
+            throw error;
+        throw new EncryptionUnavailableError(error instanceof Error ? error : undefined);
+    }
+}

package/dist/crypto/pii-field-encryption.js

@@ -17,6 +17,7 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { assertIrreversibleOperationAllowed } from "../pipeline/irreversible-operation-gate.js";
 import { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, PII_ERASED_SENTINEL, subjectIdFromKey, subjectIdToKey, } from "./kms-adapter.js";
+import { classifyKmsOutage } from "./kms-outage.js";
 import { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_CIPHERTEXT_PREFIX_V1, } from "./pii-ciphertext-format.js";
 import { resolveSubjectForField } from "./subject-resolver.js";
 // Spec value (crypto-shredding.md) — renderers show it verbatim.
@@ -219,12 +220,12 @@ let injectedKms;
 function gateIrreversibleKmsErase(adapter) {
     return {
         capabilities: adapter.capabilities,
-        createKey: (subject, ctx) => adapter.createKey(subject, ctx),
-        getKey: (subject, ctx) => adapter.getKey(subject, ctx),
+        createKey: (subject, ctx) => classifyKmsOutage(() => adapter.createKey(subject, ctx)),
+        getKey: (subject, ctx) => classifyKmsOutage(() => adapter.getKey(subject, ctx)),
         health: () => adapter.health(),
         eraseKey: async (subject, ctx) => {
             assertIrreversibleOperationAllowed("kms.eraseKey");
-            await adapter.eraseKey(subject, ctx);
+            await classifyKmsOutage(() => adapter.eraseKey(subject, ctx));
         },
     };
 }

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -8,7 +8,6 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 export declare function validateHandlerAccess(feature: FeatureDefinition): void;
 export declare function validateAdditionalRateLimits(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
-export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitCost(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -5,6 +5,7 @@ import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key.js";
 import { access as accessPresets } from "../config-helpers.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
+import { validateBeforeTransactionWhenNested, validatePerCommandTransaction, } from "./transaction-phases.js";
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
 // Field names that typically contain PII. Without a `pii: true` /
 // `userOwned` / `tenantOwned` / `allowPlaintext` marker → boot warning.
@@ -141,6 +142,7 @@ export function validateHandlerAccess(feature) {
         validateAdditionalRateLimits(feature.name, name, handler);
         validateRateLimitCost(feature.name, name, handler);
         validatePerCommandTransaction(feature.name, name, handler);
+        validateBeforeTransactionWhenNested(feature.name, name, handler);
     }
 }
 const IP_BUCKETED_RATE_LIMIT_PER = new Set(["ip", "ip+handler"]);
@@ -196,22 +198,6 @@ function validatePayloadBucket(where, shape, entry) {
         throw new Error(`${where} for "${field}" with windowSeconds ${entry.windowSeconds} — must be a positive integer.`);
     }
 }
-function perCommandConflict(handler) {
-    if (handler.transaction !== "perCommand")
-        return undefined;
-    if (handler.beforeTransaction)
-        return "beforeTransaction";
-    if (handler.reserveBeforeTransaction)
-        return "reserveBeforeTransaction";
-    return undefined;
-}
-export function validatePerCommandTransaction(featureName, handlerName, handler) {
-    const conflicting = perCommandConflict(handler);
-    if (conflicting !== undefined) {
-        throw new Error(`write handler "${featureName}:write:${handlerName}" declares transaction: "perCommand" together with ${conflicting} — ` +
-            "a perCommand handler holds no transaction, so move the phase into the commands it issues via ctx.dispatch.write.");
-    }
-}
 const IP_SCOPED_RATE_LIMIT_PER = ["ip", "ip+handler"];
 export function validateTenantlessAnonymous(featureName, handlerName, handler) {
     // skip: handler does not opt into tenantless anonymous calls

package/dist/engine/boot-validator/query-output-columns.js

@@ -198,12 +198,19 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
         // contract with no author-declared field names to check.
     }
 }
+function checkToolbarVisibleWhenFields(queryHandlers, featureName, screenId, screen) {
+    for (const action of screen.toolbarActions ?? []) {
+        checkVisibleWhenField(queryHandlers, action.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) toolbarAction "${action.id}"`);
+    }
+}
 function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen) {
     checkVisibleWhenField(queryHandlers, screen.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (${screen.type})`);
     if (screen.type === "projectionList") {
+        checkToolbarVisibleWhenFields(queryHandlers, featureName, screenId, screen);
         checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen);
     }
     else if (screen.type === "entityList") {
+        checkToolbarVisibleWhenFields(queryHandlers, featureName, screenId, screen);
         if (screen.expandableRow !== undefined) {
             const rowShape = resolveListRowShape(queryHandlers, screen.expandableRow.query, `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow.title}"`);
             for (const column of screen.expandableRow.columns) {

package/dist/engine/boot-validator/query-refs.js

@@ -110,6 +110,13 @@ function checkEditFormScreenQueryRefs(queryHandlers, featureName, screenId, scre
         checkFormFieldQueryRefs(queryHandlers, featureName, screenId, "secretMint confirm", screen.confirm.fields);
     }
 }
+function checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen) {
+    for (const action of screen.toolbarActions ?? []) {
+        if (action.visibleWhen === undefined)
+            continue;
+        checkVisibleWhenQueryRef(queryHandlers, action.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) toolbarAction "${action.id}" visibleWhen`);
+    }
+}
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
     if (screen.visibleWhen !== undefined) {
         const { idParam } = screen.visibleWhen;
@@ -121,8 +128,10 @@ function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
     }
     if (screen.type === "projectionList") {
         checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
+        checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
     }
     else if (screen.type === "entityList") {
+        checkToolbarVisibleWhenQueryRefs(queryHandlers, featureName, screenId, screen);
         if (screen.expandableRow !== undefined) {
             checkQueryRef(queryHandlers, screen.expandableRow.query, () => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}"`);
         }

package/dist/engine/boot-validator/screens-actions.js

@@ -1,5 +1,6 @@
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
+import { fallbackTargets, SCREEN_FALLBACK_REASONS, } from "@cosmicdrift/kumiko-types/screen";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
 import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
@@ -465,7 +466,25 @@ export function validateScreenVisibleWhen(feature, screenId, screen, allScreenQn
         validateScreenFallback(feature, screenId, screen.type, fallback, allScreenQns, featureMap);
     }
 }
+function assertFallbackMapShape(context, fallback) {
+    const reasons = Object.keys(fallback);
+    if (reasons.length === 0) {
+        throw new Error(`${context} fallback map is empty. Set at least one of ${SCREEN_FALLBACK_REASONS.join(", ")} or use a screen id string.`);
+    }
+    const unknownReason = reasons.find((reason) => !isOneOf(SCREEN_FALLBACK_REASONS, reason));
+    if (unknownReason !== undefined) {
+        throw new Error(`${context} fallback has unknown reason "${unknownReason}". Use ${SCREEN_FALLBACK_REASONS.join(", ")}.`);
+    }
+}
 function validateScreenFallback(feature, screenId, screenType, fallback, allScreenQns, featureMap) {
+    if (typeof fallback !== "string") {
+        assertFallbackMapShape(`[Feature ${feature.name}] Screen "${screenId}" (${screenType})`, fallback);
+    }
+    for (const target of fallbackTargets(fallback)) {
+        validateFallbackTarget(feature, screenId, screenType, target, allScreenQns, featureMap);
+    }
+}
+function validateFallbackTarget(feature, screenId, screenType, fallback, allScreenQns, featureMap) {
     const context = `[Feature ${feature.name}] Screen "${screenId}" (${screenType})`;
     validateScreenNavTarget(feature.name, screenId, screenType, "fallback", fallback, allScreenQns, feature.screens);
     const fallbackQn = resolveScreenTargetQn(feature.name, fallback);

package/dist/engine/boot-validator/screens-dashboard.d.ts

@@ -1,5 +1,5 @@
 import type { FeatureDefinition } from "../types/index.ts";
-import type { DashboardCustomPanel, DashboardScreenDefinition, DashboardScreenPanel } from "../types/screen.ts";
+import type { DashboardCustomPanel, DashboardPanelVisibility, DashboardScreenDefinition, DashboardScreenPanel } from "../types/screen.ts";
 import { resolveRowActionNavigateTarget } from "./screens-actions.ts";
 export declare function validateDashboardScreen(featureName: string, screenId: string, screen: DashboardScreenDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
 type DashboardActionNavLookups = {
@@ -10,6 +10,7 @@ type DashboardActionNavLookups = {
 };
 export declare function validateDashboardActions(featureName: string, screenId: string, screen: DashboardScreenDefinition, allWriteHandlerQns: ReadonlySet<string>, lookups: DashboardActionNavLookups): void;
 export declare function validateDashboardRecordBinding(featureName: string, screenId: string, screen: DashboardScreenDefinition): void;
-export declare function validateDashboardScreenPanel(featureName: string, screenId: string, panel: DashboardScreenPanel, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
+export declare function validateDashboardScreenPanel(featureName: string, screenId: string, panel: DashboardScreenPanel, featureMap: ReadonlyMap<string, FeatureDefinition>, hostHasRecord: boolean | undefined): void;
+export declare function validateDashboardPanelVisibleWhen(context: string, visibleWhen: DashboardPanelVisibility | undefined): void;
 export declare function validateDashboardCustomPanel(featureName: string, screenId: string, panel: DashboardCustomPanel): void;
 export {};

package/dist/engine/boot-validator/screens-dashboard.js

@@ -26,7 +26,7 @@ export function validateDashboardScreen(featureName, screenId, screen, featureMa
             validateDashboardCustomPanel(featureName, screenId, panel);
         }
         else if (panel.kind === "screen") {
-            validateDashboardScreenPanel(featureName, screenId, panel, featureMap);
+            validateDashboardScreenPanel(featureName, screenId, panel, featureMap, screen.record !== undefined);
         }
         else if (panel.kind === "text") {
             validateDashboardTextPanel(featureName, screenId, panel, featureMap);
@@ -166,12 +166,13 @@ function validateDashboardTimeRange(featureName, screenId, timeRange, filterId)
 }
 const EMBEDDABLE_SCREEN_TYPES = new Set([
     "projectionList",
+    "projectionDetail",
     "actionForm",
     "secretMint",
     "configEdit",
     "secretsEdit",
 ]);
-function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap) {
+function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap, hostHasRecord) {
     const targetQn = resolveScreenTargetQn(featureName, ref);
     const [targetFeatureName = "", , targetShortId = ""] = targetQn.split(":");
     const target = featureMap.get(targetFeatureName)?.screens[targetShortId];
@@ -183,6 +184,12 @@ function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap
         throw new Error(`${context} embeds "${targetQn}" of type "${target.type}", which can't be embedded — allowed: ` +
             `${[...EMBEDDABLE_SCREEN_TYPES].join(", ")}. Use a custom panel for app components.`);
     }
+    // The tile hands the dashboard's bound record id to the detail screen; without a binding it has no id.
+    // undefined = host unknown (extension-selector panels), checked nowhere else.
+    if (target.type === "projectionDetail" && hostHasRecord === false) {
+        throw new Error(`${context} embeds "${targetQn}", a projectionDetail, but the host dashboard has no record binding ` +
+            `to take its id from. Add record: { param } to the dashboard or embed another screen type.`);
+    }
     // ActionFormBody/SecretMintBody navigate via nav.navigate after submit or
     // cancel even when embedded, which would pull the user off the dashboard.
     if ((target.type === "actionForm" || target.type === "secretMint") &&
@@ -194,9 +201,9 @@ function validateEmbeddableScreenRef(context, prop, ref, featureName, featureMap
     }
     return target;
 }
-export function validateDashboardScreenPanel(featureName, screenId, panel, featureMap) {
+export function validateDashboardScreenPanel(featureName, screenId, panel, featureMap, hostHasRecord) {
     const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`;
-    validateEmbeddableScreenRef(context, "screen", panel.screen, featureName, featureMap);
+    validateEmbeddableScreenRef(context, "screen", panel.screen, featureName, featureMap, hostHasRecord);
     validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
     // skip: no fallback declared, nothing more to validate
     if (panel.fallback === undefined)
@@ -204,7 +211,7 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
     if (panel.visibleWhen === undefined) {
         throw new Error(`${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`);
     }
-    const target = validateEmbeddableScreenRef(context, "fallback", panel.fallback, featureName, featureMap);
+    const target = validateEmbeddableScreenRef(context, "fallback", panel.fallback, featureName, featureMap, hostHasRecord);
     // A gated fallback could hide in turn; the tile would show nothing where it promised a stand-in.
     if (target.visibleWhen !== undefined) {
         throw new Error(`${context} fallback "${panel.fallback}" has its own visibleWhen; a fallback must always render.`);
@@ -237,7 +244,7 @@ function validateDashboardTextLinkBlock(context, block, featureName, featureMap)
             `List the roles or omit roles.`);
     }
 }
-function validateDashboardPanelVisibleWhen(context, visibleWhen) {
+export function validateDashboardPanelVisibleWhen(context, visibleWhen) {
     if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
         throw new Error(`${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`);
     }

package/dist/engine/boot-validator/screens-kind-entity-list.js

@@ -8,6 +8,7 @@ import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
 import { validateListBulkActions } from "./list-bulk-actions.js";
 import { validateListTableOptions } from "./list-table-options.js";
 import { assertWriteHandlerRegistered, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateActionFieldRefs, validateAtMostOneRowClick, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { validateDashboardPanelVisibleWhen } from "./screens-dashboard.js";
 import { buildUnknownFieldMessage, listActionContext, rejectEmptyColumns, rejectNonArrayInFilter, resolveScreenEntity, validateListColumnRendering, } from "./screens-kind-shared.js";
 import { validateRelatedListSection, validateRowActionTarget } from "./screens-lists.js";
 function resolveEntityListFields(ctx, screenId, entityName) {
@@ -156,6 +157,7 @@ function validateEntityListRowAction(ctx, screenId, screen, fields, action) {
 // unregistered writeHandler QNs fail at boot instead of on the first click.
 function validateEntityListToolbarAction(ctx, screenId, fields, action) {
     const featureName = ctx.feature.name;
+    validateDashboardPanelVisibleWhen(`[Feature ${featureName}] Screen "${screenId}" (entityList) toolbarAction "${action.id}"`, action.visibleWhen);
     if (action.kind === "navigate") {
         const candidateQn = qualifyEntityName(featureName, "screen", action.screen);
         if (!ctx.allScreenQns.has(candidateQn) && !ctx.navTargetShortIds.has(action.screen)) {