@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/template-resolver/handlers/export-bundle.query.d.ts

@@ -0,0 +1,35 @@
+import * as z from "zod";
+export declare const exportBundleQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"export-bundle", z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        "ai-prompt": "ai-prompt";
+        "document-pdf": "document-pdf";
+        "image-snapshot": "image-snapshot";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
+    }>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
+}, z.core.$strip>, {
+    slug: string;
+    kind: "ai-prompt" | "document-pdf" | "image-snapshot" | "mail" | "mail-layout" | "pdf-layout";
+    contentFormat: string;
+    variableSchema: Readonly<Record<string, unknown>>;
+    locales: Record<string, {
+        body: string;
+        meta?: unknown;
+    }>;
+    resources: Record<string, {
+        fileName: string;
+        contentType: string;
+        base64: string;
+        purpose?: "attachment" | undefined;
+    }>;
+    pdfAttachments: Record<string, {
+        templateSlug: string;
+        fileName: string;
+    }>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/export-bundle.query.js

@@ -0,0 +1,118 @@
+import { isDeepStrictEqual } from "node:util";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { isFileAttachmentEntry, isPdfAttachmentLink, parseLinkedResourceEntries, } from "../linked-resources.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
+import { templateResourcesTable } from "../table.js";
+import { readTemplateResource } from "../template-resources.js";
+import { kindSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson, storedRecord } from "./template-gates.js";
+// The files live in the system tenant's key space; readTemplateResource only
+// serves the caller's own tenant, so anyone else would end in a misleading NotFound.
+function assertSystemFilesReadable(scope, entries, callerTenantId) {
+    // skip: tenant exports read the caller's own files.
+    if (scope === "tenant")
+        return;
+    // skip: the system tenant reads its own key space.
+    if (callerTenantId === SYSTEM_TENANT_ID)
+        return;
+    const hasFileResources = [...entries].some((entry) => !isPdfAttachmentLink(entry));
+    // skip: PDF attachment links carry no file to read.
+    if (!hasFileResources)
+        return;
+    throw new ValidationError({
+        fields: [
+            {
+                path: "scope",
+                code: "system_resources_need_system_tenant",
+                i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
+            },
+        ],
+    });
+}
+// A bundle carries one contentFormat and one variableSchema for all locales; importing it would
+// relabel the rows that differ from the first.
+function assertLocalesShareFormat(rows) {
+    const [first, ...rest] = rows;
+    // skip: a bundle without rows has nothing to compare
+    if (first === undefined)
+        return;
+    const firstSchema = storedRecord(first.variableSchema);
+    const differing = rest.find((row) => row.contentFormat !== first.contentFormat ||
+        !isDeepStrictEqual(storedRecord(row.variableSchema), firstSchema));
+    // skip: all locales agree
+    if (differing === undefined)
+        return;
+    throw new ValidationError({
+        fields: [
+            {
+                path: "slug",
+                code: TemplateResolverErrors.bundleLocalesDiffer,
+                i18nKey: "templateResolver.errors.template.bundleLocalesDiffer",
+            },
+        ],
+    });
+}
+export const exportBundleQuery = defineQueryHandler({
+    name: "export-bundle",
+    schema: z.object({
+        slug: templateSlugSchema,
+        kind: kindSchema,
+        scope: z.enum(["tenant", "system"]).default("tenant"),
+    }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description: "Exports every locale of one template (the caller's own rows, or the active system rows) together with its linked resource files as a self-contained bundle that import-bundle can read back, for example to move a template between tenants or environments.",
+    handler: async (query, ctx) => {
+        const { slug, kind, scope } = query.payload;
+        const found = await selectMany(ctx.db, templateResourcesTable, scope === "system"
+            ? { tenantId: SYSTEM_TENANT_ID, slug, kind, scope: "system", status: "active" }
+            : { tenantId: query.user.tenantId, slug, kind, scope: "tenant" });
+        const rows = found
+            .filter((row) => row.status !== "archived")
+            .sort((a, b) => a.locale.localeCompare(b.locale));
+        const first = rows[0];
+        if (!first)
+            throw new NotFoundError("template-resource", slug);
+        assertLocalesShareFormat(rows);
+        const locales = {};
+        const entryByKey = new Map();
+        for (const row of rows) {
+            const meta = parseStoredJson(row.meta);
+            locales[row.locale] = { body: row.content ?? "", ...(meta === undefined ? {} : { meta }) };
+            for (const [key, entry] of Object.entries(parseLinkedResourceEntries(row.linkedResources))) {
+                if (!entryByKey.has(key))
+                    entryByKey.set(key, entry);
+            }
+        }
+        assertSystemFilesReadable(scope, entryByKey.values(), query.user.tenantId);
+        const resources = {};
+        const pdfAttachments = {};
+        for (const [key, entry] of entryByKey) {
+            if (isPdfAttachmentLink(entry)) {
+                pdfAttachments[key] = { templateSlug: entry.templateSlug, fileName: entry.fileName };
+                continue;
+            }
+            const attachment = isFileAttachmentEntry(entry);
+            const file = await readTemplateResource({ db: ctx.db, files: ctx.files, user: query.user }, attachment ? entry.fileRefId : entry);
+            if (!file)
+                throw new NotFoundError("template-resource-file", key);
+            resources[key] = {
+                fileName: attachment ? entry.fileName : file.fileName,
+                contentType: file.contentType,
+                base64: Buffer.from(file.bytes).toString("base64"),
+                ...(attachment && { purpose: "attachment" }),
+            };
+        }
+        return {
+            slug,
+            kind,
+            contentFormat: first.contentFormat,
+            variableSchema: storedRecord(first.variableSchema),
+            locales,
+            resources,
+            pdfAttachments,
+        };
+    },
+});

package/dist/template-resolver/handlers/find-by-id.query.d.ts

@@ -12,8 +12,10 @@ export declare const findByIdQuery: import("@cosmicdrift/kumiko-types/define-han
     contentFormat: string;
     variableSchema: string | null;
     linkedResources: string | null;
+    meta: string | null;
     scope: string;
     parentTemplateId: string | null;
     status: string;
     modifiedAt: Temporal.Instant | null;
+    active: import("../template-draft.js").ActiveInfo | null;
 } | null, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/find-by-id.query.js

@@ -2,26 +2,27 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { templateResourcesTable } from "../table.js";
+import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow } from "../template-draft.js";
 // Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
 // archived Status. Tenant-Isolation: User sieht nur Templates des
 // eigenen Tenants oder SYSTEM_TENANT (system-defaults sind public-
-// readable). SystemAdmin sieht alle. Anonymous bleibt aus — Public-
+// readable); ctx.db is tenant-scoped for every role, so the check below is defense in depth. Anonymous bleibt aus — Public-
 // Read geht über resolveTemplate aus der API, nicht hier.
 export const findByIdQuery = defineQueryHandler({
     name: "find-by-id",
     schema: z.object({ id: z.string().min(1) }),
     access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
-    description: "Reads one template resource by row id with its content, variable schema, scope and draft/archived status, but only when it belongs to the caller's tenant or is a system default; use it to load a template into the admin editor.",
+    description: "Reads the version of one template resource an editor works on, by row id: the open draft if there is one (status draft), else the stored version, with content, variable schema and scope, but only when it belongs to the caller's tenant or is a served system default (a never-served system draft is visible to a SystemAdmin only); `active` is the version number and since-time the resolver serves, null when none is served. Use it to load a template into the admin editor.",
     handler: async (query, ctx) => {
-        const row = await fetchOne(ctx.db, templateResourcesTable, {
+        const stored = await fetchOne(ctx.db, templateResourcesTable, {
             id: query.payload.id,
         });
-        if (!row)
+        if (!stored || isHiddenSystemDraft(query.user, stored))
             return null;
-        const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+        const row = toWorkingRow(stored, draftViewerTenantId(query.user, stored));
         const isOwnTenant = row.tenantId === query.user.tenantId;
         const isSystemTemplate = row.scope === "system";
-        if (!isSystemAdmin && !isOwnTenant && !isSystemTemplate)
+        if (!isOwnTenant && !isSystemTemplate)
             return null;
         return {
             id: String(row.id),
@@ -34,10 +35,12 @@ export const findByIdQuery = defineQueryHandler({
             contentFormat: row.contentFormat,
             variableSchema: row.variableSchema,
             linkedResources: row.linkedResources,
+            meta: row.meta,
             scope: row.scope,
             parentTemplateId: row.parentTemplateId,
             status: row.status,
             modifiedAt: row.modifiedAt,
+            active: row.active,
         };
     },
 });

package/dist/template-resolver/handlers/import-bundle-system.write.d.ts

@@ -0,0 +1,39 @@
+import * as z from "zod";
+export declare const importBundleSystemWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"import-bundle-system", z.ZodObject<{
+    bundle: z.ZodObject<{
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            "ai-prompt": "ai-prompt";
+            "document-pdf": "document-pdf";
+            "image-snapshot": "image-snapshot";
+            mail: "mail";
+            "mail-layout": "mail-layout";
+            "pdf-layout": "pdf-layout";
+        }>;
+        contentFormat: z.ZodEnum<{
+            html: "html";
+            markdown: "markdown";
+            mjml: "mjml";
+            plain: "plain";
+        }>;
+        variableSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        locales: z.ZodRecord<z.ZodString, z.ZodObject<{
+            body: z.ZodString;
+            meta: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>>;
+        resources: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            fileName: z.ZodString;
+            contentType: z.ZodString;
+            base64: z.ZodString;
+            purpose: z.ZodOptional<z.ZodEnum<{
+                attachment: "attachment";
+            }>>;
+        }, z.core.$strict>>>;
+        pdfAttachments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            templateSlug: z.ZodString;
+            fileName: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strip>, {
+    ids: Record<string, string>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/template-resolver/handlers/import-bundle-system.write.js

@@ -0,0 +1,36 @@
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { templateBundleSchema } from "../template-bundle.js";
+import { importTemplateBundle } from "./bundle-import.js";
+export const importBundleSystemWrite = defineWriteHandler({
+    name: "import-bundle-system",
+    schema: z.object({ bundle: templateBundleSchema }),
+    access: { roles: ["SystemAdmin"] },
+    // A system template change reaches every tenant without an override.
+    agent: { risk: "high" },
+    description: "Imports a template bundle as system-default templates, active straight away and overwriting existing system rows; SystemAdmin only. Bundles with resource files need a caller in the system tenant, because the files are stored in the caller's file space.",
+    handler: (event, ctx) => {
+        const { bundle } = event.payload;
+        if (Object.keys(bundle.resources).length > 0 && event.user.tenantId !== SYSTEM_TENANT_ID) {
+            return Promise.resolve(writeFailure(new ValidationError({
+                fields: [
+                    {
+                        path: "bundle.resources",
+                        code: "system_resources_need_system_tenant",
+                        i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
+                    },
+                ],
+            })));
+        }
+        return importTemplateBundle({
+            ctx,
+            user: event.user,
+            tenantId: SYSTEM_TENANT_ID,
+            scope: "system",
+            status: "active",
+            bundle,
+            overwrite: true,
+        });
+    },
+});

package/dist/template-resolver/handlers/import-bundle.write.d.ts

@@ -0,0 +1,40 @@
+import * as z from "zod";
+export declare const importBundleWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"import-bundle", z.ZodObject<{
+    bundle: z.ZodObject<{
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            "ai-prompt": "ai-prompt";
+            "document-pdf": "document-pdf";
+            "image-snapshot": "image-snapshot";
+            mail: "mail";
+            "mail-layout": "mail-layout";
+            "pdf-layout": "pdf-layout";
+        }>;
+        contentFormat: z.ZodEnum<{
+            html: "html";
+            markdown: "markdown";
+            mjml: "mjml";
+            plain: "plain";
+        }>;
+        variableSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        locales: z.ZodRecord<z.ZodString, z.ZodObject<{
+            body: z.ZodString;
+            meta: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>>;
+        resources: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            fileName: z.ZodString;
+            contentType: z.ZodString;
+            base64: z.ZodString;
+            purpose: z.ZodOptional<z.ZodEnum<{
+                attachment: "attachment";
+            }>>;
+        }, z.core.$strict>>>;
+        pdfAttachments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            templateSlug: z.ZodString;
+            fileName: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    overwrite: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, {
+    ids: Record<string, string>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/template-resolver/handlers/import-bundle.write.js

@@ -0,0 +1,19 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { templateBundleSchema } from "../template-bundle.js";
+import { importTemplateBundle } from "./bundle-import.js";
+export const importBundleWrite = defineWriteHandler({
+    name: "import-bundle",
+    schema: z.object({ bundle: templateBundleSchema, overwrite: z.boolean().default(false) }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description: "Imports a template bundle (all locales plus resource files, as produced by export-bundle) into the caller's tenant as drafts; it refuses a locale that already has an override unless overwrite is set, and publish makes the drafts live.",
+    handler: (event, ctx) => importTemplateBundle({
+        ctx,
+        user: event.user,
+        tenantId: event.user.tenantId,
+        scope: "tenant",
+        status: "draft",
+        bundle: event.payload.bundle,
+        overwrite: event.payload.overwrite,
+    }),
+});

package/dist/template-resolver/handlers/layout-source.query.d.ts

@@ -0,0 +1,31 @@
+import * as z from "zod";
+import { type LayoutRegions } from "../layout-regions.js";
+import { type ActiveInfo } from "../template-draft.js";
+import { type MailLayoutMeta } from "../template-meta.js";
+export type LayoutSourceRow = {
+    readonly id: string;
+    readonly version: number;
+    readonly status: string;
+    readonly locale: string;
+    readonly active: ActiveInfo | null;
+};
+export type LayoutSourceResponse = {
+    readonly tenant: LayoutSourceRow | null;
+    readonly system: (LayoutSourceRow & {
+        readonly contentFormat: string;
+    }) | null;
+    readonly regions: LayoutRegions;
+    readonly effectiveFormat: "html" | "mjml" | null;
+    readonly mjmlSource: string | null;
+    /** Appearance of the effective mail layout; invalid stored meta reads as defaults (empty). */
+    readonly meta: MailLayoutMeta;
+    readonly locale: string;
+};
+export declare const layoutSourceQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"layout-source", z.ZodObject<{
+    kind: z.ZodEnum<{
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
+    }>;
+    slug: z.ZodDefault<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, LayoutSourceResponse, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/layout-source.query.js

@@ -0,0 +1,87 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { FALLBACK_LOCALE } from "../constants.js";
+import { readLayoutRegions } from "../layout-regions.js";
+import { templateResourcesTable } from "../table.js";
+import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow, } from "../template-draft.js";
+import { readMailLayoutMeta } from "../template-meta.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson } from "./template-gates.js";
+const EMPTY_REGIONS = { header: "", signature: "", footer: "" };
+function pickByLocale(rows, requested) {
+    const live = rows.filter((row) => row.status !== "archived");
+    const candidates = live.length > 0 ? live : rows;
+    return (candidates.find((row) => row.locale === requested) ??
+        candidates.find((row) => row.locale === FALLBACK_LOCALE) ??
+        candidates[0] ??
+        null);
+}
+function toSourceRow(row) {
+    return {
+        id: String(row.id),
+        version: row.version,
+        status: row.status,
+        locale: row.locale,
+        active: row.active,
+    };
+}
+function layoutFormat(row) {
+    return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
+}
+function pickEditedRows(rows, user, locale) {
+    const tenantRow = user.roles.includes("SystemAdmin")
+        ? null
+        : pickByLocale(rows.filter((row) => row.scope === "tenant"), locale);
+    const systemRow = pickByLocale(rows.filter((row) => row.scope === "system" && !isHiddenSystemDraft(user, row)), locale);
+    return {
+        tenantRow: tenantRow && toWorkingRow(tenantRow, user.tenantId),
+        // Only a SystemAdmin works on the system draft; a tenant sees the served system version.
+        systemRow: systemRow && toWorkingRow(systemRow, draftViewerTenantId(user, systemRow)),
+    };
+}
+function readEffectiveRegions(effective, effectiveFormat) {
+    return effective !== null && effectiveFormat === "html"
+        ? readLayoutRegions(effective.content ?? "")
+        : EMPTY_REGIONS;
+}
+function readMjmlSource(systemRow, isSystemAdmin) {
+    const exposesMjml = isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml";
+    return exposesMjml ? (systemRow.content ?? "") : null;
+}
+function buildLayoutSource(input) {
+    const { kind, locale, isSystemAdmin, tenantRow, systemRow } = input;
+    const effective = tenantRow ?? systemRow;
+    const effectiveFormat = effective === null ? null : layoutFormat(effective);
+    return {
+        tenant: tenantRow === null ? null : toSourceRow(tenantRow),
+        system: systemRow === null
+            ? null
+            : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
+        regions: readEffectiveRegions(effective, effectiveFormat),
+        effectiveFormat,
+        mjmlSource: readMjmlSource(systemRow, isSystemAdmin),
+        meta: kind === "mail-layout" ? readMailLayoutMeta(parseStoredJson(effective?.meta ?? null)) : {},
+        locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
+    };
+}
+export const layoutSourceQuery = defineQueryHandler({
+    name: "layout-source",
+    schema: z.object({
+        kind: z.enum(["mail-layout", "pdf-layout"]),
+        slug: templateSlugSchema.default("default"),
+        locale: localeSchema.optional(),
+    }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description: "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+    handler: async (query, ctx) => {
+        const { kind, slug, locale } = query.payload;
+        const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+        const rows = await selectMany(ctx.db, templateResourcesTable, {
+            kind,
+            slug,
+        });
+        const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
+        return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
+    },
+});

package/dist/template-resolver/handlers/list.query.d.ts

@@ -4,8 +4,11 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
         "ai-prompt": "ai-prompt";
         "document-pdf": "document-pdf";
         "image-snapshot": "image-snapshot";
-        "mail-html": "mail-html";
+        mail: "mail";
+        "mail-layout": "mail-layout";
         notification: "notification";
+        "pdf-layout": "pdf-layout";
+        snippet: "snippet";
         "text-block": "text-block";
     }>>;
     locale: z.ZodOptional<z.ZodString>;

package/dist/template-resolver/handlers/list.query.js

@@ -3,9 +3,9 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { templateResourcesTable } from "../table.js";
-// List für Admin-UI: filterbar nach kind / locale / status. Liefert
-// system-templates + tenant's eigene zusammen — Admin-UI rendert beide
-// Spalten mit scope-marker. SystemAdmin sieht alle (auch andere Tenants).
+import { isHiddenSystemDraft } from "../template-draft.js";
+// ctx.db is tenant-scoped even for SystemAdmin: every caller sees its own
+// tenant's rows plus the system defaults, never another tenant's rows.
 export const listQuery = defineQueryHandler({
     name: "list",
     schema: z.object({
@@ -18,10 +18,9 @@ export const listQuery = defineQueryHandler({
     description: "Lists template resources of the caller's tenant alongside the system defaults as summaries without content, filterable by kind, locale and status; use it to browse the catalogue, then find-by-id to read one row.",
     handler: async (query, ctx) => {
         const where = {};
-        // includeSystem=false narrows to own tenant AT THE DB — for non-SystemAdmin
-        // TenantDb permits narrowing within its enforced [own, SYSTEM] scope, for
-        // SystemAdmin (system-scoped db) the where applies verbatim. Filtering at
-        // the DB keeps the limit meaningful (no post-filter starvation).
+        // includeSystem=false narrows to own tenant AT THE DB — TenantDb permits
+        // narrowing within its enforced [own, SYSTEM] scope. Filtering at the DB
+        // keeps the limit meaningful (no post-filter starvation).
         if (!query.payload.includeSystem) {
             where["tenantId"] = query.user.tenantId;
         }
@@ -39,7 +38,9 @@ export const listQuery = defineQueryHandler({
         const rows = (await selectMany(ctx.db, templateResourcesTable, where, {
             limit: 500,
         }));
-        return rows.map((row) => ({
+        return rows
+            .filter((row) => !isHiddenSystemDraft(query.user, row))
+            .map((row) => ({
             id: String(row.id),
             tenantId: row.tenantId,
             slug: row.slug,

package/dist/template-resolver/handlers/override-diff.d.ts

@@ -0,0 +1,20 @@
+import type { TemplateResourceRow } from "../table.js";
+export declare function buildOverrideDiff(tenantRow: TemplateResourceRow, systemRow: TemplateResourceRow): {
+    tenant: {
+        templateId: string;
+        templateVersion: number;
+        contentFormat: string;
+    };
+    system: {
+        templateId: string;
+        templateVersion: number;
+        contentFormat: string;
+    };
+    identical: boolean;
+    blocks: import("../template-diff.js").TemplateDiffBlock[];
+    meta: {
+        key: string;
+        tenant: unknown;
+        system: unknown;
+    }[];
+};

package/dist/template-resolver/handlers/override-diff.js

@@ -0,0 +1,41 @@
+import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
+import { servedVersionOf } from "../template-draft.js";
+function parseStoredMeta(raw) {
+    if (raw === null)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? Object.fromEntries(Object.entries(parsed))
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function diffMeta(system, tenant) {
+    const keys = [...new Set([...Object.keys(system), ...Object.keys(tenant)])].sort();
+    return keys
+        .filter((key) => JSON.stringify(system[key]) !== JSON.stringify(tenant[key]))
+        .map((key) => ({ key, tenant: tenant[key], system: system[key] }));
+}
+// Shared by the tenant's own diff and the SystemAdmin's per-tenant diff in the overrides drawer.
+export function buildOverrideDiff(tenantRow, systemRow) {
+    const blocks = diffTemplateBlocks(splitTemplateBlocks(systemRow.content ?? "", systemRow.contentFormat), splitTemplateBlocks(tenantRow.content ?? "", tenantRow.contentFormat));
+    const meta = diffMeta(parseStoredMeta(systemRow.meta), parseStoredMeta(tenantRow.meta));
+    return {
+        tenant: {
+            templateId: String(tenantRow.id),
+            templateVersion: servedVersionOf(tenantRow),
+            contentFormat: tenantRow.contentFormat,
+        },
+        system: {
+            templateId: String(systemRow.id),
+            templateVersion: servedVersionOf(systemRow),
+            contentFormat: systemRow.contentFormat,
+        },
+        identical: meta.length === 0 && blocks.every((block) => block.change === "same"),
+        blocks,
+        meta,
+    };
+}

package/dist/template-resolver/handlers/overview.query.d.ts

@@ -0,0 +1,65 @@
+import * as z from "zod";
+import { type TemplateStatus } from "../constants.js";
+import { type TemplateResourceRow } from "../table.js";
+import { type EffectiveMailLayoutSlugs } from "../template-usage.js";
+declare const OVERVIEW_KINDS: readonly ["mail", "document-pdf", "mail-layout", "pdf-layout"];
+type OverviewKind = (typeof OVERVIEW_KINDS)[number];
+export type OverviewOrigin = "tenant" | "system";
+export type OverviewKindGroup = "mail" | "pdf" | "layout";
+export type OverviewUsage = {
+    readonly qualifiedName: string;
+    readonly feature: string;
+    readonly notification: string;
+    readonly trigger: string | null;
+};
+export type OverviewRow = {
+    readonly id: string;
+    readonly slug: string;
+    readonly kind: OverviewKind;
+    readonly kindGroup: OverviewKindGroup;
+    readonly title: string;
+    readonly origin: OverviewOrigin;
+    readonly locales: readonly string[];
+    readonly status: TemplateStatus;
+    readonly version: number;
+    readonly draftVersion: number | null;
+    readonly activeSince: string | null;
+    readonly systemVersion: number | null;
+    readonly layoutSlug: string | null;
+    readonly modifiedAt: string;
+    readonly usedBy: readonly OverviewUsage[];
+    readonly usedByCount: number;
+};
+export type OverviewResponse = {
+    readonly rows: readonly OverviewRow[];
+    readonly nextCursor: null;
+    readonly total: number;
+};
+export declare function effectiveMailLayoutSlugs(rows: readonly TemplateResourceRow[]): EffectiveMailLayoutSlugs;
+export declare const overviewQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"overview", z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodEnum<{
+            kind: "kind";
+            kindGroup: "kindGroup";
+            origin: "origin";
+            status: "status";
+        }>;
+        op: z.ZodLiteral<"in">;
+        value: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    layoutSlug: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    totalCount: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, {
+    rows: OverviewRow[];
+    nextCursor: null;
+    total: number;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};