@cosmicdrift/kumiko-samples 0.378.0 → 0.379.0

package/samples/apps/ui-walkthrough/src/features/rental/screens.ts

@@ -1,7 +1,8 @@
 import {
   createDateField,
-  createDecimalField,
   createEmbeddedListField,
+  createFilesField,
+  createNumberField,
   createSelectField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -12,6 +13,7 @@ import type {
   EntityListScreenDefinition,
   ProjectionDetailScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
+import { RECEIPT_ACCEPT } from "./entities";
 import { PAYMENT_METHODS, POSITION_KINDS, POSITION_MEASURES } from "./lease-support";
 import { RENTAL_QUERIES, RENTAL_WRITES } from "./qualified-names";
 
@@ -362,10 +364,50 @@ export const rentalDashboardScreen: DashboardScreenDefinition = {
       valueField: "rent",
       subField: "rentSub",
     },
+    {
+      kind: "text",
+      id: "profile-hint",
+      label: "rental.dashboard.profileHint.title",
+      blocks: [
+        { kind: "paragraph", text: "rental.dashboard.profileHint.text" },
+        {
+          kind: "link",
+          text: "rental.dashboard.profileHint.link",
+          screen: "management-profile",
+          roles: ["Admin"],
+        },
+      ],
+    },
   ],
   access: OPEN_ACCESS,
 };
 
+export const managementProfileScreen: ActionFormScreenDefinition = {
+  id: "management-profile",
+  type: "actionForm",
+  handler: RENTAL_WRITES.managementProfileSave,
+  load: { query: RENTAL_QUERIES.managementProfile, singleton: true },
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    anschrift: createTextField({ personal: false, reason: "is_business_data" }),
+    zahlungsziel: createNumberField({ integer: true, required: true }),
+  },
+  fieldLabels: {
+    name: "rental:entity:__action-form__:field:profileName",
+    anschrift: "rental:entity:__action-form__:field:anschrift",
+    zahlungsziel: "rental:entity:__action-form__:field:zahlungsziel",
+  },
+  layout: {
+    sections: [
+      {
+        description: "rental.managementProfile.hint",
+        fields: ["name", "anschrift", "zahlungsziel"],
+      },
+    ],
+  },
+  access: OPEN_ACCESS,
+};
+
 export const adjustRentScreen: ActionFormScreenDefinition = {
   id: "adjust-rent",
   type: "actionForm",
@@ -473,8 +515,13 @@ export const receiveInvoiceLines = createEmbeddedListField(
     vatAmount: { type: "money" },
   },
   {
+    minItems: 1,
     derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
-    totals: ["amount", "vatAmount"],
+    totals: [
+      { label: "rental.total.net", from: ["amount"] },
+      { label: "rental.total.vat", from: ["vatAmount"] },
+      { label: "rental.total.gross", from: ["amount", "vatAmount"] },
+    ],
   },
 );
 
@@ -491,29 +538,23 @@ export const receiveInvoiceScreen: ActionFormScreenDefinition = {
     }),
     lines: receiveInvoiceLines,
     netTotal: { type: "money", currency: EUR },
-    vatRate: createDecimalField({ precision: 5, scale: 2 }),
     vatTotal: { type: "money", currency: EUR },
     grossTotal: { type: "money", currency: EUR },
   },
   derive: {
     netTotal: { op: "listSum", list: "lines", cell: "amount" },
-    vatTotal: {
-      op: "listSum",
-      list: "lines",
-      cell: "vatAmount",
-      whenEmpty: { op: "percent", from: ["netTotal", "vatRate"] },
-    },
+    vatTotal: { op: "listSum", list: "lines", cell: "vatAmount" },
     grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
   },
   layout: {
     width: "full",
     sections: [
       { fields: ["supplier", "invoiceNumber"] },
-      { title: "rental.section.invoiceLines", columns: 1, fields: ["lines"] },
       {
-        title: "rental.section.invoiceTotals",
-        description: "rental.section.invoiceTotalsHint",
-        fields: ["netTotal", "vatRate", "vatTotal", "grossTotal"],
+        title: "rental.section.invoiceLines",
+        description: "rental.section.invoiceLines.description",
+        columns: 1,
+        fields: ["lines"],
       },
     ],
   },
@@ -597,3 +638,39 @@ export const leaseUnterlagenScreen: ProjectionDetailScreenDefinition = {
   },
   access: OPEN_ACCESS,
 };
+
+export const uploadReceiptsScreen: ActionFormScreenDefinition = {
+  id: "upload-standard-layout",
+  type: "actionForm",
+  description: "rental.upload.screenDescription",
+  handler: RENTAL_WRITES.receiptsUpload,
+  fields: {
+    belege: createFilesField({
+      personal: false,
+      reason: "is_business_data",
+      accept: RECEIPT_ACCEPT,
+      maxSize: "10MB",
+      maxCount: 10,
+      display: "dropzone",
+    }),
+  },
+  fieldLabels: { belege: "rental:entity:__action-form__:field:belege" },
+  layout: {
+    sections: [
+      {
+        icon: "upload",
+        title: "rental.upload.zoneTitle",
+        description: "rental.upload.description",
+        fields: ["belege"],
+      },
+    ],
+  },
+  submitLabel: "rental.upload.submit",
+  successFacts: [
+    { field: "count", label: "rental.upload.factCount" },
+    { field: "belege", label: "rental.upload.factFiles" },
+  ],
+  resetOnSuccess: true,
+  cancelTarget: false,
+  access: OPEN_ACCESS,
+};

package/samples/apps/ui-walkthrough/src/features/rental/web/index.ts

@@ -1,12 +1,10 @@
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { rentalTranslations } from "../i18n";
 import { LeaseHubHeader, LeaseHubHistory } from "./lease-hub-components";
-import { UploadStandardLayout } from "./upload-standard-layout";
 
 export const rentalClient: ClientFeatureDefinition = {
   name: "rental",
   translations: rentalTranslations,
-  components: { "upload-standard-layout": UploadStandardLayout },
   extensionSectionComponents: {
     LeaseHubHeader,
     LeaseHubHistory,

package/samples/apps/ui-walkthrough/src/features/subscription-plans/feature.ts

@@ -0,0 +1,103 @@
+import {
+  createBillingFoundationFeature,
+  type ProviderPrice,
+  type SubscriptionProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { defineFeature, i18nKey } from "@cosmicdrift/kumiko-framework/engine";
+import { toKeyFirst } from "../translations";
+import { subscriptionPlansTranslations } from "./i18n";
+
+export const PLAN_PROVIDER = "nordlicht-mock-provider";
+export const PLAN_TERMS_SLUG = "portal-terms";
+const PLAN_PATH = "/billing-plans";
+
+const PRICE_IDS = { starter: "price_portal_starter", pro: "price_portal_professional" };
+
+const PRICES: readonly ProviderPrice[] = [
+  {
+    priceId: PRICE_IDS.starter,
+    unitAmount: 1900,
+    currency: "eur",
+    interval: "month",
+    intervalCount: 1,
+    active: true,
+    metadata: {},
+  },
+  {
+    priceId: PRICE_IDS.pro,
+    unitAmount: 4900,
+    currency: "eur",
+    interval: "month",
+    intervalCount: 1,
+    active: true,
+    metadata: {},
+  },
+];
+
+// The sample talks to no payment provider: prices are fixed and checkout just returns to the plans screen.
+const mockProvider: SubscriptionProviderPlugin = {
+  verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody),
+  priceToTier: { [PRICE_IDS.starter]: "starter", [PRICE_IDS.pro]: "pro" },
+  retrievePrices: async (_ctx, priceIds) => PRICES.filter((p) => priceIds.includes(p.priceId)),
+  createCheckoutSession: async (_ctx, options) => ({ url: options.successUrl }),
+  cancelSubscription: async () => {},
+};
+
+export function createPortalBillingFeature(baseUrl: string) {
+  return createBillingFoundationFeature({
+    baseUrl,
+    catalog: {
+      plans: ["starter", "pro"],
+      tierLabelKey: (tier) => `subscription-plans:plan.${tier}.label`,
+      benefits: (tier) => [
+        { labelKey: `subscription-plans:plan.${tier}.benefit.units` },
+        { labelKey: `subscription-plans:plan.${tier}.benefit.support` },
+      ],
+      resolveCurrentTier: async () => "free",
+      viewRoles: ["TenantAdmin", "SystemAdmin"],
+      successPath: PLAN_PATH,
+      cancelPath: PLAN_PATH,
+      providerName: PLAN_PROVIDER,
+      contact: {
+        labelKey: "subscription-plans:plan.portfolio.label",
+        benefits: [{ labelKey: "subscription-plans:plan.portfolio.benefit" }],
+        actionLabelKey: "subscription-plans:plan.portfolio.action",
+        href: "mailto:vertrieb@nordlicht-immobilien.de",
+      },
+    },
+    consumerProtection: {
+      termsTextBlock: PLAN_TERMS_SLUG,
+      vatNote: { de: "Preise inkl. USt.", en: "Prices include VAT." },
+      operatorEmail: "abrechnung@nordlicht-immobilien.de",
+      legalLinks: {
+        de: {
+          terms: "https://nordlicht-immobilien.de/agb",
+          withdrawal: "https://nordlicht-immobilien.de/widerruf",
+          privacy: "https://nordlicht-immobilien.de/datenschutz",
+        },
+        en: {
+          terms: "https://nordlicht-immobilien.de/terms",
+          withdrawal: "https://nordlicht-immobilien.de/withdrawal",
+          privacy: "https://nordlicht-immobilien.de/privacy",
+        },
+      },
+    },
+  });
+}
+
+// Named after the screen it opens: "billing" already belongs to the invoice mails.
+export const subscriptionPlansFeature = defineFeature("subscription-plans", (r) => {
+  r.describe("Plan overview of the tenant admin: nav entry, plan labels and the mock provider.");
+  r.requires({ features: ["billing-foundation"] });
+  r.translations({ keys: toKeyFirst(subscriptionPlansTranslations) });
+  r.useExtension("subscriptionProvider", PLAN_PROVIDER, mockProvider);
+  r.nav({
+    id: "subscription-plans",
+    label: i18nKey("subscription-plans.nav.plans"),
+    icon: "file",
+    screen: "billing-foundation:screen:billing-plans",
+    order: 50,
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  });
+  return {};
+});

package/samples/apps/ui-walkthrough/src/features/subscription-plans/i18n.ts

@@ -0,0 +1,36 @@
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const subscriptionPlansTranslations: TranslationsByLocale = {
+  de: {
+    "subscription-plans.nav.plans": "Tarif und Abrechnung",
+    "subscription-plans:plan.free.label": "Basis",
+    "subscription-plans:plan.free.benefit.units": "Bis zu 3 Wohneinheiten",
+    "subscription-plans:plan.free.benefit.support": "Hilfe-Center",
+    "subscription-plans:plan.starter.label": "Starter",
+    "subscription-plans:plan.starter.benefit.units": "Bis zu 25 Wohneinheiten",
+    "subscription-plans:plan.starter.benefit.support": "Support per E-Mail",
+    "subscription-plans:plan.pro.label": "Professional",
+    "subscription-plans:plan.pro.benefit.units": "Bis zu 150 Wohneinheiten",
+    "subscription-plans:plan.pro.benefit.support": "Telefonischer Support",
+    "subscription-plans:plan.portfolio.label": "Portfolio",
+    "subscription-plans:plan.portfolio.benefit":
+      "Größere Bestände mit individuellen Konditionen und festem Ansprechpartner",
+    "subscription-plans:plan.portfolio.action": "Vertrieb kontaktieren",
+  },
+  en: {
+    "subscription-plans.nav.plans": "Plan and billing",
+    "subscription-plans:plan.free.label": "Basic",
+    "subscription-plans:plan.free.benefit.units": "Up to 3 residential units",
+    "subscription-plans:plan.free.benefit.support": "Help center",
+    "subscription-plans:plan.starter.label": "Starter",
+    "subscription-plans:plan.starter.benefit.units": "Up to 25 residential units",
+    "subscription-plans:plan.starter.benefit.support": "Support by email",
+    "subscription-plans:plan.pro.label": "Professional",
+    "subscription-plans:plan.pro.benefit.units": "Up to 150 residential units",
+    "subscription-plans:plan.pro.benefit.support": "Support by phone",
+    "subscription-plans:plan.portfolio.label": "Portfolio",
+    "subscription-plans:plan.portfolio.benefit":
+      "Larger portfolios with individual terms and a dedicated contact",
+    "subscription-plans:plan.portfolio.action": "Contact sales",
+  },
+};

package/samples/apps/ui-walkthrough/src/features/subscription-plans/index.ts

@@ -0,0 +1,2 @@
+export { createPortalBillingFeature, subscriptionPlansFeature } from "./feature";
+export { seedPlanTerms } from "./seed";

package/samples/apps/ui-walkthrough/src/features/subscription-plans/seed.ts

@@ -0,0 +1,21 @@
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { PLAN_TERMS_SLUG } from "./feature";
+
+const TERMS_BY_LOCALE: Readonly<Record<string, string>> = {
+  de: "Diese Bedingungen gelten für alle kostenpflichtigen Tarife des Nordlicht Mieterportals. Der Vertrag läuft monatlich und ist zum Ende des Abrechnungszeitraums kündbar.",
+  en: "These terms apply to every paid plan of the Nordlicht tenant portal. The contract renews monthly and can be terminated at the end of the billing period.",
+};
+
+export const seedPlanTerms: SeedFn = async (stack) => {
+  for (const [locale, content] of Object.entries(TERMS_BY_LOCALE)) {
+    await seedTextBlock(stack.db, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug: PLAN_TERMS_SLUG,
+      locale,
+      title: "Nutzungsbedingungen",
+      content,
+    });
+  }
+};

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

@@ -9,6 +9,7 @@ import {
   createChannelEmailFeature,
   createInMemoryTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
 import { createManagedPagesFeature } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
@@ -18,6 +19,7 @@ import {
   type TenantEditableTemplate,
   templateEditAccess,
 } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createTenantLifecycleFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
 import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
 import { localeEs } from "@cosmicdrift/kumiko-locale-es";
@@ -26,6 +28,10 @@ import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-render
 import { TENANT_ADMIN_EMAIL } from "./app/auth-constants";
 import { billingFeature } from "./features/billing";
 import { rentalFeature } from "./features/rental";
+import {
+  createPortalBillingFeature,
+  subscriptionPlansFeature,
+} from "./features/subscription-plans";
 import { taskFeature } from "./features/tasks";
 import { vehiclesFeature } from "./features/vehicles";
 
@@ -58,6 +64,11 @@ export const APP_FEATURES = [
   rentalFeature,
   vehiclesFeature,
   billingFeature,
+  createPortalBillingFeature(`http://localhost:${process.env["PORT"] ?? "4173"}`),
+  subscriptionPlansFeature,
+  // billing-foundation stores the subscription as tenant data and keeps the compliance profile.
+  createComplianceProfilesFeature(),
+  createTenantLifecycleFeature(),
   createTemplateResolverFeature({ tenantEditable: TENANT_EDITABLE_TEMPLATES }),
   // Only the branding rail of the layout editor needs managed-pages; the sample
   // serves no public pages, so no host resolves to a tenant.

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -72,7 +72,7 @@ await runDevApp({
   },
   extraContext: (deps) => ({
     ...createDeliveryTestContext(deps),
-    templateResolver: createTemplateResolverApi(deps.db),
+    templateResolver: createTemplateResolverApi(deps.db, deps.registry),
   }),
   extraRoutes: [
     ...createE2eSeedRoutes({ mailOutbox: galleryMailTransport }),

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

@@ -21,7 +21,7 @@
     },
     {
       "name": "admin-shell",
-      "description": "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
+      "description": "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
       "toggleableDefault": null,
       "requires": [
         "user",
@@ -69,7 +69,7 @@
     },
     {
       "name": "audit",
-      "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
+      "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       "toggleableDefault": null,
       "requires": [
         "tenant",
@@ -2209,7 +2209,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. 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.",
+      "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 502, 503 and network errors with exponential backoff (default 3 retries); 4xx, other 5xx and client timeouts fail at once, because the render has already run. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation"
@@ -2602,7 +2602,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`. 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\nEditing 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. Reading and delivery do not depend on it: a tenant override that exists is served. A collection mounted without `access` is SystemAdmin only.\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. `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.\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\nEditing 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.\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. `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.\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": [],

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

@@ -28,7 +28,7 @@ const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
 const EXPECTED_HELD_BACK = new Set([
   "foundation-shared", // utilities (requireDefined/requireNonEmpty), kein feature
   "page-render", // shared HTML render/cache helpers (legal/managed-pages), kein defineFeature
-  "presets", // deprecated feature-bundle helpers (dsgvoSelfServiceFeatures, securityBaselineFeatures), kein defineFeature
+  "presets", // deprecated feature-bundle helpers (securityBaselineFeatures), kein defineFeature
 ]);
 
 // Sub-paths in bundled-features's package.json exports (./tenant/seeding,

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -34,7 +34,9 @@ export const devAppOptions = {
   htmlPath: "./public/index.html",
   watchDirs: ["./src", "../../../packages/*/src"],
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
-  extraContext: ({ db }) => ({ templateResolver: createTemplateResolverApi(db) }),
+  extraContext: ({ db, registry }) => ({
+    templateResolver: createTemplateResolverApi(db, registry),
+  }),
   seeds: [seedScreenshotData],
   auth: {
     admin: {

package/samples/recipes/compose-stacks/README.md

@@ -18,8 +18,7 @@ the option.
   `securityBaselineFeatures()`.
 - **`composeGdprStack({ tenantLifecycle, selfService })`**: `data-retention`
   and `compliance-profiles`, optionally `tenant-lifecycle`. `selfService` adds
-  `sessions`, `user-data-rights` and `user-profile` (needs `mail`) and
-  replaces `dsgvoSelfServiceFeatures()`.
+  `sessions`, `user-data-rights` and `user-profile` (needs `mail`).
 - **`composeSaasStack({ billing, tiers, caps, waitlist })`**:
   `billing-foundation` and `tier-engine`, plus `cap-counter`/`cap-overview`
   and `waitlist` when configured. `billing: "stripe"` leaves

package/samples/recipes/embedded/README.md

@@ -21,11 +21,11 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
 
 - **Derived head totals** (`src/screens/invoice-receive.screen.ts`): an
   `actionForm` declares `derive` so net, VAT, and gross follow the lines
-  (`listSum`), or follow a typed net and VAT rate while the list is empty
-  (`whenEmpty`, `percent`). The renderer shows them read-only and live; the
-  handler wraps its schema with `withFormDerivations(schema, screen)`
-  (`src/handlers/invoice-receive.write.ts`), so totals sent by the client are
-  replaced on the server.
+  (`listSum`); the list requires at least one line (`minItems: 1`), so there
+  is no lineless input to cover. The head totals are not laid out; the lines footer shows Net, VAT, and Gross through labelled `totals`
+  entries (`{ label, from }`). The handler wraps its schema with
+  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
+  so totals sent by the client are replaced on the server.
 
 ## When to reach for it
 

package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts

@@ -16,7 +16,6 @@ const receiveInput = withFormDerivations(
     invoiceNumber: z.string().min(1),
     lines: fieldToZod(invoiceReceiveLines, ["EUR"]),
     netTotal: moneyPayload,
-    vatRate: z.number().optional(),
     vatTotal: moneyPayload,
     grossTotal: moneyPayload,
   }),

package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts

@@ -1,6 +1,5 @@
 import {
   type ActionFormScreenDefinition,
-  createDecimalField,
   createEmbeddedListField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -15,13 +14,18 @@ export const invoiceReceiveLines = createEmbeddedListField(
     vatAmount: { type: "money" },
   },
   {
+    minItems: 1,
     derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
-    totals: ["amount", "vatAmount"],
+    totals: [
+      { label: "invoice.total.net", from: ["amount"] },
+      { label: "invoice.total.vat", from: ["vatAmount"] },
+      { label: "invoice.total.gross", from: ["amount", "vatAmount"] },
+    ],
   },
 );
 
-// Net/VAT/gross are derived: with line items they are the sum of the lines,
-// without lines the net amount and the VAT rate are typed and VAT/gross follow.
+// Net/VAT/gross are derived on the server from the lines (at least one is required)
+// and shown only in the list footer, so the head totals are declared but not laid out.
 export const invoiceReceiveScreen: ActionFormScreenDefinition = {
   id: "invoice-receive",
   type: "actionForm",
@@ -35,25 +39,18 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
     }),
     lines: invoiceReceiveLines,
     netTotal: { type: "money", currency: euro },
-    vatRate: createDecimalField({ precision: 5, scale: 2 }),
     vatTotal: { type: "money", currency: euro },
     grossTotal: { type: "money", currency: euro },
   },
   derive: {
     netTotal: { op: "listSum", list: "lines", cell: "amount" },
-    vatTotal: {
-      op: "listSum",
-      list: "lines",
-      cell: "vatAmount",
-      whenEmpty: { op: "percent", from: ["netTotal", "vatRate"] },
-    },
+    vatTotal: { op: "listSum", list: "lines", cell: "vatAmount" },
     grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
   },
   layout: {
     sections: [
       { columns: 2, fields: ["supplier", "invoiceNumber"] },
       { columns: 1, fields: ["lines"] },
-      { columns: 2, fields: ["netTotal", "vatRate", "vatTotal", "grossTotal"] },
     ],
   },
 };

package/samples/recipes/legal-pages/README.md

@@ -73,7 +73,7 @@ await runProdApp({
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
   // Required (2): boot check + internal lookup use ctx.templateResolver
   extraContext: ({ db }) => ({
-    templateResolver: createTemplateResolverApi(db),
+    templateResolver: createTemplateResolverApi(db, registry),
   }),
 });
 ```
@@ -207,7 +207,7 @@ from SYSTEM_TENANT:
 | Symptom | Cause | Fix |
 |---|---|---|
 | Route returns `503 legal page unavailable` | `anonymousAccess` not configured in `runProdApp` | Set `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` |
-| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db }) => ({ templateResolver: createTemplateResolverApi(db) })` |
+| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db, registry }) => ({ templateResolver: createTemplateResolverApi(db, registry) })` |
 | Route returns `404 not configured` | Required block doesn't exist or has `content=null` | `seedTextBlock` with a content string |
 | Multi-tenant app: tenant subdomain shows an empty page | (Bug regression?) Routes should ALWAYS show SYSTEM_TENANT texts | The `legal-pages.integration.test.ts` test "SYSTEM_TENANT routing" covers this — should be green |
 | `<script>` tags in a Markdown body land 1:1 in the HTML | Deliberately accepted right now — see [legal-pages/README.md XSS section](../../../packages/bundled-features/src/legal-pages/README.md#xss--currently-not-secured-by-design) | DOMPurify is a Phase 2 once a multi-author setup arrives |

package/samples/recipes/legal-pages/src/feature.ts

@@ -27,7 +27,7 @@
 //  - `anonymousAccess` muss in runProdApp/runDevApp konfiguriert sein
 //    (defaultTenantId = SYSTEM_TENANT_ID), sonst antworten die
 //    legal-pages-Routes mit 503
-//  - `extraContext.templateResolver = createTemplateResolverApi(db)` muss
+//  - `extraContext.templateResolver = createTemplateResolverApi(db, registry)` muss
 //    gewired sein, sonst wirft der Boot-Check mit Wiring-Hinweis
 //  - Beim ersten Boot müssen die TextBlocks geseedet sein —
 //    template-resolver/seeding `seedTextBlock` oder via API

package/samples/recipes/reference-data/src/feature.ts

@@ -1,7 +1,7 @@
 // Reference Data Sample
 // Shows: r.referenceData() for static seed data with upsert logic
 
-import { table, text } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 export const categoryEntity = createEntity({
@@ -13,12 +13,8 @@ export const categoryEntity = createEntity({
   },
 });
 
-// Drizzle table for direct DB queries in tests
-export const categoryTable = table("read_sample_categories", {
-  code: text("code").notNull(),
-  name: text("name").notNull(),
-  description: text("description"),
-});
+// Read-model table for direct DB queries in tests
+export const categoryTable = buildEntityTable("category", categoryEntity);
 
 export const categoryFeature = defineFeature("catalog", (r) => {
   r.entity({ name: "category", ...categoryEntity });