@cosmicdrift/kumiko-framework 0.374.0 → 0.378.0

package/AGENTS.md

@@ -10,7 +10,7 @@ not exist in your version:
 | File | What it holds |
 | --- | --- |
 | `agents/features.md` | Every bundled feature: name, purpose, config keys, dependencies |
-| `agents/widgets.md` | Every value export of `@cosmicdrift/kumiko-renderer-web` with its short description |
+| `agents/widgets.md` | Every value export of `@cosmicdrift/kumiko-renderer/web` with its short description |
 | `agents/examples.md` | Index of the worked examples, one per concept |
 | `agents/examples/<name>.md` | One tested sample app: README plus every source and test file |
 
@@ -238,7 +238,7 @@ produces code that compiles and then fails in production.
 - Never write your own JSX for a list, form, detail page or dashboard.
   Declare a screen. Use `type: "custom"` only when no screen type fits.
 - Inside a custom screen, never build your own card, table, badge, button or
-  chart. Use the widgets from `@cosmicdrift/kumiko-renderer-web`
+  chart. Use the widgets from `@cosmicdrift/kumiko-renderer/web`
   (`agents/widgets.md`) and the primitives from `usePrimitives()`.
 - Never fetch data with `useEffect` plus `fetch`. Use `useQuery`
   (`live: true` for server-sent updates) and `useMutation`.

package/agents/examples/apex-landing.md

@@ -238,7 +238,7 @@ import {
   type ApexPage,
   type ApexPricingTier,
   renderApexPage,
-} from "@cosmicdrift/kumiko-headless/apex";
+} from "@cosmicdrift/kumiko-renderer/headless/apex";
 import { HERO_SCREENSHOT } from "./constants";
 
 // --- Inputs: shapes the surrounding features hand you -----------------------

package/agents/examples/apex-surface-auth.md

@@ -42,7 +42,7 @@ import {
 import {
   RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
-import { createPublicSurface } from "@cosmicdrift/kumiko-renderer-web";
+import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
 
 // createLoginRoute, not a raw LoginScreen render — it owns the challenge-
 // swap for a second factor, so mounting auth-mfa later doesn't need this
@@ -252,7 +252,7 @@ describe("apex-surface-auth recipe", () => {
 //   2. Client (Kommentar unten + README): wie createPublicSurface + AuthShell
 //      die Screens in der Apex-Chrome mounten.
 //
-// CLIENT-WIRING (apex.tsx der App — renderer-web, hier nur als Referenz, da
+// CLIENT-WIRING (apex.tsx der App — renderer/web, hier nur als Referenz, da
 // Recipes keine Browser-Deps ziehen):
 //
 //   import {
@@ -263,7 +263,7 @@ describe("apex-surface-auth recipe", () => {
 //     RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
 //     defaultTranslations as deletionI18n,
 //   } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
-//   import { createPublicSurface } from "@cosmicdrift/kumiko-renderer-web";
+//   import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
 //
 //   // AuthShell: die Auth-Card rendert in der Marketing-Chrome statt
 //   // Fullscreen. Default (ohne Provider) bleibt der Fullscreen-Wrapper.

package/agents/examples/compose-stacks.md

@@ -44,22 +44,25 @@ the option.
 | `composeGdprStack` | `kmsMode` | `kms` or `allowPlaintextPii` |
 | `composeGdprStack({ selfService })`, `composeUserDataRightsStack` | `mail` | a mounted `channel-email` |
 | `composeSecurityStack` | `kmsMode`, `rateLimit` not `false` | `kms` or `allowPlaintextPii` |
-| `composeSaasStack({ billing: "stripe" })` | `billing` | a mounted subscription provider |
+| `composeSaasStack({ billing: "stripe" })` | `billing` (warning only) | a mounted subscription provider |
 
 A missing option fails the boot with:
 
 ```
 [runProdApp] stacks in `features` need boot options that are not set:
-  - composeSaasStack needs the boot option `billing`: set billing: { stripe: { priceToTier }, defaultTier }
+  - composeGdprStack needs the boot option `kmsMode`: set kmsMode: "required" (or { plaintextReason } for a demo)
 ```
 
+A stripe `composeSaasStack` without `billing` boots and logs the same line as a warning, so an
+app can go live before its prices exist.
+
 ## Flow
 
 1. `src/app.ts` lists the stacks and the boot options they need.
 2. The test boots with `KUMIKO_DRY_RUN_ENV=boot`, which runs the whole
    validation and stops before any DB or Redis connection: with the options
-   the boot passes, without `billing` or `kmsMode` it fails and names the
-   stacks.
+   the boot passes, without `kmsMode` it fails and names the stacks, and
+   without `billing` it warns.
 
 ## Tests
 
@@ -122,11 +125,15 @@ describe("compose stacks recipe", () => {
     expect(lines.some((line: string) => line.includes("boot validation OK"))).toBe(true);
   });
 
-  test("a missing billing option names composeSaasStack and the option", async () => {
+  test("a missing billing option only warns and names composeSaasStack", async () => {
     const { billing: _billing, ...withoutBilling } = bootOptions();
-    await expect(bootValidate(withoutBilling)).rejects.toThrow(
-      "composeSaasStack needs the boot option `billing`",
-    );
+    await bootValidate(withoutBilling);
+    const warnings = warnSpy.mock.calls.map((call: unknown[]) => String(call[0]));
+    expect(
+      warnings.some((line: string) =>
+        line.includes("composeSaasStack needs the boot option `billing`"),
+      ),
+    ).toBe(true);
   });
 
   test("a missing KMS decision names every stack that needs it", async () => {

package/agents/examples/delivery-notifications.md

@@ -16,7 +16,7 @@ Shows how a feature sends notifications to multiple channels (InApp + Email + Pu
 
 **Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
 
-**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+**Tenant override:** Only a SystemAdmin edits templates unless the app unlocks them. The app lists the mail in `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug, access: { roles: ["TenantAdmin"] } }] })`; then a tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`) and every other template is refused with 403. The next mail for that tenant uses the override; the system text stays for everyone else.
 
 **Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
 
@@ -137,7 +137,9 @@ const assignee = createTestUser({ id: 5, roles: ["Support"] });
 const features = [
   createConfigFeature(),
   createTenantFeature(),
-  createTemplateResolverFeature(),
+  createTemplateResolverFeature({
+    tenantEditable: [{ kind: "mail", slug: TICKET_ASSIGNED, access: { roles: ["TenantAdmin"] } }],
+  }),
   createRendererFoundationFeature(),
   createRendererMailHtmlFeature(),
   createDeliveryFeature(),
@@ -275,6 +277,27 @@ describe("delivery-notifications sample", () => {
     expect(email?.html).toContain("Tenant text: Printer on fire");
   });
 
+  test("a tenant admin may not override a mail the app did not list in tenantEditable", async () => {
+    const tenantAdmin = { ...admin, roles: ["TenantAdmin"] };
+
+    const error = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        slug: "support:notify:ticket-closed",
+        kind: "mail",
+        locale: "en",
+        content: "<p>Closed</p>",
+        contentFormat: "html",
+        meta: { subject: "Closed" },
+        variableSchema: {},
+      },
+      tenantAdmin,
+    );
+
+    expect(error.code).toBe("access_denied");
+    expect(error.i18nKey).toBe("templateResolver.errors.templateNotTenantEditable");
+  });
+
   test("ticket without assignee skips notification (recipient returns null)", async () => {
     emailTransport.sent.length = 0;
     pushTransport.sent.length = 0;

package/agents/examples/embedded-entity-form.md

@@ -471,7 +471,7 @@ export const prospectAcceptScreen: EntityEditScreenDefinition = {
 ```tsx
 import type { RenderEditControls } from "@cosmicdrift/kumiko-renderer";
 import { RenderEdit, useDispatcher, usePrimitives } from "@cosmicdrift/kumiko-renderer";
-import { Drawer } from "@cosmicdrift/kumiko-renderer-web";
+import { Drawer } from "@cosmicdrift/kumiko-renderer/web";
 import { type ReactNode, useMemo, useRef, useState } from "react";
 import { z } from "zod";
 import { prospectEntity } from "../entities/prospect";

package/agents/examples/embedded.md

@@ -27,6 +27,14 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
   `createEmbeddedListField`; its renderer receives `embeddedListCells`, so no
   custom screen component is required.
 
+- **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.
+
 ## When to reach for it
 
 Use an embedded field or list when the nested data is created, changed, and
@@ -397,6 +405,74 @@ describe("invoice line items with select/reference/derived/totals metadata", ()
     expect(error).toBeDefined();
   });
 });
+
+// --- actionForm derive ---
+
+describe("invoice receive form derives its totals on the server", () => {
+  type ReceiveTotals = {
+    netTotal: { amount: number; currency: string };
+    vatTotal: { amount: number; currency: string };
+    grossTotal: { amount: number; currency: string };
+  };
+  const eur = (amount: number) => ({ amount, currency: "EUR" });
+  const head = { supplier: "Papier AG", invoiceNumber: "RE-2026-0042" };
+
+  test("with lines, manipulated client totals are replaced by the line sums", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [
+          { description: "Paper", amount: 1005, vatRate: 19, vatAmount: 5 },
+          { description: "Toner", amount: 2000, vatRate: 7 },
+        ],
+        netTotal: eur(1),
+        vatTotal: eur(2),
+        grossTotal: eur(3),
+      },
+      admin,
+    );
+    expect(totals).toEqual({
+      netTotal: eur(30.05),
+      vatTotal: eur(3.31),
+      grossTotal: eur(33.36),
+    });
+  });
+
+  test("without lines, the typed net stays and VAT and gross are computed from the rate", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      { ...head, lines: [], netTotal: eur(100), vatRate: 19, vatTotal: eur(0), grossTotal: eur(0) },
+      admin,
+    );
+    expect(totals).toEqual({ netTotal: eur(100), vatTotal: eur(19), grossTotal: eur(119) });
+  });
+
+  test("a stale gross total is overwritten", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [],
+        netTotal: eur(50),
+        vatRate: 20,
+        vatTotal: eur(0),
+        grossTotal: eur(999),
+      },
+      admin,
+    );
+    expect(totals.grossTotal).toEqual(eur(60));
+  });
+
+  test("a caller without the Admin role is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:receive",
+      { ...head, lines: [], netTotal: eur(50), vatRate: 20, vatTotal: eur(0), grossTotal: eur(0) },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
 ```
 
 ### src/entities/contact.ts
@@ -529,6 +605,9 @@ export const productTable = buildEntityTable("product", productEntity);
 //             on its `lines` sub-fields (Issue #1835), plus a declarative
 //             entityEdit screen that renders the list end-to-end via
 //             EmbeddedListField, no custom-screen code required
+//   invoice-receive — actionForm whose net/VAT/gross head fields are derived
+//             from the lines (`derive`); the handler recomputes them with
+//             `withFormDerivations`, so client-sent totals are never trusted
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { contactEntity } from "./entities/contact";
@@ -536,6 +615,8 @@ import { invoiceEntity } from "./entities/invoice";
 import { productEntity } from "./entities/product";
 import { contactCreate } from "./handlers/contact-create.write";
 import { contactDetail } from "./handlers/contact-detail.query";
+import { invoiceReceive } from "./handlers/invoice-receive.write";
+import { invoiceReceiveScreen } from "./screens/invoice-receive.screen";
 
 export { contactEntity } from "./entities/contact";
 export { invoiceEntity } from "./entities/invoice";
@@ -557,6 +638,7 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
 
   r.writeHandler(contactCreate);
   r.queryHandler(contactDetail);
+  r.writeHandler(invoiceReceive);
 
   r.crud("product", productEntity, { write: adminWrite, read: openRead });
   r.crud("invoice", invoiceEntity, { write: adminWrite, read: openRead });
@@ -569,6 +651,8 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
       sections: [{ columns: 1, fields: ["customer", "lines"] }],
     },
   });
+
+  r.screen(invoiceReceiveScreen);
 });
 ```
 
@@ -646,3 +730,110 @@ export const contactDetail = defineQueryHandler({
   },
 });
 ```
+
+### src/handlers/invoice-receive.write.ts
+
+```ts
+import {
+  defineWriteHandler,
+  fieldToZod,
+  withFormDerivations,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { invoiceReceiveLines, invoiceReceiveScreen } from "../screens/invoice-receive.screen";
+
+const moneyPayload = z.object({ amount: z.number(), currency: z.string().min(1) });
+
+// The preprocess recomputes net/VAT/gross before validation: totals sent by the
+// client never reach the handler.
+const receiveInput = withFormDerivations(
+  z.object({
+    supplier: z.string().min(1),
+    invoiceNumber: z.string().min(1),
+    lines: fieldToZod(invoiceReceiveLines, ["EUR"]),
+    netTotal: moneyPayload,
+    vatRate: z.number().optional(),
+    vatTotal: moneyPayload,
+    grossTotal: moneyPayload,
+  }),
+  invoiceReceiveScreen,
+);
+
+export const invoiceReceive = defineWriteHandler({
+  name: "invoice:receive",
+  schema: receiveInput,
+  access: { roles: ["Admin"] },
+  handler: async (event) => ({
+    isSuccess: true,
+    data: {
+      netTotal: event.payload.netTotal,
+      vatTotal: event.payload.vatTotal,
+      grossTotal: event.payload.grossTotal,
+    },
+  }),
+});
+```
+
+### src/screens/invoice-receive.screen.ts
+
+```ts
+import {
+  type ActionFormScreenDefinition,
+  createDecimalField,
+  createEmbeddedListField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const euro = { kind: "literal", code: "EUR" } as const;
+
+export const invoiceReceiveLines = createEmbeddedListField(
+  {
+    description: { type: "text", required: true },
+    amount: { type: "money", required: true },
+    vatRate: { type: "decimal", scale: 2, required: true },
+    vatAmount: { type: "money" },
+  },
+  {
+    derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
+    totals: ["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.
+export const invoiceReceiveScreen: ActionFormScreenDefinition = {
+  id: "invoice-receive",
+  type: "actionForm",
+  handler: "contacts:write:invoice:receive",
+  fields: {
+    supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
+    invoiceNumber: createTextField({
+      required: true,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    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"] },
+    },
+    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/agents/examples/notes-history-basic.md

@@ -55,7 +55,7 @@ handler as above. Register `notesHistoryClient()` once (for its component +
 i18n), then mount it either way:
 
 ```tsx illustration
-import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer/web";
 import { notesHistoryClient, NotesSection, NOTES_SECTION_EXTENSION_NAME } from "@cosmicdrift/kumiko-bundled-features/notes-history/web";
 
 // once, at app boot — required even for standalone use (registers i18n):

package/agents/examples/tags-basic.md

@@ -56,7 +56,7 @@ as above. Register `tagsClient()` once (for its component + i18n), then mount it
 either way:
 
 ```tsx illustration
-import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer/web";
 import { tagsClient, TagSection, TAGS_SECTION_EXTENSION_NAME } from "@cosmicdrift/kumiko-bundled-features/tags/web";
 
 // once, at app boot — required even for standalone use (registers i18n):

package/agents/examples/user-profile.md

@@ -54,7 +54,7 @@ itself needs no client registration):
 ```tsx illustration
 import { userProfileClient } from "@cosmicdrift/kumiko-bundled-features/user-profile/web";
 import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
-import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer/web";
 
 createKumikoApp({
   clientFeatures: [emailPasswordClient(), userProfileClient()],

package/agents/examples/wizard-form.md

@@ -338,11 +338,11 @@ export const listingsFeature = defineFeature("listings", (r) => {
 // A `kind: "extension"` section only resolves through
 // clientFeatures.extensionSectionComponents (createKumikoApp → ExtensionSectionsProvider)
 // — never imported directly from feature.ts, which keeps the server file
-// free of the renderer-web graph. Without registering this export, an app
+// free of the renderer/web graph. Without registering this export, an app
 // mounting this recipe gets RenderEdit's fallback placeholder instead of
 // the real review step.
 
-import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { ListingReviewSection } from "./listing-review-section";
 
 export const listingsClient: ClientFeatureDefinition = {
@@ -355,13 +355,13 @@ export const listingsClient: ClientFeatureDefinition = {
 
 ```tsx
 import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
-import { DetailList } from "@cosmicdrift/kumiko-renderer-web";
+import { DetailList } from "@cosmicdrift/kumiko-renderer/web";
 import type { ReactNode } from "react";
 
 // Registered under the `__component` name the feature's review section
 // points at (see feature.ts) — never imported by feature.ts itself, the
 // string name is the only link so the server file stays free of the
-// renderer-web graph.
+// renderer/web graph.
 export function ListingReviewSection({ values }: ExtensionSectionProps): ReactNode {
   return (
     <DetailList

package/agents/features.md

@@ -228,7 +228,7 @@ Requires: `file-derivatives`
 
 ## document-designer
 
-Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`.
+Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`. The tenant overview and the editors are for SystemAdmin only; the `access` option adds roles (normally `templateEditAccess(tenantEditable)` of the template-resolver mount), and the server still enforces per template which of them may save.
 
 Category: content
 
@@ -644,7 +644,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. 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. 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. Reading and delivery do not depend on it: a tenant override that exists is 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`.
 
 Category: notifications
 

package/agents/widgets.md

@@ -1,8 +1,8 @@
-<!-- Generated by `bun run gen:agent-docs` from packages/renderer-web/src/index.ts. Do not edit. -->
+<!-- Generated by `bun run gen:agent-docs` from packages/renderer/src/web/index.ts. Do not edit. -->
 
 # Widgets
 
-Value exports of `@cosmicdrift/kumiko-renderer-web`.
+Value exports of `@cosmicdrift/kumiko-renderer/web`.
 
 ## Components
 
@@ -55,6 +55,7 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `NavTree` |  |
 | `NumberField` | Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die wiederholte id/name/value/onChange-Verdrahtung ab. |
 | `PageSection` |  |
+| `PdfPreview` |  |
 | `PercentField` |  |
 | `PhotoSlots` | Guided photo capture: one tile per requested shot in a two-column grid, each its own camera/gallery picker, filled tiles show the thumbnail. |
 | `PlainContentEditor` |  |
@@ -174,7 +175,7 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | --- | --- |
 | `BROWSER_LOCALE_STORAGE_KEY` |  |
 | `STATUS_TONE_TEXT` |  |
-| `cssVarTokens` | Tokens mit var-string-Werten. |
+| `cssVarTokens` | Tokens with var-string values. |
 | `defaultPrimitives` |  |
 | `defaultTokens` | Default-Tokens — identisch zu `cssVarTokens` (var-string-refs). |
 | `lightTokens` |  |

package/dist/api/index.d.ts

@@ -3,7 +3,7 @@ export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.ts";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.ts";
 export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthMiddlewareOptions, AuthSessionChecker, AuthSessionCheckResult, AuthSessionStatus, TenantExists, TenantLifecycleStatusResolver, TenantResolver, TokenVerifier, } from "./auth-middleware.ts";
-export { authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.ts";
+export { authMiddleware, CSRF_HEADER_NAME, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.ts";
 export type { AuthRoutesConfig, LoginRateLimiter, SessionChecker, SessionCreator, SessionMassRevoker, SessionMetadata, SessionRevoker, } from "./auth-routes.ts";
 export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.ts";
 export type { ClientIpHeaderSource, ClientIpResolver } from "./client-ip.ts";

package/dist/api/index.js

@@ -1,7 +1,7 @@
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.js";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
-export { authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.js";
+export { authMiddleware, CSRF_HEADER_NAME, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.js";
 export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.js";
 export { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, extractSocketAddress, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, UNKNOWN_CLIENT_IP, } from "./client-ip.js";
 export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route.js";

package/dist/api/routes.js

@@ -11,8 +11,8 @@ import { patAllows } from "./pat-scope.js";
 import { requestContext } from "./request-context.js";
 import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
 // SSE frame event names for POST /api/stream. Parallel definition lives in
-// @cosmicdrift/kumiko-headless (dispatcher-live imports that one) — framework
-// cannot depend on headless for four string literals.
+// @cosmicdrift/kumiko-renderer/headless (the live dispatcher imports that one) — framework
+// cannot depend on the renderer for four string literals.
 export const StreamFrame = {
     chunk: "chunk",
     ping: "ping",

package/dist/api/server.js

@@ -18,6 +18,7 @@ import { createRecordWriteCheck } from "../files/record-write-check.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { createNoopProvider, registerStandardMetrics, wrapRedisClient, } from "../observability/index.js";
 import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership.js";
+import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js";
 import { createDispatcher } from "../pipeline/dispatcher.js";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
 import { createEventDispatcher } from "../pipeline/event-dispatcher.js";
@@ -63,7 +64,7 @@ export function withFileProviderResolver(registry, context, cacheSync) {
         ...context,
         _fileProviderResolver: makeFileProviderResolver({
             registry,
-            _configAccessorFactory: context._configAccessorFactory,
+            _configAccessorFactory: configAccessorFactoryOf(context),
             secrets: context.secrets,
             db: context.db,
             ...(cacheSync ? { cacheSync } : {}),

package/dist/config/index.d.ts

@@ -27,6 +27,10 @@ export type AppConfig = {
     readonly features: readonly FeatureDefinition[];
     /** Features mounted only in production on top of `features`. */
     readonly prodFeatures?: readonly FeatureDefinition[];
+    /** Whether the app boots with the bundled auth features (config/user/tenant/auth-email-password)
+     *  that composeFeatures adds; the schema tooling needs their tables. Unset: derived from the
+     *  feature list. */
+    readonly includeBundled?: boolean;
     readonly client: AppClientConfig;
     readonly ports: AppPorts;
     /** Passed to validateBoot by `kumiko check` and, via the app's bin files, by the runners. */

package/dist/db/index.d.ts

@@ -35,5 +35,5 @@ export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, typ
 export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.ts";
 export { tableExists } from "./schema-inspection.ts";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.ts";
-export type { CreateTenantDbOptions, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";
+export type { CreateTenantDbOptions, OutsideTransactionContext, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
+export { castTenantRows, createSystemDbView, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";

package/dist/db/index.js

@@ -28,4 +28,4 @@ export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migrat
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/migrate-runner.js

@@ -111,8 +111,18 @@ export function splitSqlStatements(sqlText) {
             current += ch;
             continue;
         }
-        if (ch === "$" && /^\$([A-Za-z_]\w*)?\$/.test(sqlText.slice(i))) {
-            throw new Error("splitSqlStatements: unsupported dollar-quoted body — migration SQL is malformed, refusing to split");
+        if (ch === "$") {
+            const opening = /^\$([A-Za-z_]\w*)?\$/.exec(sqlText.slice(i))?.[0];
+            if (opening !== undefined) {
+                // Body is copied verbatim: `;` and quotes inside a DO/function body belong to it.
+                const closeAt = sqlText.indexOf(opening, i + opening.length);
+                if (closeAt === -1) {
+                    throw new Error(`splitSqlStatements: unterminated dollar-quoted body ${opening} — migration SQL is malformed, refusing to split`);
+                }
+                current += sqlText.slice(i, closeAt + opening.length);
+                i = closeAt + opening.length - 1;
+                continue;
+            }
         }
         if (ch === ";") {
             statements.push(current);
@@ -122,8 +132,6 @@ export function splitSqlStatements(sqlText) {
         current += ch;
     }
     if (state === "blockComment" || state === "singleQuote" || state === "doubleQuote") {
-        // Does not track dollar-quoted (`$$...$$`) bodies — none of this repo's
-        // migrations use them; add that state if one ever does.
         throw new Error(`splitSqlStatements: unterminated ${state} — migration SQL is malformed, refusing to split`);
     }
     statements.push(current);