@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/samples/apps/ui-walkthrough/src/run-config.ts

@@ -15,6 +15,7 @@ import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-featu
 import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
 import { createRendererMailHtmlFeature } from "@cosmicdrift/kumiko-renderer-mail-html";
+import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
 import { TENANT_ADMIN_EMAIL } from "./app/auth-constants";
 import { billingFeature } from "./features/billing";
 import { rentalFeature } from "./features/rental";
@@ -34,7 +35,23 @@ export const APP_FEATURES = [
   createDocumentDesignerFeature(),
   // Mounted individually: composeRendererStack() would add a second template-resolver.
   createRendererFoundationFeature(),
-  createRendererMailHtmlFeature(),
+  createRendererMailHtmlFeature({
+    footer: ({ locale }) =>
+      locale.startsWith("de")
+        ? {
+            text: "Gesendet über das Nordlicht Mieterportal",
+            imprint: { label: "Impressum", url: "https://nordlicht-immobilien.de/impressum" },
+            privacy: { label: "Datenschutz", url: "https://nordlicht-immobilien.de/datenschutz" },
+          }
+        : {
+            text: "Sent via the Nordlicht tenant portal",
+            imprint: { label: "Imprint", url: "https://nordlicht-immobilien.de/imprint" },
+            privacy: { label: "Privacy", url: "https://nordlicht-immobilien.de/privacy" },
+          },
+  }),
+  // The PDF preview of the template editor prints through the puppeteer-service
+  // (PUPPETEER_SERVICE_URL / PUPPETEER_AUTH_TOKEN); the e2e config starts one.
+  createRendererPuppeteerClientFeature(),
   createDeliveryFeature(),
   // In-memory transport: the test mail of the mail editor is rendered and
   // "sent" for real, nothing leaves the process. Every user resolves to the

package/samples/apps/use-all-bundled/README.md

@@ -33,24 +33,14 @@ Exits 0 on success; any feature-wiring fault throws and exits 1.
 
 ## Coverage status
 
-36/39 bundled-feature exports mounted, 3 held-back. M0.1 reduced this from 10. Held-back nach M0.1:
-
-- `auth-email-password` — auto-mounted via `composeFeatures(authOptions)` (no need to list)
-- `files-provider-s3` — utility helpers (`createS3Provider`), kein `defineFeature`
-- `foundation-shared` — pure utilities (`requireDefined`, `requireNonEmpty`), kein `defineFeature`
-
-The 3 remaining are utilities or auto-mounted — they cannot be added to `APP_FEATURES` by design.
+Every bundled-feature export is mounted except the held-back ones in `EXPECTED_HELD_BACK` (`scripts/check-coverage.ts`): utilities without `defineFeature` and scaffold-only features. They cannot be added to `APP_FEATURES` by design.
 
 ## Maintenance
 
 When you add a new feature-export to `@cosmicdrift/kumiko-bundled-features` you MUST either:
 
 1. Mount it in `src/run-config.ts`. `kumiko/schema.ts` picks up entities via
-   `composeFeatures(APP_FEATURES)` — then regenerate if schema changed:
-   ```sh
-   cd samples/apps/use-all-bundled
-   bun ../../bin/kumiko.ts schema generate feature-coverage
-   ```
+   `composeFeatures(APP_FEATURES)`; run `kumiko-schema generate` if the schema changed.
 2. Or, if the feature is not yet smoke-ready, add it to `EXPECTED_HELD_BACK` in `scripts/check-coverage.ts` with a one-line reason.
 
-CI fails otherwise via `Coverage lint (M5)`.
+CI fails otherwise via `Coverage lint`.

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1423,7 +1423,7 @@
     },
     {
       "name": "jobs",
-      "description": "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops its stuck `queued` rows.",
+      "description": "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],
@@ -2122,7 +2122,7 @@
     },
     {
       "name": "renderer-mail-html",
-      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, in-code `DEFAULT_MAIL_LAYOUT_MJML` as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
+      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation",
@@ -2170,7 +2170,7 @@
     },
     {
       "name": "renderer-puppeteer-client",
-      "description": "A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. `renderAndStorePdf(ctx, ...)` renders and stores the PDF as a file with a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 5xx and network errors with exponential backoff (default 3 retries), 4xx fails at once. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.",
+      "description": "A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. A write handler renders with `renderPdfBeforeTransaction(ctx, { slug, locale, variables })` as its `beforeTransaction` phase, so the print service call holds no database connection, and stores the result with `storeRenderedPdf(ctx, event.prepared)` in the handler: a file plus a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`, which must embed all resources as data: URIs because the service fetches no http(s) resources. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 5xx and network errors with exponential backoff (default 3 retries), 4xx fails at once. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation"
@@ -2563,7 +2563,7 @@
     },
     {
       "name": "template-resolver",
-      "description": "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`).\n\nReading 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`.\n\nText 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.\n\nHow 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).\n\nA 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.\n\n`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.\n\n`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.\n\nImages 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.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
+      "description": "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`).\n\nReading 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.\n\nText 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.\n\nHow 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).\n\nA 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.\n\n`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.\n\n`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.\n\nImages 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.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],
@@ -2601,6 +2601,8 @@
         "template-resolver:write:archive",
         "template-resolver:write:archive-system",
         "template-resolver:write:copy-locale",
+        "template-resolver:write:discard-draft",
+        "template-resolver:write:discard-draft-system",
         "template-resolver:write:import-bundle",
         "template-resolver:write:import-bundle-system",
         "template-resolver:write:publish",
@@ -3207,7 +3209,7 @@
     },
     {
       "name": "waitlist",
-      "description": "Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response never reveals whether an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.",
+      "description": "Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response body is identical whether or not an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.",
       "toggleableDefault": null,
       "requires": [
         "tenant",

package/samples/apps/use-all-bundled/scripts/check-coverage.ts

@@ -1,18 +1,13 @@
 #!/usr/bin/env bun
 // biome-ignore-all lint/suspicious/noConsole: CLI-Script, console ist Feature.
 //
-// C1 M5 coverage lint. Diffs bundled-features-Exports gegen den
-// FEATURE_IMPORT_REGISTRY in samples/apps/use-all-bundled/schema/
-// generate.ts. Fängt zwei Drifts:
+// Coverage lint. Diffs die Top-Level-Exports von bundled-features gegen die Features, die
+// use-all-bundled mountet (FEATURES aus kumiko/schema.ts: APP_FEATURES plus die von
+// composeFeatures ergänzten Auth-/Signup-Features). Fängt drei Drifts:
 //
-//   1. Ein neuer feature-export ohne Aufnahme in use-all-bundled
-//      → unreferenced exports
-//   2. Ein removed feature-export der noch im Registry steht
-//      → stale registry
-//
-// Held-back features für M0.1 (subscription-stripe, channel-email, …)
-// stehen in EXPECTED_HELD_BACK. Sobald sie mit stub-options gemountet
-// werden, müssen sie aus dieser Liste raus.
+//   1. Ein Export, der weder gemountet ist noch in EXPECTED_HELD_BACK steht
+//   2. Ein EXPECTED_HELD_BACK-Eintrag, der kein Export mehr ist
+//   3. Ein EXPECTED_HELD_BACK-Eintrag, der inzwischen gemountet ist (stale)
 //
 // Usage:
 //   bun samples/apps/use-all-bundled/scripts/check-coverage.ts
@@ -20,6 +15,7 @@
 
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { FEATURES } from "../kumiko/schema";
 
 const ROOT = resolve(import.meta.dir, "..");
 const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
@@ -27,33 +23,13 @@ const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
 // Held-back exports: existieren in bundled-features, sind aber nicht
 // als runtime-feature in use-all-bundled mountbar.
 //
-// Nach M0.1 nur noch utilities + auto-mounted:
-// - utilities: kein r.defineFeature (foundation-shared, files-provider-s3
-//   sind pure helpers).
-// - auto-mounted: kommt via composeFeatures(includeBundled:true) automatisch
-//   (auth-email-password) — wäre doppelt-mount wenn explizit gelistet.
+// Nur Utilities ohne defineFeature (foundation-shared, files-provider-s3 sind pure helpers)
+// und scaffold-only Features. Gemountete Features gehören nicht hierher.
 const EXPECTED_HELD_BACK = new Set([
-  "auth-email-password", // auto-mounted via composeFeatures(authOptions)
-  "agent-tools", // utility (buildToolCatalog: Registry -> ToolDefinition[]), kein defineFeature
   "files-provider-s3", // utility (createS3Provider helpers), kein defineFeature
   "foundation-shared", // utilities (requireDefined/requireNonEmpty), kein feature
   "page-render", // shared HTML render/cache helpers (legal/managed-pages), kein defineFeature
   "presets", // feature-bundle helpers (dsgvoSelfServiceFeatures, securityBaselineFeatures), kein defineFeature
-  "auth-foundation", // scaffold-only (#1368): bootCheck wirft ohne gemountete auth-provider-*, die es noch nicht gibt
-]);
-
-// Registry-only: mounted features that are NOT top-level package exports
-// (companion features living under another export path). schema-check still
-// needs them in FEATURE_IMPORT_REGISTRY; coverage must not flag them stale.
-const EXPECTED_REGISTRY_ONLY = new Set([
-  "auth-self-registration", // from ./auth-email-password, auto-mounted with signup (#1521)
-  "collection-labels", // app-local (src/app/), nav labels for this app's content collections
-  "cap-overview-labels", // app-local (src/app/), labels for this app's example cap-overview caps
-  "metrics-system", // from ./metrics, companion of createMetricsFeature (platform-wide scope)
-  "locale-de", // @cosmicdrift/kumiko-locale-de, not a bundled-features export
-  "renderer-mail-html", // @cosmicdrift/kumiko-renderer-mail-html, auto-mounted with auth by composeFeatures
-  "renderer-puppeteer-client", // @cosmicdrift/kumiko-renderer-puppeteer-client, not a bundled-features export
-  "document-designer", // @cosmicdrift/kumiko-document-designer, not a bundled-features export
 ]);
 
 // Sub-paths in bundled-features's package.json exports (./tenant/seeding,
@@ -87,120 +63,60 @@ function readBundledExports(): Set<string> {
   return out;
 }
 
-function extractRegistryBlock(src: string): string {
-  // Anchor auf den FEATURE_IMPORT_REGISTRY-Object-Body. Ohne diesen Anchor
-  // würde die kind-Regex jedes `<ident>: { kind: "factory"|"named" }` im File
-  // matchen (z.B. eine künftige Hilfsvariable) → false positive/negative.
-  const startMatch = /FEATURE_IMPORT_REGISTRY[^=]*=\s*\{/.exec(src);
-  if (!startMatch) {
-    throw new Error("check-coverage: FEATURE_IMPORT_REGISTRY block not found in generate.ts");
-  }
-  const bodyStart = startMatch.index + startMatch[0].length;
-  // Top-level-Close ist das erste `};` am Zeilenanfang nach bodyStart.
-  const closeMatch = /\n};/.exec(src.slice(bodyStart));
-  if (!closeMatch) {
-    throw new Error("check-coverage: FEATURE_IMPORT_REGISTRY closing `};` not found");
-  }
-  return src.slice(bodyStart, bodyStart + closeMatch.index);
-}
-
-function readRegistryFeatures(): Set<string> {
-  const generateSrc = readFileSync(resolve(ROOT, "schema", "generate.ts"), "utf-8");
-  const registryBlock = extractRegistryBlock(generateSrc);
-  // Match object-keys mit Discriminator `kind: "factory" | "named"`.
-  // Property-Keys können quoted ("billing-foundation") oder unquoted
-  // (config, user) sein — beides ist gültig wenn kebab-segment-free.
-  const re = /(?:"([a-z][a-z0-9-]*)"|([a-z][a-z0-9]*)):\s*\{\s*kind:\s*"(factory|named)"/g;
-  const out = new Set<string>();
-  for (const m of registryBlock.matchAll(re)) {
-    const name = m[1] ?? m[2];
-    if (name) out.add(name);
-  }
-  return out;
-}
-
 const exports = readBundledExports();
-const registry = readRegistryFeatures();
-
-const unreferenced: string[] = [];
-const stale: string[] = [];
-// Held-back-Einträge, die kein bundled-Export mehr sind → stale Konfig.
-// Ohne diese Prüfung hätte der Drift-Guard in seiner eigenen Konfig einen
-// Blind-Spot: ein umbenanntes/entferntes Feature bliebe still in der Liste.
-const staleHeldBack: string[] = [];
-
-for (const name of exports) {
-  if (registry.has(name)) continue;
-  if (EXPECTED_HELD_BACK.has(name)) continue;
-  unreferenced.push(name);
-}
-
-for (const name of registry) {
-  if (!exports.has(name) && !EXPECTED_REGISTRY_ONLY.has(name)) stale.push(name);
-}
+const mounted = new Set<string>(FEATURES.map((feature) => feature.name));
 
-for (const name of EXPECTED_HELD_BACK) {
-  if (!exports.has(name)) staleHeldBack.push(name);
-}
+const unreferenced = [...exports].filter(
+  (name) => !mounted.has(name) && !EXPECTED_HELD_BACK.has(name),
+);
+// Ohne diese Prüfungen hätte der Guard in seiner eigenen Konfig einen Blind-Spot: ein
+// umbenanntes oder entferntes Feature bliebe still in der Liste, ein gemountetes ebenso.
+const staleHeldBack = [...EXPECTED_HELD_BACK].filter((name) => !exports.has(name));
+const mountedHeldBack = [...EXPECTED_HELD_BACK].filter((name) => mounted.has(name));
 
 let ok = true;
 
 if (unreferenced.length > 0) {
   console.error(
-    `\n❌ ${unreferenced.length} bundled-feature export(s) NICHT in use-all-bundled/schema/generate.ts:`,
+    `\n❌ ${unreferenced.length} bundled-feature export(s) nicht in use-all-bundled gemountet:`,
   );
   for (const name of unreferenced.sort()) {
     console.error(`   - ${name}`);
   }
   console.error(
-    "\n  Action: in src/run-config.ts + schema/generate.ts FEATURE_IMPORT_REGISTRY aufnehmen,",
-  );
-  console.error(
-    "  oder (wenn mount-options noch fehlen) zu EXPECTED_HELD_BACK in dieser Datei hinzufügen.",
+    "\n  Action: in src/run-config.ts mounten, oder (wenn mount-options noch fehlen) zu EXPECTED_HELD_BACK in dieser Datei hinzufügen.",
   );
   ok = false;
 }
 
-if (stale.length > 0) {
+if (staleHeldBack.length > 0) {
   console.error(
-    `\n❌ ${stale.length} FEATURE_IMPORT_REGISTRY entry/entries ohne Match in bundled-features exports:`,
+    `\n❌ ${staleHeldBack.length} EXPECTED_HELD_BACK entry/entries ohne Match in bundled-features exports:`,
   );
-  for (const name of stale.sort()) {
+  for (const name of staleHeldBack.sort()) {
     console.error(`   - ${name}`);
   }
   console.error(
-    "\n  Action: aus schema/generate.ts FEATURE_IMPORT_REGISTRY entfernen, ggf. App-eigenes Feature.",
+    "\n  Action: aus EXPECTED_HELD_BACK in dieser Datei entfernen (Feature wurde umbenannt/entfernt).",
   );
   ok = false;
 }
 
-if (staleHeldBack.length > 0) {
+if (mountedHeldBack.length > 0) {
   console.error(
-    `\n❌ ${staleHeldBack.length} EXPECTED_HELD_BACK entry/entries ohne Match in bundled-features exports:`,
+    `\n❌ ${mountedHeldBack.length} EXPECTED_HELD_BACK entry/entries sind gemountet (stale):`,
   );
-  for (const name of staleHeldBack.sort()) {
+  for (const name of mountedHeldBack.sort()) {
     console.error(`   - ${name}`);
   }
-  console.error(
-    "\n  Action: aus EXPECTED_HELD_BACK in dieser Datei entfernen (Feature wurde umbenannt/entfernt).",
-  );
+  console.error("\n  Action: aus EXPECTED_HELD_BACK in dieser Datei entfernen.");
   ok = false;
 }
 
-if (ok) {
-  // Disjunkte Zahlen: `mountable` = exports ohne held-back; `coveredCount`
-  // zählt nur Registry-Einträge, die ein echter mountbarer Export sind
-  // (auth-email-password steht im Registry für schema-check-Konsistenz,
-  // ist aber held-back — würde sonst die Ratio >1 verfälschen).
-  const mountable = exports.size - EXPECTED_HELD_BACK.size;
-  let coveredCount = 0;
-  for (const name of registry) {
-    if (exports.has(name) && !EXPECTED_HELD_BACK.has(name)) coveredCount++;
-  }
-  console.log(
-    `✓ Coverage: ${coveredCount}/${mountable} mountable bundled-features im Registry, ${EXPECTED_HELD_BACK.size} held-back (M0.1).`,
-  );
-  process.exit(0);
-} else {
-  process.exit(1);
-}
+if (!ok) process.exit(1);
+
+const mountable = exports.size - EXPECTED_HELD_BACK.size;
+const mountedExports = [...exports].filter((name) => mounted.has(name)).length;
+console.log(
+  `✓ Coverage: ${mountedExports}/${mountable} mountable bundled-features gemountet, ${EXPECTED_HELD_BACK.size} held-back.`,
+);

package/samples/apps/use-all-bundled/src/app/notes-feature.ts

@@ -6,7 +6,7 @@
 // proving the "extend any object" promise on real, bootable screens.
 //
 // Deliberately NOT in src/run-config.ts APP_FEATURES: that set is bundled-only
-// (schema/generate.ts FEATURE_IMPORT_REGISTRY + check-coverage gate it). Like
+// (check-coverage compares it against the bundled-features exports). Like
 // appScreensFeature, this app-owned feature is mounted only in the dev server
 // (src/app/dev-app-options.ts), where runDevApp dev-pushes its table into the ephemeral
 // DB. Nothing here ships to prod / the schema pipeline.

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -442,6 +442,3 @@ export const AUTH_COMPOSE_OPTIONS = {
     tokenTtlMinutes: 60,
   },
 } as const;
-
-/** schema-check: auth-self-registration is mounted when signup is set. */
-export const HAS_SIGNUP = true;

package/samples/recipes/auth-mfa/README.md

@@ -10,7 +10,7 @@ The production wiring shape: mount `createAuthMfaFeature()` next to `createAuthE
 
 1. `createAuthMfaFeature({ setupTokenSecret, challengeTokenSecret, issuer })` builds the feature; `mfaStatusCheckerFromFeature(mfaFeature)` reads its login-status callback back off.
 2. That callback goes into `createAuthEmailPasswordFeature({ mfaStatusChecker: ... })` — `login.write.ts` calls it after the password check to decide whether to mint a JWT or a challenge.
-3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify } })` mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
+3. `buildServer({ auth: { mfaVerifyHandler: AuthMfaHandlers.verify, switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate } })` (the gate is required with `mfaVerifyHandler`, so a tenant switch asks for the second factor too) mounts `POST /auth/mfa/verify`, a framework route (not a dispatcher write-handler) with its own rate limiter, since it runs before a JWT exists.
 4. If `sessions` is mounted too, `bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(sessionCallbacks.sessionRevokeAllOthers)` wires "enable/disable/regenerate signs out every other session."
 
 ## What to copy into your app
@@ -43,6 +43,7 @@ const server = buildServer({
     membershipQuery: "tenant:query:memberships",
     loginHandler: "auth-email-password:[REDACTED:API key param]",
     mfaVerifyHandler: AuthMfaHandlers.verify,
+    switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
     sessionCreator: sessionCallbacks.sessionCreator,
     sessionRevoker: sessionCallbacks.sessionRevoker,
     sessionChecker: sessionCallbacks.sessionChecker,

package/samples/recipes/auth-mfa/src/feature.ts

@@ -37,6 +37,7 @@
 //       membershipQuery: "tenant:query:memberships",
 //       loginHandler: "auth-email-password:[REDACTED:API key param]",
 //       mfaVerifyHandler: AuthMfaHandlers.verify,
+//       switchTenantMfaGateHandler: AuthHandlers.switchTenantMfaGate,
 //       sessionCreator: sessionCallbacks.sessionCreator,
 //       sessionRevoker: sessionCallbacks.sessionRevoker,
 //       sessionChecker: sessionCallbacks.sessionChecker,

package/samples/recipes/custom-handlers/README.md

@@ -22,9 +22,10 @@ logic is yours.
 - **`skipOptimisticLock` for last-writer-wins** — `reset` deliberately
   bypasses the version check because the operation is admin-driven and
   resetting twice is semantically the same as resetting once.
-- **Custom queries** — `counter:active` filters the projection in
-  TypeScript after the executor's list returns. Useful when the filter is
-  computed (above-threshold) rather than indexed.
+- **Custom queries** — `counter:active` passes a server-side `filter`
+  (`eq`/`ne`/`lt`/`gt`/`lte`/`gte`/`in`) and `totalCount` to the executor's
+  list. Never filter a page in TypeScript: list is paginated, so rows after
+  the first page would be missed.
 - **`failNotFound` helper** — typed error response for the 404 case
   without a hand-built `KumikoError` subclass.
 

package/samples/recipes/custom-handlers/src/feature.ts

@@ -1,5 +1,5 @@
 // Custom Handlers Sample
-// Shows: writeHandler with business logic, queryHandler with custom filtering,
+// Shows: writeHandler with business logic, queryHandler with a server-side filter,
 // handler that modifies payload before DB write.
 
 import {
@@ -12,6 +12,9 @@ import {
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
+// detail() returns an untyped row; parse the two fields the increment needs once.
+const counterVersionRowSchema = z.object({ count: z.number(), version: z.number() });
+
 export const counterEntity = createEntity({
   table: "read_sample_counters",
   fields: {
@@ -48,13 +51,14 @@ export const counterFeature = defineFeature("counters", (r) => {
         return failNotFound("counter", event.payload.id);
       }
 
-      const newCount = (current["count"] as number) + event.payload.amount;
+      const { count, version } = counterVersionRowSchema.parse(current);
+      const newCount = count + event.payload.amount;
       // Read-modify-write on counter: use the version we just read so two
       // concurrent increments don't clobber each other's changes.
       return counterExecutor.update(
         {
           id: event.payload.id,
-          version: current["version"] as number,
+          version,
           changes: { count: newCount, lastIncrementedBy: `user:${event.user.id}` },
         },
         event.user,
@@ -80,17 +84,22 @@ export const counterFeature = defineFeature("counters", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
-  // Custom query: only counters above a threshold
+  // Custom query: only counters above a threshold. list() returns one page
+  // (default 50, max 200, MAX_LIST_LIMIT), so a JS filter would miss rows after
+  // page 1; filter in the query instead. totalCount counts over the whole WHERE.
   r.queryHandler(
     "counter:active",
-    z.object({ minCount: z.number().default(1) }),
-    async (query, ctx) => {
-      const all = await counterExecutor.list({}, query.user, ctx.db);
-      return {
-        ...all,
-        rows: all.rows.filter((r) => (r["count"] as number) >= query.payload.minCount),
-      };
-    },
+    z.object({ minCount: z.number().int().default(1), cursor: z.string().optional() }),
+    async (query, ctx) =>
+      counterExecutor.list(
+        {
+          filter: { field: "count", op: "gte", value: query.payload.minCount },
+          totalCount: true,
+          cursor: query.payload.cursor,
+        },
+        query.user,
+        ctx.db,
+      ),
     {
       access: {
         openToAll: {

package/samples/recipes/dashboard-stats/README.md

@@ -0,0 +1,38 @@
+# Dashboard stats
+
+Key figures on a dashboard. This recipe ships a `ticket` entity, one query
+handler that returns the figures as a flat object, and a `dashboard` screen
+with a stat group (open, closed) and a single stat (total).
+
+The point is to show how the three pieces connect: the screen only names a
+query and the fields to read, the query does the counting.
+
+## What it shows
+
+- **Panels reference a query by qualified name**: each `stat` carries
+  `query: "tickets:query:ticket:stats"`. The dashboard calls that handler and
+  renders the result.
+- **`valueField` picks a field from a flat result**: the handler returns
+  `{ open, closed, total }`, and each stat names one of those keys.
+- **`stat-group` and `stat`**: a group shows several stats side by side under
+  one title, a top-level `stat` stands alone.
+- **Counting happens in the database**: the handler calls the executor's
+  `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
+  over the whole WHERE clause, so no rows are loaded just to be counted.
+- **Labels are translation keys**: declared with `r.translations`.
+
+## When to reach for it
+
+You want a landing screen with a few numbers: open items, overdue invoices,
+this month's revenue. Write one query per screen that returns every figure,
+and let the stats pick their field.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). The integration test
+checks that every stat reads a field the query returns, and that the query
+counts open and closed tickets correctly.
+
+```bash
+bun kumiko test integration samples/dashboard-stats
+```

package/samples/recipes/dashboard-stats/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-dashboard-stats",
+  "description": "Key figures on a dashboard: stat panels backed by one counting query.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/dashboard-stats/src/feature.ts

@@ -0,0 +1,104 @@
+// Dashboard Stats Sample
+// Shows: a dashboard screen with a stat-group and a single stat, backed by one
+// query handler that counts in the database.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const TICKET_STATUSES = ["open", "closed"] as const;
+
+export const ticketEntity = createEntity({
+  table: "read_sample_tickets",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createSelectField({ options: TICKET_STATUSES, default: "open", required: true }),
+  },
+});
+
+export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+
+const readerRoles = { roles: ["Admin", "User"] } as const;
+
+export const ticketFeature = defineFeature("tickets", (r) => {
+  const { executor: ticketExecutor } = createEntityExecutor("ticket", ticketEntity);
+
+  r.crud("ticket", ticketEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: readerRoles },
+  });
+
+  // Flat result: each dashboard stat reads one field via its valueField.
+  // limit: 1 keeps the page tiny; totalCount counts over the whole WHERE in
+  // the database, so no rows are loaded just to be counted.
+  r.queryHandler(
+    "ticket:stats",
+    z.object({}),
+    async (query, ctx) => {
+      const countWithStatus = async (status: (typeof TICKET_STATUSES)[number]): Promise<number> => {
+        const page = await ticketExecutor.list(
+          { filter: { field: "status", op: "eq", value: status }, limit: 1, totalCount: true },
+          query.user,
+          ctx.db,
+        );
+        return page.total ?? 0;
+      };
+      const [open, closed] = await Promise.all([
+        countWithStatus("open"),
+        countWithStatus("closed"),
+      ]);
+      return { open, closed, total: open + closed };
+    },
+    { access: readerRoles },
+  );
+
+  r.translations({
+    keys: {
+      "tickets.dashboard.group": { en: "Tickets by status" },
+      "tickets.dashboard.open": { en: "Open" },
+      "tickets.dashboard.closed": { en: "Closed" },
+      "tickets.dashboard.total": { en: "All tickets" },
+    },
+  });
+
+  r.screen({
+    id: "ticket-dashboard",
+    type: "dashboard",
+    panels: [
+      {
+        kind: "stat-group",
+        id: "by-status",
+        label: "tickets.dashboard.group",
+        stats: [
+          {
+            kind: "stat",
+            id: "open",
+            label: "tickets.dashboard.open",
+            query: TICKET_STATS_QUERY,
+            valueField: "open",
+          },
+          {
+            kind: "stat",
+            id: "closed",
+            label: "tickets.dashboard.closed",
+            query: TICKET_STATS_QUERY,
+            valueField: "closed",
+          },
+        ],
+      },
+      {
+        kind: "stat",
+        id: "total",
+        label: "tickets.dashboard.total",
+        query: TICKET_STATS_QUERY,
+        valueField: "total",
+      },
+    ],
+    access: readerRoles,
+  });
+});