@cosmicdrift/kumiko-bundled-features 0.176.2 → 0.178.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.176.2",
+  "version": "0.178.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -120,12 +120,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.176.2",
-    "@cosmicdrift/kumiko-framework": "0.176.2",
-    "@cosmicdrift/kumiko-headless": "0.176.2",
-    "@cosmicdrift/kumiko-renderer": "0.176.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.176.2",
-    "@cosmicdrift/kumiko-types": "0.176.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.178.0",
+    "@cosmicdrift/kumiko-framework": "0.178.0",
+    "@cosmicdrift/kumiko-headless": "0.178.0",
+    "@cosmicdrift/kumiko-renderer": "0.178.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.178.0",
+    "@cosmicdrift/kumiko-types": "0.178.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/template-resolver/README.md

@@ -128,13 +128,15 @@ kennt keinen draft-Status — Speichern veröffentlicht.
 
 | Handler | QN | Wer | Was |
 |---|---|---|---|
-| `TemplateResolverHandlers.set` | `template-resolver:write:set` | TenantAdmin + SystemAdmin (via `tenantIdOverride` auch auf `SYSTEM_TENANT_ID`) | Upsert eines Text-Blocks pro `(tenantId, slug, locale)` |
+| `TemplateResolverHandlers.set` | `template-resolver:write:set` | TenantAdmin + SystemAdmin (via `tenantIdOverride` auch auf `SYSTEM_TENANT_ID`) | Upsert einer Ressource pro `(tenantId, slug, kind, locale)` |
 | `TemplateResolverQueries.bySlug` | `template-resolver:query:by-slug` | anonymous + User + Admins | Ein Text-Block — der Public-Read für Landing-/Legal-Pages |
 | `TemplateResolverQueries.byTenant` | `template-resolver:query:by-tenant` | anonymous + User + Admins | Alle Text-Blöcke eines Tenants für den Content-Tree |
+| `<collection>-list` / `-item` / `-set` | `template-resolver:query:<id>-list` … | wie deklariert | Pro Content-Collection, siehe unten |
 
-Die beiden Queries sind fest auf `kind: "text-block"` verdrahtet: Mail-Templates
-und AI-Prompts liegen in derselben Tabelle und dürfen nicht über den anonymen
-Pfad rausfallen.
+Die beiden Public-Queries sind fest auf `kind: "text-block"` verdrahtet und
+nehmen **keinen** kind-Parameter. Mail-Templates und AI-Prompts liegen in
+derselben Tabelle und laufen über die Handler ihrer Collection. So kann ein
+neuer kind nicht versehentlich öffentlich lesbar werden.
 
 Seed-Helper: `seedTextBlock` / `seedLegalContentFromJson` aus
 `@cosmicdrift/kumiko-bundled-features/template-resolver/seeding`.
@@ -149,6 +151,67 @@ createKumikoApp({
 });
 ```
 
+## Content-Collections
+
+Eine Sammlung erscheint dort in der Nav, wo sie fachlich hingehört — statt alles
+in einen zentralen "Content"-Bereich zu kippen. Deklariert wird sie **beim
+Mounten**, nicht im Feature:
+
+```typescript
+createTemplateResolverFeature({
+  collections: [
+    {
+      id: "reply-snippets",
+      kind: "mail-html",
+      access: { roles: ["Agent", "TenantAdmin"] },
+      nav: { label: "mail:nav.snippets", parent: "mail:nav:root" },
+    },
+    {
+      id: "ai-prompts",
+      kind: "ai-prompt",
+      access: { roles: ["PromptEngineer"] },
+      nav: { label: "mail:nav.prompts", parent: "mail:nav:root" },
+    },
+  ],
+});
+```
+
+`access` gehört an den Mount, weil ein bundled-feature das Rollenvokabular der
+App nicht kennen kann — dasselbe Muster wie die `access`-Option von
+`tags`/`folders`/`ledger`. Ohne Angabe gilt TenantAdmin + SystemAdmin.
+
+Jede Collection bekommt **eigene Handler** — `<id>-list`, `<id>-item`,
+`<id>-set` — die je die Access-Regel ihrer Collection tragen. Deshalb setzt der
+Dispatcher die Trennung durch: wer Snippets pflegen darf, kommt an den
+AI-Prompts nicht vorbei. Ein gemeinsamer Handler mit `kind`-Parameter müsste
+die Vereinigung aller Rollen zulassen und im Body sortieren.
+
+Der Payload trägt entsprechend **keinen** `kind` — `kind`, `ownership` und
+`access` stammen aus der Deklaration. Zwei Collections dürfen denselben `kind`
+mit unterschiedlichen Regeln führen.
+
+`textBlocksClient()` bedient jede deklarierte Collection automatisch: ein
+Folder-Tree pro Collection inklusive SSE-Refresh, Editor-Ziel mit der
+`collectionId`. Die App reicht dafür nichts durch.
+
+`nav.parent` darf auf ein fremdes Feature zeigen. Der Boot-Validator lehnt
+dangling Refs ab — eine Collection unter einem nicht gemounteten Feature lässt
+den Boot scheitern statt still aus der Sidebar zu verschwinden. Die
+Sichtbarkeit des Knotens folgt `access`, sofern `nav.access` nichts anderes
+sagt.
+
+Ein "+" am Knoten braucht ein explizites `nav.createAction` (Ziel ist
+üblicherweise `treeHandle.create`); ohne das listet die Collection nur, was
+schon existiert. `nav.actions` setzt Hover-Actions auf die Zeile.
+
+Speichern **veröffentlicht sofort** — Status `active`, leeres `variableSchema`.
+Wer eine Draft-Stufe oder ein Variablen-Schema braucht, nimmt
+`upsertSystem`/`upsertTenant` + `publish`.
+
+`ownership: "user"` (jeder Enduser pflegt seine eigenen Einträge, z.B.
+Signaturen) ist im Typ vorhanden, aber noch nicht implementiert — der Mount
+wirft dann, statt still allen denselben Satz zu zeigen. Siehe #1770.
+
 ## Out-of-Scope
 
 - Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`

package/src/template-resolver/__tests__/collection-kinds.integration.test.ts

@@ -0,0 +1,281 @@
+// Collections are declared at mount, each with its own access rule, and each
+// gets its own handler trio. The point of the split is that the dispatcher
+// enforces the separation: someone who may curate reply snippets must not
+// reach the AI prompts, and neither must show up on the anonymous path that
+// serves the public legal pages.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type DbConnection, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { createAnonymousUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTemplateResolverFeature } from "../feature";
+import {
+  collectionHandlerName,
+  collectionQueryName,
+  TemplateResolverHandlers,
+  TemplateResolverQueries,
+} from "../qualified-names";
+import { seedTextBlock } from "../seeding";
+import { type TemplateResourceRow, templateResourceEntity, templateResourcesTable } from "../table";
+
+let stack: TestStack;
+let db: DbConnection;
+
+const tenantAdmin = createTestUser({ id: 2, roles: ["TenantAdmin"] });
+const plainUser = createTestUser({ id: 3 });
+// The app's own role vocabulary — the whole reason access is declared at mount.
+const agent = createTestUser({ id: 4, roles: ["Agent"] });
+const promptEngineer = createTestUser({ id: 5, roles: ["PromptEngineer"] });
+
+const SNIPPETS_LIST = collectionQueryName("reply-snippets", "list");
+const SNIPPETS_ITEM = collectionQueryName("reply-snippets", "item");
+const SNIPPETS_SET = collectionHandlerName("reply-snippets");
+const PROMPTS_LIST = collectionQueryName("ai-prompts", "list");
+const PROMPTS_SET = collectionHandlerName("ai-prompts");
+
+const feature = createTemplateResolverFeature({
+  collections: [
+    {
+      id: "reply-snippets",
+      kind: "mail-html",
+      access: { roles: ["Agent", "TenantAdmin"] },
+      nav: { label: "mail:nav.snippets" },
+    },
+    {
+      id: "ai-prompts",
+      kind: "ai-prompt",
+      access: { roles: ["PromptEngineer"] },
+      nav: { label: "mail:nav.prompts" },
+    },
+  ],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, templateResourceEntity);
+  await createEventsTable(db);
+
+  // A text-block and a snippet on the same tenant with the same slug — proves
+  // the collection selects the row rather than decorating the payload.
+  await seedTextBlock(db, {
+    tenantId: agent.tenantId,
+    slug: "welcome",
+    locale: "de",
+    title: "Willkommen (Text-Block)",
+    content: "Statischer Text.",
+  });
+  await stack.http.writeOk(
+    SNIPPETS_SET,
+    {
+      slug: "welcome",
+      locale: "de",
+      title: "Willkommen (Snippet)",
+      content: "<p>Hallo {{name}}</p>",
+      contentFormat: "html",
+    },
+    agent,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("collection access :: declared roles, not hardcoded admin", () => {
+  test("the app's own role may read its collection", async () => {
+    const result = await stack.http.queryOk<{ blocks: readonly { title: string }[] }>(
+      SNIPPETS_LIST,
+      {},
+      agent,
+    );
+    expect(result.blocks.map((b) => b.title)).toEqual(["Willkommen (Snippet)"]);
+  });
+
+  test("the app's own role may write to its collection", async () => {
+    const result = await stack.http.writeOk<{ isNew: boolean }>(
+      SNIPPETS_SET,
+      {
+        slug: "thanks",
+        locale: "de",
+        title: "Danke",
+        content: "<p>Danke für Ihre Nachricht.</p>",
+        contentFormat: "html",
+      },
+      agent,
+    );
+    expect(result.isNew).toBe(true);
+  });
+
+  test("a role that may curate snippets may NOT reach the prompts", async () => {
+    const error = await stack.http.queryErr(PROMPTS_LIST, {}, agent);
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("and may not write them either", async () => {
+    const error = await stack.http.writeErr(
+      PROMPTS_SET,
+      { slug: "triage", locale: "de", title: "Triage", content: "x", contentFormat: "plain" },
+      agent,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("the prompt role reaches the prompts", async () => {
+    const result = await stack.http.queryOk<{ blocks: readonly unknown[] }>(
+      PROMPTS_LIST,
+      {},
+      promptEngineer,
+    );
+    expect(result.blocks).toEqual([]);
+  });
+
+  test("but not the snippets — the separation cuts both ways", async () => {
+    const error = await stack.http.queryErr(SNIPPETS_LIST, {}, promptEngineer);
+    expect(error.code).toBe("access_denied");
+  });
+
+  test("a user with no declared role reaches neither", async () => {
+    expect((await stack.http.queryErr(SNIPPETS_LIST, {}, plainUser)).code).toBe("access_denied");
+    expect((await stack.http.queryErr(PROMPTS_LIST, {}, plainUser)).code).toBe("access_denied");
+  });
+
+  test("anonymous reaches neither", async () => {
+    const anon = createAnonymousUser(agent.tenantId);
+    expect((await stack.http.queryErr(SNIPPETS_LIST, {}, anon)).code).toBe("access_denied");
+    expect((await stack.http.queryErr(PROMPTS_LIST, {}, anon)).code).toBe("access_denied");
+  });
+
+  test("TenantAdmin is in the declared list for snippets, so it passes there", async () => {
+    const result = await stack.http.queryOk<{ blocks: readonly unknown[] }>(
+      SNIPPETS_LIST,
+      {},
+      tenantAdmin,
+    );
+    expect(result.blocks.length).toBeGreaterThan(0);
+  });
+
+  test("TenantAdmin is NOT in the prompt list, so being admin doesn't help", async () => {
+    // The regression this guards: reverting to a hardcoded admin rule would
+    // make this pass and quietly undo the whole point of declaring access.
+    const error = await stack.http.queryErr(PROMPTS_LIST, {}, tenantAdmin);
+    expect(error.code).toBe("access_denied");
+  });
+});
+
+describe("collection isolation :: same slug, different collection", () => {
+  test("the collection's item handler returns its own row, not the text-block", async () => {
+    const snippet = await stack.http.queryOk<{ title: string }>(
+      SNIPPETS_ITEM,
+      { slug: "welcome", locale: "de" },
+      agent,
+    );
+    expect(snippet.title).toBe("Willkommen (Snippet)");
+
+    const block = await stack.http.queryOk<{ title: string }>(
+      TemplateResolverQueries.bySlug,
+      { slug: "welcome", locale: "de" },
+      tenantAdmin,
+    );
+    expect(block.title).toBe("Willkommen (Text-Block)");
+  });
+
+  test("writing through the collection leaves the text-block untouched", async () => {
+    await stack.http.writeOk(
+      SNIPPETS_SET,
+      {
+        slug: "welcome",
+        locale: "de",
+        title: "Willkommen (Snippet, v2)",
+        content: "<p>Servus</p>",
+        contentFormat: "html",
+      },
+      agent,
+    );
+
+    const block = await stack.http.queryOk<{ title: string }>(
+      TemplateResolverQueries.bySlug,
+      { slug: "welcome", locale: "de" },
+      tenantAdmin,
+    );
+    expect(block.title).toBe("Willkommen (Text-Block)");
+  });
+
+  test("creating through a collection publishes immediately — no draft stage", async () => {
+    await stack.http.writeOk(
+      SNIPPETS_SET,
+      {
+        slug: "invoice",
+        locale: "de",
+        title: "Rechnung",
+        content: "<p>Rechnung</p>",
+        contentFormat: "html",
+      },
+      agent,
+    );
+
+    const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+      tenantId: agent.tenantId,
+      slug: "invoice",
+      kind: "mail-html",
+      locale: "de",
+    });
+    // The tree editor is the no-draft route; upsertTenant + publish is the one
+    // that stages. Pinned because the split is easy to "fix" by accident.
+    expect(row?.status).toBe("active");
+    expect(row?.variableSchema).toBe("{}");
+  });
+});
+
+describe("public handlers stay public and stay text-block", () => {
+  test("anonymous may list text-blocks", async () => {
+    const result = await stack.http.queryOk<{ blocks: readonly { slug: string }[] }>(
+      TemplateResolverQueries.byTenant,
+      {},
+      createAnonymousUser(agent.tenantId),
+    );
+    expect(result.blocks.map((b) => b.slug)).toContain("welcome");
+  });
+
+  test("a kind in the payload changes nothing — there is no such field", async () => {
+    const result = await stack.http.queryOk<{ blocks: readonly { title: string }[] }>(
+      TemplateResolverQueries.byTenant,
+      { kind: "mail-html" },
+      createAnonymousUser(agent.tenantId),
+    );
+    expect(result.blocks.map((b) => b.title)).toEqual(["Willkommen (Text-Block)"]);
+  });
+
+  test("set still authors text-blocks for the hand-wired content tree", async () => {
+    const result = await stack.http.writeOk<{ isNew: boolean }>(
+      TemplateResolverHandlers.set,
+      { slug: "imprint", locale: "de", title: "Impressum", content: "## Angaben" },
+      tenantAdmin,
+    );
+    expect(result.isNew).toBe(true);
+  });
+});
+
+describe("mount-time guard", () => {
+  test("ownership 'user' is rejected until the ownerId column exists", () => {
+    expect(() =>
+      createTemplateResolverFeature({
+        collections: [
+          {
+            id: "signatures",
+            kind: "mail-html",
+            ownership: "user",
+            access: { roles: ["Agent"] },
+            nav: { label: "mail:nav.signatures" },
+          },
+        ],
+      }),
+    ).toThrow(/#1770/);
+  });
+});

package/src/template-resolver/constants.ts

@@ -1,3 +1,7 @@
+// @runtime client
+// Plain data, no imports — the content tree in web/ needs TEXT_BLOCK_KIND to
+// pick between the public and the admin query.
+//
 // RenderKind identifiziert die Konsumenten-Klasse eines Templates.
 // Plugin-Renderer in `renderer-foundation` matchen auf kind; der
 // Resolver hier ist kind-agnostisch — er lädt nur, das Content-Format

package/src/template-resolver/feature.ts

@@ -1,6 +1,12 @@
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type ContentCollectionDefinition,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { bySlugQuery } from "./handlers/by-slug.query";
 import { byTenantQuery } from "./handlers/by-tenant.query";
+import { makeCollectionItemQuery } from "./handlers/collection-item.query";
+import { makeCollectionListQuery } from "./handlers/collection-list.query";
+import { makeCollectionSetWrite } from "./handlers/collection-set.write";
 import { findByIdQuery } from "./handlers/find-by-id.query";
 import { listQuery } from "./handlers/list.query";
 import { setWrite } from "./handlers/set.write";
@@ -17,7 +23,31 @@ import { templateResourceEntity } from "./table";
 //   - Render-Time: ctx.templateResolver.resolveTemplate(...) (siehe api.ts)
 //   - Admin-UI: write/query-handlers (upsertSystem, upsertTenant, publish, archive, findById, list)
 //   - Cross-Feature: requireTemplateResolver(ctx, callerName) — Pattern wie requireTextContent
-export function createTemplateResolverFeature() {
+export type TemplateResolverOptions = {
+  /** Content collections this app mounts. Declared here rather than inside the
+   *  feature because `access` needs the host's role vocabulary — a bundled
+   *  feature cannot know that an app calls its support staff "Agent". Same
+   *  reasoning as the `access` option on tags/folders/ledger.
+   *
+   *  Each collection gets its own list/item/set handlers named
+   *  `<id>-list` / `<id>-item` / `<id>-set`, each carrying that collection's
+   *  access rule, so the dispatcher enforces the separation instead of a
+   *  branch in a shared handler. */
+  readonly collections?: readonly ContentCollectionDefinition[];
+};
+
+export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}) {
+  const collections = opts.collections ?? [];
+  const userOwned = collections.filter((c) => c.ownership === "user");
+  if (userOwned.length > 0) {
+    // Fail loudly at mount instead of quietly serving one shared set to every
+    // user — the ownerId column doesn't exist yet (#1770).
+    throw new Error(
+      `template-resolver: ownership "user" is not implemented yet (#1770) — ` +
+        `collections ${userOwned.map((c) => `"${c.id}"`).join(", ")} would silently ` +
+        `share one tenant-wide set between all users.`,
+    );
+  }
   return defineFeature("template-resolver", (r) => {
     r.describe(
       "Stores notification and mail templates in the database with a 4-level fallback: tenant+locale \u2192 system+locale \u2192 tenant+fallback-locale \u2192 system+fallback-locale. Call `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })` at render time; manage templates via the `upsertSystem`, `upsertTenant`, `publish`, and `archive` write handlers. Tenants can override system-default templates without touching application code.",
@@ -44,6 +74,13 @@ export function createTemplateResolverFeature() {
       byTenant: r.queryHandler(byTenantQuery),
     };
 
+    for (const collection of collections) {
+      r.contentCollection(collection);
+      r.queryHandler(makeCollectionListQuery(collection));
+      r.queryHandler(makeCollectionItemQuery(collection));
+      r.writeHandler(makeCollectionSetWrite(collection));
+    }
+
     // Visual-tree actions for the text-block content tree. The handle is
     // propagated through the setup export so other features can build
     // compile-time-typed cross-feature edit targets.

package/src/template-resolver/handlers/by-slug.query.ts

@@ -9,8 +9,11 @@ import { type TemplateResourceRow, templateResourcesTable } from "../table";
 
 // Public read of a single text-block by (tenantId, slug, locale). Anonymous
 // must be listed explicitly — `openToAll` alone is auth-only (regression
-// guard). The kind is pinned to `text-block`: mail templates and AI prompts
-// live in the same table and must not be readable without a session.
+// guard). The kind is pinned to `text-block` and takes no parameter: mail
+// templates and AI prompts live in the same table and must not be readable
+// without a session. Collections of any other kind go through
+// `collection-item`, which is admin-only by its access rule rather than by a
+// branch in here.
 //
 // Tenant scope defaults to query.user.tenantId (an anonymous context resolves
 // to SYSTEM_TENANT_ID or the host-resolved tenant, depending on app setup).

package/src/template-resolver/handlers/by-tenant.query.ts

@@ -8,9 +8,11 @@ import { z } from "zod";
 import { TEXT_BLOCK_KIND } from "../constants";
 import { type TemplateResourceRow, templateResourcesTable } from "../table";
 
-// All text-blocks of one tenant — feeds the content tree sidebar. Anonymous
-// is listed explicitly so no-JWT visitors get the sidebar on public pages;
-// `kind` is pinned to text-block for the same reason as in by-slug.
+// All text-blocks of one tenant — feeds the public content tree sidebar.
+// Anonymous is listed explicitly so no-JWT visitors get the sidebar on public
+// pages; `kind` is pinned to text-block for the same reason as in by-slug and
+// takes no parameter. Trees for any other kind go through `collection-list`,
+// which is admin-only by its access rule.
 //
 // Unlike by-slug this returns summaries for every slug. The body travels along
 // because the tree marks empty blocks as stubs; full render content for a

package/src/template-resolver/handlers/collection-item.query.ts

@@ -0,0 +1,52 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type ContentCollectionDefinition,
+  crossTenantOverrideDenied,
+  defineQueryHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { type TemplateResourceRow, templateResourcesTable } from "../table";
+import { DEFAULT_COLLECTION_ACCESS, ownerFilter } from "./collection-shared";
+
+// Single entry of one collection, for the editor behind a tree node. Same
+// per-collection construction as collection-list — see there for why.
+export function makeCollectionItemQuery(collection: ContentCollectionDefinition) {
+  const isUserOwned = collection.ownership === "user";
+  return defineQueryHandler({
+    name: `${collection.id}-item`,
+    schema: z.object({
+      slug: z.string().min(1).max(80),
+      locale: z.string().min(2).max(8),
+      /** Optional cross-tenant read — SystemAdmin only. */
+      tenantIdOverride: z.string().min(1).optional(),
+    }),
+    access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    handler: async (query, ctx) => {
+      const override = query.payload.tenantIdOverride;
+      const overrideDenied = crossTenantOverrideDenied(
+        query.user,
+        override,
+        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
+      );
+      if (overrideDenied) throw overrideDenied;
+      const tenantId = override ?? query.user.tenantId;
+      const row = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+        tenantId,
+        slug: query.payload.slug,
+        kind: collection.kind,
+        locale: query.payload.locale,
+        ...ownerFilter(isUserOwned, query.user),
+      });
+
+      if (!row) return null;
+      return {
+        slug: row.slug,
+        locale: row.locale,
+        title: row.title,
+        content: row.content,
+        folder: row.folder,
+        updatedAt: row.updatedAt,
+      };
+    },
+  });
+}

package/src/template-resolver/handlers/collection-list.query.ts

@@ -0,0 +1,57 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ContentCollectionDefinition,
+  crossTenantOverrideDenied,
+  defineQueryHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { type TemplateResourceRow, templateResourcesTable } from "../table";
+import { DEFAULT_COLLECTION_ACCESS, ownerFilter } from "./collection-shared";
+
+// One list handler per declared collection: `kind`, `ownership` and `access`
+// come from the declaration, never from the payload.
+//
+// Why per collection instead of one handler taking a kind: `access` is then
+// the handler's own rule and the dispatcher enforces it. A shared handler
+// would have to admit the union of every collection's roles and sort them out
+// in its body — one bug there and a prompt engineer's collection is open to
+// everyone who may edit a signature.
+export function makeCollectionListQuery(collection: ContentCollectionDefinition) {
+  const isUserOwned = collection.ownership === "user";
+  return defineQueryHandler({
+    name: `${collection.id}-list`,
+    schema: z.object({
+      /** Optional cross-tenant read — SystemAdmin only. */
+      tenantIdOverride: z.string().min(1).optional(),
+    }),
+    access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    handler: async (query, ctx) => {
+      const override = query.payload.tenantIdOverride;
+      const overrideDenied = crossTenantOverrideDenied(
+        query.user,
+        override,
+        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
+      );
+      if (overrideDenied) throw overrideDenied;
+      const tenantId = override ?? query.user.tenantId;
+      const rows = castTenantRows<TemplateResourceRow>(
+        await selectMany(ctx.db, templateResourcesTable, {
+          tenantId,
+          kind: collection.kind,
+          ...ownerFilter(isUserOwned, query.user),
+        }),
+      );
+      return {
+        blocks: rows.map((row) => ({
+          slug: row.slug,
+          locale: row.locale,
+          title: row.title,
+          content: row.content,
+          folder: row.folder,
+          updatedAt: row.updatedAt,
+        })),
+      };
+    },
+  });
+}

package/src/template-resolver/handlers/collection-set.write.ts

@@ -0,0 +1,112 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type ContentCollectionDefinition,
+  crossTenantOverrideDenied,
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { type TemplateResourceRow, templateResourcesTable } from "../table";
+import { DEFAULT_COLLECTION_ACCESS, ownerFilter } from "./collection-shared";
+import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema } from "./shared";
+
+// Upsert inside one collection. Mirrors set.write for text-blocks, but the
+// kind comes from the declaration and the access rule is the collection's own,
+// so an app can let agents edit their snippets without letting them near the
+// AI prompts.
+//
+// Like set.write this publishes on save (status active, empty variableSchema)
+// — the draft stage lives on upsertTenant + publish.
+export function makeCollectionSetWrite(collection: ContentCollectionDefinition) {
+  const isUserOwned = collection.ownership === "user";
+  return defineWriteHandler({
+    name: `${collection.id}-set`,
+    schema: z.object({
+      slug: slugSchema,
+      locale: localeSchema,
+      title: z.string().min(1).max(200),
+      content: z.string().max(200_000).nullable(),
+      contentFormat: contentFormatSchema.default("markdown"),
+      folder: folderSchema.nullable().optional(),
+      /** Optional cross-tenant write — SystemAdmin only. */
+      tenantIdOverride: z.string().min(1).optional(),
+    }),
+    access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    handler: async (event, ctx) => {
+      const db = ctx.db;
+      const override = event.payload.tenantIdOverride;
+      const overrideDenied = crossTenantOverrideDenied(
+        event.user,
+        override,
+        "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
+      );
+      if (overrideDenied) return writeFailure(overrideDenied);
+      // @cast-boundary engine-payload — override is a zod-validated string, the
+      // user's own tenantId is already TenantId-branded.
+      const tenantId = (override ?? event.user.tenantId) as TenantId;
+      const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
+      const owner = ownerFilter(isUserOwned, event.user);
+
+      const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+        tenantId,
+        slug: event.payload.slug,
+        kind: collection.kind,
+        locale: event.payload.locale,
+        ...owner,
+      });
+
+      if (existing) {
+        const result = await executor.update(
+          {
+            id: existing.id,
+            version: existing.version,
+            // Only the editable columns — slug/kind/locale are the unique key,
+            // and rewriting scope/status/variableSchema here would reset what
+            // the template upserts put on the row.
+            changes: {
+              title: event.payload.title,
+              content: event.payload.content,
+              contentFormat: event.payload.contentFormat,
+              folder: event.payload.folder ?? null,
+            },
+          },
+          executorUser,
+          db,
+        );
+        if (!result.isSuccess) return result;
+        return {
+          isSuccess: true as const,
+          data: { slug: event.payload.slug, locale: event.payload.locale, isNew: false },
+        };
+      }
+
+      const result = await executor.create(
+        {
+          tenantId,
+          slug: event.payload.slug,
+          kind: collection.kind,
+          locale: event.payload.locale,
+          title: event.payload.title,
+          content: event.payload.content,
+          contentFormat: event.payload.contentFormat,
+          folder: event.payload.folder ?? null,
+          variableSchema: "{}",
+          linkedResources: "{}",
+          scope: tenantId === SYSTEM_TENANT_ID ? ("system" as const) : ("tenant" as const),
+          parentTemplateId: null,
+          status: "active" as const,
+          ...owner,
+        },
+        executorUser,
+        db,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { slug: event.payload.slug, locale: event.payload.locale, isNew: true },
+      };
+    },
+  });
+}

package/src/template-resolver/handlers/collection-shared.ts

@@ -0,0 +1,24 @@
+import type { AccessRule, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+// Applies when an app mounts a collection without saying who may reach it.
+// Deliberately narrow: a collection whose access nobody decided should be
+// invisible to normal users rather than open by default.
+export const DEFAULT_COLLECTION_ACCESS: AccessRule = { roles: ["TenantAdmin", "SystemAdmin"] };
+
+// `ownership: "user"` means every user keeps their own entries (signatures);
+// "tenant" means one shared set (reply snippets an admin curates).
+//
+// The user-owned column doesn't exist yet — see #1770. Until it does, a
+// user-owned collection would silently behave like a tenant-wide one, so the
+// feature factory rejects `ownership: "user"` at registration time and this
+// helper never sees it.
+export function ownerFilter(
+  isUserOwned: boolean,
+  _user: SessionUser,
+): Readonly<Record<string, unknown>> {
+  if (!isUserOwned) return {};
+  throw new Error(
+    "template-resolver: ownership 'user' needs the ownerId column (#1770) — " +
+      "createTemplateResolverFeature should have rejected this collection at mount.",
+  );
+}

package/src/template-resolver/handlers/set.write.ts

@@ -7,20 +7,33 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
-import { TEXT_BLOCK_KIND } from "../constants";
+import { TEMPLATE_KINDS, TEXT_BLOCK_KIND } from "../constants";
 import { type TemplateResourceRow, templateResourcesTable } from "../table";
 import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema } from "./shared";
 
-// Upsert of a single text-block, one operation per (tenantId, slug, locale).
-// This is the authoring path for kind=text-block: unlike upsertTenant it takes
-// a title and a folder, has no draft stage (text blocks are live when saved)
-// and it may write onto SYSTEM_TENANT_ID, which is where legal and marketing
-// copy lives. Cross-tenant writes are SystemAdmin-only.
+// Upsert of a single resource, one operation per (tenantId, slug, kind,
+// locale). This is the content-tree authoring path: unlike upsertTenant it
+// takes a title and a folder, has no draft stage (saving publishes) and it may
+// write onto SYSTEM_TENANT_ID, which is where legal and marketing copy lives.
+// Cross-tenant writes are SystemAdmin-only.
+//
+// `kind` defaults to text-block. A collection editor passes its own kind; on
+// update only title/content/contentFormat/folder move, so a mail template's
+// variableSchema and status survive being edited through the tree.
+//
+// On CREATE this path stays what it is for text-blocks: status "active",
+// empty variableSchema, no parent. A mail template created through a
+// collection tree is therefore live immediately and skips the
+// upsertTenant → publish draft stage. That is the deliberate split between
+// the two authoring routes — use upsertSystem/upsertTenant when a template
+// needs a draft or a variable schema.
 export const setWrite = defineWriteHandler({
   name: "set",
   schema: z.object({
     slug: slugSchema,
     locale: localeSchema,
+    /** Which kind to author. Defaults to text-block. */
+    kind: z.enum(TEMPLATE_KINDS).optional(),
     title: z.string().min(1).max(200),
     content: z.string().max(200_000).nullable(),
     contentFormat: contentFormatSchema.default("markdown"),
@@ -51,16 +64,17 @@ export const setWrite = defineWriteHandler({
     // and reports a version conflict although the projection row exists.
     const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
 
+    const kind = event.payload.kind ?? TEXT_BLOCK_KIND;
     const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
       tenantId,
       slug: event.payload.slug,
-      kind: TEXT_BLOCK_KIND,
+      kind,
       locale: event.payload.locale,
     });
 
     const fields = {
       slug: event.payload.slug,
-      kind: TEXT_BLOCK_KIND,
+      kind,
       locale: event.payload.locale,
       title: event.payload.title,
       content: event.payload.content,

package/src/template-resolver/qualified-names.ts

@@ -13,10 +13,23 @@ export const TemplateResolverHandlers = {
 export const TemplateResolverQueries = {
   findById: "template-resolver:query:find-by-id",
   list: "template-resolver:query:list",
+  // Public pair — anonymous-reachable, kind pinned to text-block.
   bySlug: "template-resolver:query:by-slug",
   byTenant: "template-resolver:query:by-tenant",
 } as const;
 
+// Every r.contentCollection() gets its own handler trio, so each carries that
+// collection's access rule and the dispatcher enforces it. The names are
+// derived from the collection id on both sides — server-side in
+// createTemplateResolverFeature, client-side here.
+export function collectionQueryName(collectionId: string, op: "list" | "item"): string {
+  return `${TEMPLATE_RESOLVER_FEATURE}:query:${collectionId}-${op}`;
+}
+
+export function collectionHandlerName(collectionId: string): string {
+  return `${TEMPLATE_RESOLVER_FEATURE}:write:${collectionId}-set`;
+}
+
 export const TemplateResolverErrors = {
   notFound: "template_resource_not_found",
   invalidSlug: "invalid_slug",

package/src/template-resolver/web/__tests__/client-plugin.test.tsx

@@ -70,3 +70,125 @@ describe("textBlocksClient — Provider unwrappt den Content-Container", () => {
     expect(labels).toEqual(["Imprint", "page"]);
   });
 });
+
+describe("textBlocksClient — content collections", () => {
+  const origFetch = globalThis.fetch;
+  afterEach(() => {
+    globalThis.fetch = origFetch;
+  });
+
+  const collection = (id: string, kind: string) => ({
+    id,
+    kind,
+    nav: { label: `mail:nav.${id}` },
+    navQn: `mail:nav:${id}`,
+  });
+
+  test("one provider + SSE entities per declared collection, keyed on the schema's nav QN", () => {
+    const derived = textBlocksClient().navProvidersFromCollections?.([
+      collection("templates", "mail-html"),
+      collection("prompts", "ai-prompt"),
+    ]);
+
+    expect(Object.keys(derived?.providers ?? {}).sort()).toEqual([
+      "mail:nav:prompts",
+      "mail:nav:templates",
+    ]);
+    expect(derived?.entities?.["mail:nav:templates"]).toEqual(["template-resource"]);
+  });
+
+  test("no collections declared → nothing derived", () => {
+    const derived = textBlocksClient().navProvidersFromCollections?.([]);
+    expect(Object.keys(derived?.providers ?? {})).toEqual([]);
+  });
+
+  test("a collection's provider calls that collection's handler and stamps its id on the edit target", async () => {
+    let sentType = "";
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body)) as {
+        type: string;
+        payload: Record<string, unknown>;
+      };
+      sentType = body.type;
+      return new Response(
+        JSON.stringify({
+          data: {
+            blocks: [
+              {
+                slug: "reminder",
+                locale: "de",
+                title: "Reminder",
+                content: "x",
+                folder: null,
+                updatedAt: "",
+              },
+            ],
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+
+    const derived = textBlocksClient().navProvidersFromCollections?.([
+      collection("templates", "mail-html"),
+    ]);
+    const provider = derived?.providers["mail:nav:templates"];
+    if (provider === undefined) throw new Error("provider missing");
+
+    let emitted: readonly TreeNode[] | undefined;
+    provider()((nodes) => {
+      emitted = nodes;
+    });
+    await new Promise((r) => setTimeout(r, 0));
+
+    // The collection's own handler carries its access rule — a shared one
+    // taking a kind would have to admit every collection's roles at once.
+    expect(sentType).toBe("template-resolver:query:templates-list");
+    // Without the collection id on the target, the editor would read and write
+    // through the public text-block pair instead of this collection.
+    expect(emitted?.[0]?.target?.args).toMatchObject({
+      slug: "reminder",
+      collectionId: "templates",
+    });
+  });
+
+  test("a text-block collection also uses its own handler — declared means declared", async () => {
+    let sentType = "";
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      sentType = (JSON.parse(String(init?.body)) as { type: string }).type;
+      return new Response(JSON.stringify({ data: { blocks: [] } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const derived = textBlocksClient().navProvidersFromCollections?.([
+      collection("pages", "text-block"),
+    ]);
+    derived?.providers["mail:nav:pages"]?.()(() => {});
+    await new Promise((r) => setTimeout(r, 0));
+
+    // Same kind as the public tree, but declared as a collection → it gets the
+    // access the app declared, not anonymous reach.
+    expect(sentType).toBe("template-resolver:query:pages-list");
+  });
+
+  test("the hand-wired navId path stays on the anonymous-capable query", async () => {
+    let sentType = "";
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      sentType = (JSON.parse(String(init?.body)) as { type: string }).type;
+      return new Response(JSON.stringify({ data: { blocks: [] } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    // publicstatus renders its content sidebar on public pages without a
+    // session — that path must not move onto a collection handler.
+    const navId = "publicstatus:nav:content";
+    textBlocksClient({ navId }).navProviders?.[navId]?.()(() => {});
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(sentType).toBe("template-resolver:query:by-tenant");
+  });
+});

package/src/template-resolver/web/client-plugin.tsx

@@ -25,7 +25,12 @@ import {
 } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
 import { type FormEvent, type ReactNode, useEffect, useState } from "react";
-import { TemplateResolverHandlers, TemplateResolverQueries } from "../qualified-names";
+import {
+  collectionHandlerName,
+  collectionQueryName,
+  TemplateResolverHandlers,
+  TemplateResolverQueries,
+} from "../qualified-names";
 import { defaultTranslations } from "./i18n";
 
 // Exported for the unit test — groupBlocksByFolder is a pure function.
@@ -62,20 +67,26 @@ function newFolderNode(): FolderNode {
   return { leaves: [], subFolders: new Map() };
 }
 
-function attachBlock(root: FolderNode, block: BlockSummary, tenantIdOverride?: string): void {
+function attachBlock(
+  root: FolderNode,
+  block: BlockSummary,
+  tenantIdOverride?: string,
+  collectionId?: string,
+): void {
   const leaf: TreeNode = {
     label: block.title || block.slug,
     icon: "file",
     target: {
       featureId: "template-resolver",
       action: "edit",
-      // tenantIdOverride travels with the node → the editor's by-slug read +
-      // set write target the same tenant the tree was loaded from (SystemAdmin
-      // editing SYSTEM-tenant content). Omitted → session tenant.
+      // tenantIdOverride and collectionId travel with the node → the editor
+      // reads and writes through the same tenant and the same collection the
+      // tree was loaded from. Omitted → session tenant, public text-blocks.
       args: {
         slug: block.slug,
         locale: block.locale,
         ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+        ...(collectionId !== undefined && { collectionId }),
       },
     },
     state: block.content ? "filled" : "stub",
@@ -115,10 +126,11 @@ function renderFolderNode(node: FolderNode): TreeNode[] {
 export function groupBlocksByFolder(
   blocks: readonly BlockSummary[],
   tenantIdOverride?: string,
+  collectionId?: string,
 ): readonly TreeNode[] {
   const root = newFolderNode();
   for (const block of blocks) {
-    attachBlock(root, block, tenantIdOverride);
+    attachBlock(root, block, tenantIdOverride, collectionId);
   }
   const rendered = renderFolderNode(root);
   if (rendered.length === 0) return [];
@@ -135,7 +147,14 @@ export function groupBlocksByFolder(
 // tenantIdOverride (SystemAdmin-only) lets an app point the content tree at a
 // tenant other than the session's — publicstatus seeds marketing/legal blocks
 // on SYSTEM_TENANT_ID, so its SystemAdmin must read that tenant, not their own.
-function makeTreeProvider(tenantIdOverride?: string): TreeChildrenSubscribe {
+// Without a collection id: the anonymous-capable by-tenant query, so a public
+// page keeps its content sidebar without a session. With one: that
+// collection's own list handler, which carries the collection's access rule.
+function makeTreeProvider(tenantIdOverride?: string, collectionId?: string): TreeChildrenSubscribe {
+  const queryType =
+    collectionId === undefined
+      ? TemplateResolverQueries.byTenant
+      : collectionQueryName(collectionId, "list");
   return () => (emit, emitError) => {
     // CSRF header is mandatory on authenticated requests (auth-middleware
     // double-submit pattern). Anonymous/pre-login has no token → header
@@ -147,7 +166,7 @@ function makeTreeProvider(tenantIdOverride?: string): TreeChildrenSubscribe {
       method: "POST",
       headers,
       body: JSON.stringify({
-        type: TemplateResolverQueries.byTenant,
+        type: queryType,
         payload: tenantIdOverride !== undefined ? { tenantIdOverride } : {},
       }),
     })
@@ -162,7 +181,7 @@ function makeTreeProvider(tenantIdOverride?: string): TreeChildrenSubscribe {
       .then((data: ByTenantResponse) => {
         // The app-side r.nav node IS the "Content" container → the provider's
         // children are the folders/leaves below it, not the wrapper.
-        const content = groupBlocksByFolder(data.data.blocks, tenantIdOverride)[0];
+        const content = groupBlocksByFolder(data.data.blocks, tenantIdOverride, collectionId)[0];
         emit(content !== undefined && Array.isArray(content.children) ? content.children : []);
       })
       .catch((e) => {
@@ -208,11 +227,14 @@ function TextBlockEditor({
   // same way event payloads do. Optional chaining absorbs missing fields so a
   // hand-edited URL cannot crash the editor.
   const args = target.args as
-    | { slug?: string; locale?: string; tenantIdOverride?: string }
+    | { slug?: string; locale?: string; collectionId?: string; tenantIdOverride?: string }
     | undefined;
   const slug = args?.slug ?? "";
   const locale = args?.locale ?? "";
   const tenantIdOverride = args?.tenantIdOverride;
+  // Which collection the node came from. Absent → the public text-block pair,
+  // which is what the hand-wired content tree uses.
+  const collectionId = args?.collectionId;
 
   const { Form, Field, Input, Button, Banner } = usePrimitives();
   const dispatcher = useDispatcher();
@@ -221,12 +243,20 @@ function TextBlockEditor({
   const canWrite =
     user?.roles.includes("TenantAdmin") === true || user?.roles.includes("SystemAdmin") === true;
 
+  // Same split as the tree provider: a node without a collection reads through
+  // the public by-slug, a collection node through that collection's handlers.
+  const readQuery =
+    collectionId === undefined
+      ? TemplateResolverQueries.bySlug
+      : collectionQueryName(collectionId, "item");
+  const writeHandler =
+    collectionId === undefined ? TemplateResolverHandlers.set : collectionHandlerName(collectionId);
   const {
     data: loaded,
     loading,
     error: loadError,
   } = useQuery<TextBlock | null>(
-    TemplateResolverQueries.bySlug,
+    readQuery,
     { slug, locale, ...(tenantIdOverride !== undefined && { tenantIdOverride }) },
     { enabled: slug !== "" && locale !== "" },
   );
@@ -252,7 +282,7 @@ function TextBlockEditor({
     setSaveError(null);
     setSavedMsg(null);
     try {
-      const result = await dispatcher.write<SetResponse>(TemplateResolverHandlers.set, {
+      const result = await dispatcher.write<SetResponse>(writeHandler, {
         slug,
         locale,
         title,
@@ -346,18 +376,33 @@ function TextBlockEditor({
 // `tenantId` (SystemAdmin-only): which tenant the tree and editor serve —
 // SYSTEM_TENANT_ID for apps that seed marketing/legal there. Omit for the
 // session tenant (default, no cross-tenant access).
+//
+// Beyond that single tree, this client also serves every content collection
+// the app declares via r.contentCollection() — one provider per collection,
+// filtered to its kind. Those need no navId here; their nav QN comes from the
+// schema, so navId and kind can't drift apart.
 export function textBlocksClient(opts?: {
   readonly navId?: string;
   readonly tenantId?: string;
 }): ClientFeatureDefinition {
   const navId = opts?.navId;
+  const tenantId = opts?.tenantId;
   return {
     name: "template-resolver",
     ...(navId !== undefined && {
-      navProviders: { [navId]: makeTreeProvider(opts?.tenantId) },
+      navProviders: { [navId]: makeTreeProvider(tenantId) },
       // SSE refresh: every template-resource event re-fires the provider.
       navEntities: { [navId]: ["template-resource"] },
     }),
+    // Every r.contentCollection() in the app gets its own tree, filtered to
+    // that collection's kind. The explicit navId above stays independent of
+    // this — an app can have both a hand-wired content tree and collections.
+    navProvidersFromCollections: (collections) => ({
+      providers: Object.fromEntries(
+        collections.map((c) => [c.navQn, makeTreeProvider(tenantId, c.id)]),
+      ),
+      entities: Object.fromEntries(collections.map((c) => [c.navQn, ["template-resource"]])),
+    }),
     resolvers: {
       "template-resolver:edit": TextBlockEditor,
     },