@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/handlers/layout-source.query.ts

@@ -0,0 +1,151 @@
+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 { type LayoutRegions, readLayoutRegions } from "../layout-regions.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import {
+  type ActiveInfo,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  toWorkingRow,
+  type WorkingRow,
+} from "../template-draft.js";
+import { type MailLayoutMeta, readMailLayoutMeta } from "../template-meta.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson } from "./template-gates.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;
+};
+
+const EMPTY_REGIONS: LayoutRegions = { header: "", signature: "", footer: "" };
+
+function pickByLocale(
+  rows: readonly TemplateResourceRow[],
+  requested: string | undefined,
+): TemplateResourceRow | null {
+  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: WorkingRow): LayoutSourceRow {
+  return {
+    id: String(row.id),
+    version: row.version,
+    status: row.status,
+    locale: row.locale,
+    active: row.active,
+  };
+}
+
+function layoutFormat(row: WorkingRow): "html" | "mjml" | null {
+  return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
+}
+
+function pickEditedRows(
+  rows: readonly TemplateResourceRow[],
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  locale: string | undefined,
+): {
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
+} {
+  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: WorkingRow | null,
+  effectiveFormat: "html" | "mjml" | null,
+): LayoutRegions {
+  return effective !== null && effectiveFormat === "html"
+    ? readLayoutRegions(effective.content ?? "")
+    : EMPTY_REGIONS;
+}
+
+function readMjmlSource(systemRow: WorkingRow | null, isSystemAdmin: boolean): string | null {
+  const exposesMjml = isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml";
+  return exposesMjml ? (systemRow.content ?? "") : null;
+}
+
+function buildLayoutSource(input: {
+  readonly kind: "mail-layout" | "pdf-layout";
+  readonly locale: string | undefined;
+  readonly isSystemAdmin: boolean;
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
+}): LayoutSourceResponse {
+  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): Promise<LayoutSourceResponse> => {
+    const { kind, slug, locale } = query.payload;
+    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const rows = await selectMany<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      kind,
+      slug,
+    });
+    const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
+    return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/list.query.ts

@@ -3,10 +3,10 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { isHiddenSystemDraft } from "../template-draft.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).
+// 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({
@@ -21,10 +21,9 @@ export const listQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const where: Record<string, unknown> = {};
 
-    // 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;
     }
@@ -45,16 +44,18 @@ export const listQuery = defineQueryHandler({
       limit: 500,
     })) as TemplateResourceRow[];
 
-    return rows.map((row) => ({
-      id: String(row.id),
-      tenantId: row.tenantId,
-      slug: row.slug,
-      kind: row.kind,
-      locale: row.locale,
-      scope: row.scope,
-      status: row.status,
-      contentFormat: row.contentFormat,
-      modifiedAt: row.modifiedAt,
-    }));
+    return rows
+      .filter((row) => !isHiddenSystemDraft(query.user, row))
+      .map((row) => ({
+        id: String(row.id),
+        tenantId: row.tenantId,
+        slug: row.slug,
+        kind: row.kind,
+        locale: row.locale,
+        scope: row.scope,
+        status: row.status,
+        contentFormat: row.contentFormat,
+        modifiedAt: row.modifiedAt,
+      }));
   },
 });

package/packages/bundled-features/src/template-resolver/handlers/override-diff.ts

@@ -0,0 +1,49 @@
+import type { TemplateResourceRow } from "../table.js";
+import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
+import { servedVersionOf } from "../template-draft.js";
+
+function parseStoredMeta(raw: string | null): Readonly<Record<string, unknown>> {
+  if (raw === null) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? Object.fromEntries(Object.entries(parsed))
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function diffMeta(
+  system: Readonly<Record<string, unknown>>,
+  tenant: Readonly<Record<string, unknown>>,
+) {
+  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: TemplateResourceRow, systemRow: TemplateResourceRow) {
+  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/packages/bundled-features/src/template-resolver/handlers/overview.query.ts

@@ -0,0 +1,323 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { DEFAULT_MAIL_LAYOUT_SLUG, FALLBACK_LOCALE, type TemplateStatus } from "../constants.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import {
+  activeSinceOf,
+  activeVersionOf,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  parseTemplateDraft,
+  servedVersionOf,
+} from "../template-draft.js";
+import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.js";
+import { storedRecord } from "./template-gates.js";
+
+const OVERVIEW_KINDS = ["mail", "document-pdf", "mail-layout", "pdf-layout"] as const;
+type OverviewKind = (typeof OVERVIEW_KINDS)[number];
+
+const OVERVIEW_ROW_LIMIT = 5000;
+
+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;
+};
+
+const SORT_FIELDS = ["title", "slug", "kind", "origin", "status", "modifiedAt"] as const;
+type SortField = (typeof SORT_FIELDS)[number];
+
+const KIND_GROUP: Readonly<Record<OverviewKind, OverviewKindGroup>> = {
+  mail: "mail",
+  "document-pdf": "pdf",
+  "mail-layout": "layout",
+  "pdf-layout": "layout",
+};
+
+function isOverviewKind(kind: string): kind is OverviewKind {
+  return OVERVIEW_KINDS.some((candidate) => candidate === kind);
+}
+
+function isTemplateStatus(status: string): status is TemplateStatus {
+  return status === "draft" || status === "active" || status === "archived";
+}
+
+function layoutSlugOf(row: TemplateResourceRow): string {
+  const layoutSlug = storedRecord(row.meta)["layoutSlug"];
+  return typeof layoutSlug === "string" ? layoutSlug : DEFAULT_MAIL_LAYOUT_SLUG;
+}
+
+function preferredRow(rows: readonly TemplateResourceRow[]): TemplateResourceRow | undefined {
+  return (
+    rows.find((row) => row.locale === FALLBACK_LOCALE) ??
+    [...rows].sort((a, b) => a.locale.localeCompare(b.locale))[0]
+  );
+}
+
+type EffectiveRows = { readonly origin: OverviewOrigin; readonly rows: TemplateResourceRow[] };
+
+function effectiveRowsOf(rows: readonly TemplateResourceRow[]): EffectiveRows | null {
+  const tenantRows = rows.filter((row) => row.scope === "tenant");
+  const systemRows = rows.filter((row) => row.scope === "system");
+  const live = (list: TemplateResourceRow[]) => list.filter((row) => row.status !== "archived");
+  const liveTenant = live(tenantRows);
+  if (liveTenant.length > 0) return { origin: "tenant", rows: liveTenant };
+  if (systemRows.length > 0) {
+    const liveSystem = live(systemRows);
+    return { origin: "system", rows: liveSystem.length > 0 ? liveSystem : systemRows };
+  }
+  return tenantRows.length > 0 ? { origin: "tenant", rows: tenantRows } : null;
+}
+
+export function effectiveMailLayoutSlugs(
+  rows: readonly TemplateResourceRow[],
+): EffectiveMailLayoutSlugs {
+  const byLocale = new Map<string, TemplateResourceRow[]>();
+  for (const row of rows) {
+    if (row.kind !== "mail") continue;
+    const key = `${row.slug}\u0000${row.locale}`;
+    byLocale.set(key, [...(byLocale.get(key) ?? []), row]);
+  }
+  const bySlug = new Map<string, Map<string, string>>();
+  for (const group of byLocale.values()) {
+    const effective = effectiveRowsOf(group)?.rows[0];
+    // All-archived: the renderer falls back to the code-registered template.
+    if (effective === undefined || effective.status === "archived") continue;
+    const locales = bySlug.get(effective.slug) ?? new Map<string, string>();
+    locales.set(effective.locale, layoutSlugOf(effective));
+    bySlug.set(effective.slug, locales);
+  }
+  return bySlug;
+}
+
+function modifiedAtOf(row: TemplateResourceRow): string {
+  return (row.modifiedAt ?? row.insertedAt).toString();
+}
+
+function splitDocumentSlug(slug: string): { feature: string; notification: string } {
+  const separator = slug.indexOf(":");
+  return separator === -1
+    ? { feature: "", notification: slug }
+    : { feature: slug.slice(0, separator), notification: slug.slice(separator + 1) };
+}
+
+function compareBy(field: SortField, a: OverviewRow, b: OverviewRow): number {
+  return String(a[field]).localeCompare(String(b[field]));
+}
+
+function isSortField(value: string): value is SortField {
+  return SORT_FIELDS.some((candidate) => candidate === value);
+}
+
+type OverviewDraft = Omit<OverviewRow, "usedBy" | "usedByCount">;
+type OverviewFilter = {
+  readonly field: "kindGroup" | "kind" | "origin" | "status";
+  readonly value: readonly string[];
+};
+
+function groupBySlugAndKind(
+  rows: readonly TemplateResourceRow[],
+): Map<string, TemplateResourceRow[]> {
+  const groups = new Map<string, TemplateResourceRow[]>();
+  for (const row of rows) {
+    if (!isOverviewKind(row.kind)) continue;
+    const key = `${row.kind}|${row.slug}`;
+    groups.set(key, [...(groups.get(key) ?? []), row]);
+  }
+  return groups;
+}
+
+// Another tenant's draft, including a system draft seen by a tenant, is never announced.
+function draftVersionFor(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  row: TemplateResourceRow,
+): number | null {
+  const isOwnRow = row.tenantId === draftViewerTenantId(user, row);
+  return isOwnRow && parseTemplateDraft(row.draft) !== null ? row.version : null;
+}
+
+// Version columns of one overview row: the served version, a waiting draft and the system version it overrides.
+function versionFieldsOf(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  preferred: TemplateResourceRow,
+  groupRows: readonly TemplateResourceRow[],
+): Pick<OverviewDraft, "version" | "draftVersion" | "activeSince" | "systemVersion"> {
+  const isActive = preferred.status === "active";
+  const systemSameLocale = groupRows.find(
+    (row) => row.scope === "system" && row.locale === preferred.locale,
+  );
+  return {
+    version: servedVersionOf(preferred),
+    draftVersion: draftVersionFor(user, preferred),
+    activeSince: isActive ? activeSinceOf(preferred).toString() : null,
+    systemVersion: systemSameLocale === undefined ? null : activeVersionOf(systemSameLocale),
+  };
+}
+
+function buildDrafts(
+  groups: ReadonlyMap<string, readonly TemplateResourceRow[]>,
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+): {
+  readonly drafts: OverviewDraft[];
+  readonly layoutSlugByDocument: Map<string, string>;
+} {
+  const layoutSlugByDocument = new Map<string, string>();
+  const drafts: OverviewDraft[] = [];
+  for (const [id, groupRows] of groups) {
+    const effective = effectiveRowsOf(groupRows);
+    const preferred = effective === null ? undefined : preferredRow(effective.rows);
+    if (effective === null || preferred === undefined) continue;
+    if (!isOverviewKind(preferred.kind) || !isTemplateStatus(preferred.status)) continue;
+    const isDocument = preferred.kind === "mail" || preferred.kind === "document-pdf";
+    const layoutSlug = isDocument ? layoutSlugOf(preferred) : null;
+    if (layoutSlug !== null && preferred.kind === "document-pdf") {
+      layoutSlugByDocument.set(preferred.slug, layoutSlug);
+    }
+    drafts.push({
+      id,
+      slug: preferred.slug,
+      kind: preferred.kind,
+      kindGroup: KIND_GROUP[preferred.kind],
+      title: preferred.title ?? preferred.slug,
+      origin: effective.origin,
+      locales: [...new Set(effective.rows.map((row) => row.locale))].sort(),
+      status: preferred.status,
+      ...versionFieldsOf(user, preferred, groupRows),
+      layoutSlug,
+      modifiedAt: modifiedAtOf(preferred),
+    });
+  }
+  return { drafts, layoutSlugByDocument };
+}
+
+function withUsage(
+  draft: OverviewDraft,
+  layoutSlugByDocument: ReadonlyMap<string, string>,
+  registry: Parameters<typeof collectTemplateUsage>[0],
+  effectiveLayouts: EffectiveMailLayoutSlugs,
+): OverviewRow {
+  let usedBy: OverviewUsage[] = [];
+  if (draft.kind === "mail" || draft.kind === "mail-layout") {
+    usedBy = collectTemplateUsage(registry, draft.slug, draft.kind, effectiveLayouts).map(
+      (entry) => ({
+        qualifiedName: entry.qualifiedName,
+        feature: entry.feature,
+        notification: entry.notification,
+        trigger: entry.trigger,
+      }),
+    );
+  } else if (draft.kind === "pdf-layout") {
+    usedBy = [...layoutSlugByDocument]
+      .filter(([, layoutSlug]) => layoutSlug === draft.slug)
+      .map(([documentSlug]) => ({
+        qualifiedName: documentSlug,
+        ...splitDocumentSlug(documentSlug),
+        trigger: null,
+      }));
+  }
+  return { ...draft, usedBy, usedByCount: usedBy.length };
+}
+
+function filterRows(
+  rows: readonly OverviewRow[],
+  search: string | undefined,
+  filters: readonly OverviewFilter[],
+  layoutSlug: string | undefined,
+): OverviewRow[] {
+  const needle = search?.trim().toLowerCase() ?? "";
+  return rows.filter((row) => {
+    if (layoutSlug !== undefined && row.layoutSlug !== layoutSlug) return false;
+    if (needle !== "" && !`${row.title} ${row.slug}`.toLowerCase().includes(needle)) return false;
+    return filters.every((filter) => filter.value.includes(String(row[filter.field])));
+  });
+}
+
+const filterSchema = z.object({
+  field: z.enum(["kindGroup", "kind", "origin", "status"]),
+  op: z.literal("in"),
+  value: z.array(z.string()),
+});
+
+export const overviewQuery = defineQueryHandler({
+  name: "overview",
+  schema: z.object({
+    search: z.string().optional(),
+    filters: z.array(filterSchema).optional(),
+    layoutSlug: z.string().optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+    limit: z.number().int().min(1).max(200).default(50),
+    offset: z.number().int().min(0).optional(),
+    totalCount: z.boolean().optional(),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; use it to browse and filter all templates at a glance.",
+  handler: async (query, ctx) => {
+    const payload = query.payload;
+    const rows = await selectMany<TemplateResourceRow>(
+      ctx.db,
+      templateResourcesTable,
+      { kind: { in: [...OVERVIEW_KINDS] } },
+      { limit: OVERVIEW_ROW_LIMIT },
+    );
+
+    const visibleRows = rows.filter((row) => !isHiddenSystemDraft(query.user, row));
+    const { drafts, layoutSlugByDocument } = buildDrafts(
+      groupBySlugAndKind(visibleRows),
+      query.user,
+    );
+    const effectiveLayouts = effectiveMailLayoutSlugs(visibleRows);
+    const overviewRows = drafts.map((draft) =>
+      withUsage(draft, layoutSlugByDocument, ctx.registry, effectiveLayouts),
+    );
+    const filtered = filterRows(
+      overviewRows,
+      payload.search,
+      payload.filters ?? [],
+      payload.layoutSlug,
+    );
+
+    const sortField: SortField =
+      payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
+    const direction = (payload.sortDirection ?? "desc") === "desc" ? -1 : 1;
+    filtered.sort((a, b) => direction * compareBy(sortField, a, b) || a.id.localeCompare(b.id));
+
+    const offset = payload.offset ?? 0;
+    return {
+      rows: filtered.slice(offset, offset + payload.limit),
+      nextCursor: null,
+      total: filtered.length,
+    } satisfies OverviewResponse;
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/preview.query.ts

@@ -0,0 +1,25 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { renderTemplatePreview } from "../template-preview.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+
+export const previewQuery = defineQueryHandler({
+  name: "preview",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: z.enum(["mail", "document-pdf"]),
+    locale: localeSchema,
+    /** Without content the stored template is previewed. */
+    content: z.string().max(200_000).optional(),
+    meta: z.unknown().optional(),
+    variableSchema: z.record(z.string(), z.unknown()).default({}),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Renders a template draft, or the stored template when no content is given, with sample values taken from the declared variable examples, without saving or sending anything: returns the mail subject, html and plain text with its inline images (a PDF template returns its body and layout regions instead), the sample values used, and checks for unresolved images, missing plain text, mail size and unused required placeholders; a draft that fails the write rules is rejected with the same problems as a save.",
+  handler: async (query, ctx) => {
+    const outcome = await renderTemplatePreview(ctx, query.user, query.payload);
+    if (!outcome.ok) throw outcome.error;
+    return outcome.preview;
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/reset-to-system.write.ts

@@ -0,0 +1,58 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import type { TemplateResourceRow } from "../table.js";
+import { templateResourcesTable } from "../table.js";
+import { executor } from "./shared.js";
+
+export const resetToSystemWrite = defineWriteHandler({
+  name: "reset-to-system",
+  schema: z.object({ id: z.string().min(1) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Retires a tenant override by archiving it so the resolver serves the active system template again; the override and its content survive and can be published again. Refused when there is no active system template to fall back to.",
+  handler: async (event, ctx) => {
+    const existing = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      id: event.payload.id,
+    });
+    if (!existing || existing.tenantId !== event.user.tenantId || existing.scope !== "tenant") {
+      return writeFailure(new NotFoundError("template-resource", event.payload.id));
+    }
+    const systemRow = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug: existing.slug,
+      kind: existing.kind,
+      locale: existing.locale,
+      status: "active",
+    });
+    if (!systemRow) {
+      return writeFailure(
+        new ValidationError({
+          fields: [
+            {
+              path: "id",
+              code: "no_system_template",
+              i18nKey: "templateResolver.errors.noSystemTemplate",
+            },
+          ],
+        }),
+      );
+    }
+    const response = {
+      isSuccess: true as const,
+      data: {
+        id: String(existing.id),
+        status: "archived" as const,
+        systemTemplateId: String(systemRow.id),
+      },
+    };
+    if (existing.status === "archived") return response;
+    const result = await executor.update(
+      { id: existing.id, version: existing.version, changes: { status: "archived" } },
+      event.user,
+      ctx.db,
+    );
+    return result.isSuccess ? response : result;
+  },
+});