@cosmicdrift/kumiko-samples 0.361.0 → 0.363.0

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

@@ -1,10 +1,10 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 82,
+  "featureCount": 84,
   "features": [
     {
       "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`) 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`, `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",
@@ -14,7 +14,8 @@
         "metrics",
         "metrics-system",
         "tier-engine",
-        "cap-overview"
+        "cap-overview",
+        "document-designer"
       ],
       "optionalRequires": [],
       "configReads": [],
@@ -406,7 +407,7 @@
     },
     {
       "name": "channel-email",
-      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.",
+      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -724,7 +725,7 @@
     },
     {
       "name": "delivery",
-      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
+      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
       "toggleableDefault": null,
       "requires": [
         "tenant"
@@ -775,6 +776,27 @@
         "recommended": false
       }
     },
+    {
+      "name": "document-designer",
+      "description": "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`.",
+      "toggleableDefault": null,
+      "requires": [
+        "template-resolver"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Documents · Template Designer",
+        "category": "content",
+        "recommended": false
+      }
+    },
     {
       "name": "document-ingest-foundation",
       "description": "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
@@ -1143,7 +1165,9 @@
       "extensionsUsed": [],
       "configKeys": [],
       "secrets": [],
-      "writeHandlers": [],
+      "writeHandlers": [
+        "files:write:bind-referenced-files"
+      ],
       "uiHints": {
         "displayLabel": "Files · Metadata",
         "category": "storage",
@@ -1798,6 +1822,30 @@
             "all"
           ]
         },
+        {
+          "key": "branding-logo-file",
+          "qualifiedName": "managed-pages:config:branding-logo-file",
+          "type": "text",
+          "scope": "tenant",
+          "default": "",
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": {
+            "regex": "^$|^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+          },
+          "writeRoles": [
+            "system",
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "all"
+          ]
+        },
         {
           "key": "branding-logo-url",
           "qualifiedName": "managed-pages:config:branding-logo-url",
@@ -2053,7 +2101,7 @@
     },
     {
       "name": "renderer-foundation",
-      "description": "Plugin registry for content rendering (notification HTML, mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block — add `renderer-simple` (or write a custom plugin via `r.useExtension(\"renderer\", name, { kinds, render })`) rather than using this feature alone.",
+      "description": "Plugin registry for content rendering (mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block — add `renderer-mail-html` (or write a custom plugin via `r.useExtension(\"renderer\", name, { kinds, render })`) rather than using this feature alone.",
       "toggleableDefault": null,
       "requires": [
         "template-resolver"
@@ -2072,6 +2120,28 @@
         "recommended": false
       }
     },
+    {
+      "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`.",
+      "toggleableDefault": null,
+      "requires": [
+        "renderer-foundation",
+        "template-resolver"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "renderer",
+          "entityName": "mail-html"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": []
+    },
     {
       "name": "renderer-pdf",
       "description": "Renderer plugin for `kind=\"document-pdf\"` that draws a table document (title, meta lines, weighted columns, repeating header, page footer) as a PDF in pure JavaScript, without a browser or Puppeteer service. `payload.variables` must be a `PdfTableDocument`. Requires `renderer-foundation`; mount a Puppeteer-based plugin instead when you need HTML/CSS layouts.",
@@ -2099,32 +2169,25 @@
       }
     },
     {
-      "name": "renderer-simple",
-      "description": "Default renderer plugin for `kind=\"notification\"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails — swap it for `renderer-mail-html` if you need MJML/Markdown layouts.",
+      "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.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation"
       ],
-      "optionalRequires": [
-        "template-resolver"
-      ],
+      "optionalRequires": [],
       "configReads": [],
       "exposesApis": [],
       "usesApis": [],
       "extensionsUsed": [
         {
           "extensionName": "renderer",
-          "entityName": "simple"
+          "entityName": "puppeteer"
         }
       ],
       "configKeys": [],
       "secrets": [],
-      "writeHandlers": [],
-      "uiHints": {
-        "displayLabel": "Renderer · Simple",
-        "category": "notifications",
-        "recommended": false
-      }
+      "writeHandlers": []
     },
     {
       "name": "secrets",
@@ -2500,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-html`, `document-pdf`, `ai-prompt`, `text-block`, `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.\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\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`.\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": [],
@@ -2508,12 +2571,46 @@
       "exposesApis": [],
       "usesApis": [],
       "extensionsUsed": [],
-      "configKeys": [],
+      "configKeys": [
+        {
+          "key": "resource-max-bytes",
+          "qualifiedName": "template-resolver:config:resource-max-bytes",
+          "type": "number",
+          "scope": "system",
+          "default": 2097152,
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": {
+            "min": 1
+          },
+          "pattern": null,
+          "writeRoles": [
+            "system"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        }
+      ],
       "secrets": [],
       "writeHandlers": [
         "template-resolver:write:archive",
+        "template-resolver:write:archive-system",
+        "template-resolver:write:copy-locale",
+        "template-resolver:write:import-bundle",
+        "template-resolver:write:import-bundle-system",
         "template-resolver:write:publish",
+        "template-resolver:write:publish-system",
         "template-resolver:write:reply-snippets-set",
+        "template-resolver:write:reset-to-system",
+        "template-resolver:write:resource-link-pdf",
+        "template-resolver:write:resource-remove",
+        "template-resolver:write:resource-upload",
+        "template-resolver:write:send-test",
         "template-resolver:write:set",
         "template-resolver:write:signatures-set",
         "template-resolver:write:upsert-system",
@@ -3008,7 +3105,7 @@
     },
     {
       "name": "user-data-rights-defaults",
-      "description": "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding. Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
+      "description": "Registers ready-made `EXT_USER_DATA` export and delete hooks for the bundled entities that hold per-user data: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`), `fileRef` (delete removes both the DB row and the storage binary), plus — gated on the source feature being mounted — `user-session` (ip/userAgent, hard-delete), `api-token` (hard-delete = revoke), `in-app-message` (hard-delete), `tenant-invitation` (invitee email forgotten/pseudonymized, inviter link severed), `notification-preference` and user-scoped `config-value` (purged via the forget verb), plus export-only hooks for the events-only aggregates `delivery-attempt` (recipientAddress) and `job-run` (payload) whose erasure runs via crypto-shredding, and `download-attempt` (rejected export-download attempts of the user: result, path, source IP, user agent, time; delete purges the user's own attempts via the forget verb, token-path rows without an owner expire by retention). Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
       "toggleableDefault": null,
       "requires": [
         "user",
@@ -3064,6 +3161,10 @@
           "extensionName": "userData",
           "entityName": "delivery-attempt"
         },
+        {
+          "extensionName": "userData",
+          "entityName": "download-attempt"
+        },
         {
           "extensionName": "userData",
           "entityName": "job-run"

package/samples/apps/use-all-bundled/kumiko/migrations/0044_download-attempt-ip-bidx.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_download_attempts"]
+}

package/samples/apps/use-all-bundled/kumiko/migrations/0045_template-resource-meta.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_template_resources"]
+}

package/samples/apps/use-all-bundled/kumiko/migrations/0046_pdf-rendered.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["rendered_pdfs"]
+}

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

@@ -18,8 +18,10 @@
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-dev-server": "workspace:*",
     "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@cosmicdrift/kumiko-document-designer": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-headless": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-puppeteer-client": "workspace:*",
     "@cosmicdrift/kumiko-renderer-web": "workspace:*",
     "@cosmicdrift/kumiko-server-runtime": "workspace:*",
     "@cosmicdrift/kumiko-types": "workspace:*",

package/samples/apps/use-all-bundled/playwright.config.ts

@@ -1,10 +1,45 @@
 // @runtime test
-import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import {
+  defineAppE2eConfig,
+  E2E_TIMEOUT_MS,
+  PLAYWRIGHT_DEMO_ENV,
+} from "@cosmicdrift/kumiko-testing/e2e";
+import { chromium } from "@playwright/test";
 import { E2E_PORTS } from "../../e2e/e2e-ports";
 
 const PORT = E2E_PORTS["framework/use-all-bundled"];
+const PRINT_SERVICE_PORT = E2E_PORTS["framework/use-all-bundled-puppeteer-service"];
+// Both sides of the print service handshake; any value of 16+ characters will do for a local run.
+const PRINT_SERVICE_TOKEN = "use-all-bundled-e2e-print-service";
 
-export default defineAppE2eConfig({
+const appConfig = defineAppE2eConfig({
   port: PORT,
-  env: PLAYWRIGHT_DEMO_ENV,
+  env: {
+    ...PLAYWRIGHT_DEMO_ENV,
+    PUPPETEER_SERVICE_URL: `http://127.0.0.1:${PRINT_SERVICE_PORT}`,
+    PUPPETEER_AUTH_TOKEN: PRINT_SERVICE_TOKEN,
+  },
 });
+
+// The PDF template editor prints through the real puppeteer-service, on the Chromium
+// that `playwright install chromium` provides instead of a Chrome download of its own.
+export default {
+  ...appConfig,
+  webServer: [
+    {
+      command: "bun run src/index.ts",
+      cwd: "../../../apps/puppeteer-service",
+      url: `http://127.0.0.1:${PRINT_SERVICE_PORT}/healthz`,
+      env: {
+        PORT: String(PRINT_SERVICE_PORT),
+        PUPPETEER_AUTH_TOKEN: PRINT_SERVICE_TOKEN,
+        PUPPETEER_EXECUTABLE_PATH: chromium.executablePath(),
+      },
+      reuseExistingServer: false,
+      timeout: E2E_TIMEOUT_MS.webServer,
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+    ...[appConfig.webServer ?? []].flat(),
+  ],
+};

package/samples/apps/use-all-bundled/schema/generate.ts

@@ -312,15 +312,25 @@ const FEATURE_IMPORT_REGISTRY: Record<string, FeatureImport> = {
     path: "@cosmicdrift/kumiko-bundled-features/template-resolver",
     factory: "createTemplateResolverFeature",
   },
+  "document-designer": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-document-designer",
+    factory: "createDocumentDesignerFeature",
+  },
   "renderer-foundation": {
     kind: "factory",
     path: "@cosmicdrift/kumiko-bundled-features/renderer-foundation",
     factory: "createRendererFoundationFeature",
   },
-  "renderer-simple": {
+  "renderer-mail-html": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-renderer-mail-html",
+    factory: "createRendererMailHtmlFeature",
+  },
+  "renderer-puppeteer-client": {
     kind: "factory",
-    path: "@cosmicdrift/kumiko-bundled-features/renderer-simple",
-    factory: "createRendererSimpleFeature",
+    path: "@cosmicdrift/kumiko-renderer-puppeteer-client",
+    factory: "createRendererPuppeteerClientFeature",
   },
   "renderer-pdf": {
     kind: "factory",

package/samples/apps/use-all-bundled/schema/schema.generated.ts

@@ -19,6 +19,7 @@ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features
 import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
 import { createWaitlistFeature } from "@cosmicdrift/kumiko-bundled-features/waitlist";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
 import { createManagedPagesFeature } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 import { customFieldsFeature } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
 import { tagsFeature } from "@cosmicdrift/kumiko-bundled-features/tags";
@@ -42,6 +43,7 @@ const _dataRetention = createDataRetentionFeature();
 const _userDataRights = createUserDataRightsFeature();
 const _waitlist = createWaitlistFeature();
 const _templateResolver = createTemplateResolverFeature();
+const _rendererPuppeteerClient = createRendererPuppeteerClientFeature();
 const _managedPages = createManagedPagesFeature({ resolveApexTenant: () => null, allowCustomCss: true });
 const _customFields = customFieldsFeature;
 const _tags = tagsFeature;
@@ -71,6 +73,7 @@ export const downloadAttemptTable = buildEntityTable("download-attempt", _userDa
 export const waitlistEntryTable = buildEntityTable("waitlistEntry", _waitlist.entities["waitlistEntry"]!);
 export const templateResourceTable = buildEntityTable("template-resource", _templateResolver.entities["template-resource"]!);
 export const userContentEntryTable = buildEntityTable("user-content-entry", _templateResolver.entities["user-content-entry"]!);
+export const renderedPdfTable = buildEntityTable("rendered-pdf", _rendererPuppeteerClient.entities["rendered-pdf"]!);
 export const pageTable = buildEntityTable("page", _managedPages.entities["page"]!);
 export const fieldDefinitionTable = buildEntityTable("field-definition", _customFields.entities["field-definition"]!);
 export const tagTable = buildEntityTable("tag", _tags.entities["tag"]!);

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

@@ -51,6 +51,9 @@ const EXPECTED_REGISTRY_ONLY = new Set([
   "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,

package/samples/apps/use-all-bundled/src/app/auth-constants.ts

@@ -14,3 +14,6 @@ export const BETA_TENANT_ID = "00000000-0000-4000-8000-000000000002";
 // Fixed id of the first seeded note, so the tags-section screenshot can navigate
 // straight to /note-edit/<id> (the other seeded notes get minted uuids).
 export const DEMO_NOTE_ID = "00000000-0000-4000-8000-00000000d001";
+
+// Seeded PDF template that the pdf-template-editor spec opens.
+export const INVOICE_TEMPLATE_SLUG = "billing:invoice";

package/samples/apps/use-all-bundled/src/app/client.tsx

@@ -33,6 +33,7 @@ import { tenantClient } from "@cosmicdrift/kumiko-bundled-features/tenant/web";
 import { tierEngineClient } from "@cosmicdrift/kumiko-bundled-features/tier-engine/web";
 import { userDataRightsClient } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
 import { userProfileClient } from "@cosmicdrift/kumiko-bundled-features/user-profile/web";
+import { documentDesignerClient } from "@cosmicdrift/kumiko-document-designer/web";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine/types";
 import { localeDeClient } from "@cosmicdrift/kumiko-locale-de/web";
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
@@ -121,6 +122,9 @@ createKumikoApp({
     // nav node. Points at SYSTEM_TENANT because that is where the legal and
     // marketing copy is seeded.
     textBlocksClient({ navId: "app-screens:nav:content", tenantId: SYSTEM_TENANT_ID }),
+    // PDF template editor with live PDF preview, mounted as the custom screen
+    // app-screens declares (no nav entry; opened by URL).
+    documentDesignerClient(),
     appScreens,
   ],
 });

package/samples/apps/use-all-bundled/src/app/seed-documents.ts

@@ -0,0 +1,128 @@
+// @runtime dev
+// Seed data for the PDF template editor: the system invoice of a small property
+// manager with its letterhead layout, plus one tenant customisation that is live
+// and one that is still a draft, so the editor's "tenant customisations" drawer
+// has both counts to show. System rows go through the template-resolver seed
+// helper, tenant rows through the real upsert-tenant write.
+
+import { TemplateResolverHandlers } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { BETA_TENANT_ID, DEV_TENANT_ID, INVOICE_TEMPLATE_SLUG } from "./auth-constants";
+
+type Stack = Parameters<SeedFn>[0];
+
+const LETTERHEAD_SLUG = "briefpapier";
+const LOCALE = "de";
+
+const LETTERHEAD_BODY = [
+  "<div data-header><p>Nordlicht Immobilien GmbH</p><p>Hafenstraße 12 · 24103 Kiel</p></div>",
+  "<div data-content></div>",
+  '<div data-footer><p>Seite <span data-variable="page"></span> von <span data-variable="pages"></span></p></div>',
+].join("");
+
+// The page break puts the payment terms on page 2 whatever the length of the
+// positions list: the print preview shows only two rows of any list.
+const invoiceBody = (paymentNote: string): string =>
+  [
+    '<h1>Rechnung <span data-variable="number"></span></h1>',
+    '<p>Rechnungsdatum: <span data-variable="invoiceDate"></span></p>',
+    '<p><span data-variable="recipientName"></span></p>',
+    '<p><span data-variable="recipientAddress"></span></p>',
+    "<p>für die folgenden Leistungen im Abrechnungszeitraum stellen wir Ihnen in Rechnung:</p>",
+    '<table><tbody><tr data-repeat-header=""><th><p>Position</p></th><th><p>Betrag</p></th></tr>',
+    '<tr data-each="items"><td><p><span data-variable="description"></span></p></td><td><p><span data-variable="amount"></span></p></td></tr></tbody></table>',
+    '<p>Gesamtbetrag: <span data-variable="total"></span></p>',
+    '<div data-page-break=""></div>',
+    "<h2>Zahlungsbedingungen</h2>",
+    `<p>${paymentNote}</p>`,
+    "<p>Bankverbindung: Förde Sparkasse, IBAN DE89 3704 0044 0532 0130 00.</p>",
+  ].join("");
+
+const INVOICE_VARIABLES = {
+  number: { type: "text", label: "Rechnungsnummer", required: true, example: "2026-0142" },
+  invoiceDate: { type: "date", label: "Rechnungsdatum", example: "2026-10-01" },
+  recipientName: { type: "text", label: "Empfänger", example: "Mareike Jansen" },
+  recipientAddress: { type: "text", label: "Anschrift", example: "Kehdenstraße 14, 24103 Kiel" },
+  items: {
+    type: "list",
+    label: "Positionen",
+    item: {
+      description: { type: "text", label: "Beschreibung" },
+      amount: { type: "money", label: "Betrag" },
+    },
+    // Money examples are minor units (cents), like stored amounts.
+    example: [
+      { description: "Kaltmiete Oktober 2026, Wohnung 3. OG links", amount: 78000 },
+      { description: "Nebenkostenvorauszahlung Oktober 2026", amount: 18500 },
+    ],
+  },
+  total: { type: "money", label: "Gesamtbetrag", example: 96500 },
+} as const;
+
+const INVOICE_META = {
+  layoutSlug: LETTERHEAD_SLUG,
+  pageFormat: "A4",
+  margins: { top: 35, bottom: 25 },
+  fileName: "Rechnung-{{number}}.pdf",
+  metadata: { title: "Rechnung {{number}}" },
+} as const;
+
+export async function seedPdfDocuments(stack: Stack, adminUserId: string): Promise<void> {
+  await seedSystemTemplate(stack.db, {
+    slug: LETTERHEAD_SLUG,
+    kind: "pdf-layout",
+    locale: LOCALE,
+    content: LETTERHEAD_BODY,
+    contentFormat: "html",
+    meta: {},
+  });
+  const system = await seedSystemTemplate(stack.db, {
+    slug: INVOICE_TEMPLATE_SLUG,
+    kind: "document-pdf",
+    locale: LOCALE,
+    content: invoiceBody("Bitte überweisen Sie den Betrag innerhalb von 14 Tagen."),
+    contentFormat: "html",
+    meta: INVOICE_META,
+    variableSchema: INVOICE_VARIABLES,
+  });
+
+  const admin: SessionUser = {
+    ...TestUsers.systemAdmin,
+    tenantId: DEV_TENANT_ID as TenantId,
+    id: adminUserId,
+  };
+  const overrides = [
+    {
+      tenantId: DEV_TENANT_ID,
+      status: "active",
+      paymentNote:
+        "Bitte überweisen Sie den Betrag innerhalb von 7 Tagen unter Angabe der Rechnungsnummer.",
+    },
+    {
+      tenantId: BETA_TENANT_ID,
+      status: "draft",
+      paymentNote: "Der Betrag wird zum Monatsersten von Ihrem Konto eingezogen.",
+    },
+  ] as const;
+  for (const override of overrides) {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        slug: INVOICE_TEMPLATE_SLUG,
+        kind: "document-pdf",
+        locale: LOCALE,
+        content: invoiceBody(override.paymentNote),
+        contentFormat: "html",
+        meta: INVOICE_META,
+        variableSchema: INVOICE_VARIABLES,
+        parentTemplateId: system.id,
+        tenantIdOverride: override.tenantId,
+        status: override.status,
+      },
+      admin,
+    );
+  }
+}

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

@@ -37,6 +37,7 @@ import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { ADMIN_EMAIL, BETA_TENANT_ID, DEMO_NOTE_ID, DEV_TENANT_ID } from "./auth-constants";
 import { noteEntity } from "./notes-feature";
+import { seedPdfDocuments } from "./seed-documents";
 
 // Event-store executors mirror the real handlers (createEntityExecutor pairs the
 // projection table + executor), so seeded rows are proper event streams, not
@@ -392,6 +393,9 @@ export const seedScreenshotData: SeedFn = async (stack) => {
     await stack.http.writeOk("auth-email-password:write:invite-create", invitee, inviter);
   }
 
+  // PDF template editor — system invoice + letterhead, one live and one draft tenant override.
+  await seedPdfDocuments(stack, devAdminId);
+
   // reply-snippets — entries for the rich collection. Written through the
   // collection's own set-handler, the same path the editor uses, so the rows
   // carry whatever the handler derives instead of a hand-built projection.