@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/cap-overview/screens.ts

@@ -0,0 +1,109 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_USAGE_CELL_COMPONENT,
+  CapOverviewQueries,
+  capFieldName,
+  MY_CAPS_SCREEN_ID,
+  PLATFORM_TENANT_CAPS_SCREEN_ID,
+  TENANT_CAP_LIST_SCREEN_ID,
+} from "./constants.js";
+import type { CapSpec } from "./types.js";
+
+// `tiers` has no room for a separate per-tier display label (it's just
+// `readonly string[]`) — tier-engine itself has no enumerated tier list to
+// derive one from either (it's generic over tier values, see tier-engine's
+// own doc comment). The tier string is used verbatim as the facet option
+// label, same as how tier values already surface untranslated elsewhere
+// (tier-engine's TierMap keys).
+export function createTenantCapListScreen(
+  caps: readonly CapSpec[],
+  listCaps: readonly string[],
+  tiers?: readonly string[],
+): ScreenDefinition {
+  const listedCaps = caps.filter((cap) => listCaps.includes(cap.id));
+
+  return {
+    id: TENANT_CAP_LIST_SCREEN_ID,
+    type: "projectionList",
+    query: CapOverviewQueries.tenantCapsList,
+    columns: [
+      { field: "name", label: "cap-overview.list.col.name" },
+      { field: "tier", label: "cap-overview.list.col.tier" },
+      { field: "billing", label: "cap-overview.list.col.billing" },
+      ...listedCaps.map((cap) => ({
+        field: capFieldName(cap.id),
+        label: cap.label,
+        renderer: { react: { __component: CAP_USAGE_CELL_COMPONENT } },
+      })),
+    ],
+    searchable: true,
+    ...(tiers !== undefined &&
+      tiers.length > 0 && {
+        facets: [
+          {
+            field: "tier",
+            type: "select" as const,
+            label: "cap-overview.list.filter.tier",
+            options: tiers.map((tier) => ({ value: tier, label: tier })),
+          },
+        ],
+      }),
+    // params.map's key ("tenantId") must match platform-tenant-caps's own
+    // `filter.id` — that's how useFilterParams (dashboard-body.tsx) seeds
+    // the tenant filter from the URL on arrival, landing straight on the
+    // clicked tenant's dashboard instead of an empty one (boot-validated).
+    rowActions: [
+      {
+        kind: "navigate" as const,
+        id: "open-dashboard",
+        label: "cap-overview.list.action.open",
+        screen: PLATFORM_TENANT_CAPS_SCREEN_ID,
+        params: { map: { tenantId: "tenantId" } },
+        rowClick: true,
+      },
+    ],
+    defaultSort: { field: "name", dir: "asc" },
+    access: { roles: ["SystemAdmin"] },
+    // No nav wiring yet (see feature.ts header) — no nav area to resolve
+    // in isolation.
+    dormant: true,
+  };
+}
+
+export function createMyCapsScreen(usageRoles: readonly string[]): ScreenDefinition {
+  return {
+    id: MY_CAPS_SCREEN_ID,
+    type: "dashboard",
+    panels: [
+      {
+        kind: "custom",
+        id: "cap-cards",
+        component: { react: { __component: CAP_CARDS_PANEL_COMPONENT } },
+      },
+    ],
+    access: { roles: usageRoles },
+    // No nav wiring yet (see feature.ts header) — no nav area to resolve in
+    // isolation.
+    dormant: true,
+  };
+}
+
+export const platformTenantCapsScreen: ScreenDefinition = {
+  id: PLATFORM_TENANT_CAPS_SCREEN_ID,
+  type: "dashboard",
+  panels: [
+    {
+      kind: "custom",
+      id: "cap-cards",
+      component: { react: { __component: CAP_CARDS_PANEL_COMPONENT } },
+    },
+  ],
+  filter: {
+    id: "tenantId",
+    label: "cap-overview.platform.filter.tenant",
+    kind: "select",
+    optionsQuery: CapOverviewQueries.tenantOptions,
+  },
+  access: { roles: ["SystemAdmin"] },
+};

package/packages/bundled-features/src/cap-overview/types.ts

@@ -0,0 +1,66 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { CapLimitContext } from "../cap-counter/index.js";
+
+// Closed vocabulary for the dashboard cards' icon chip — cap-cards-panel.tsx
+// holds the matching lucide-react lookup. Small on purpose (YAGNI): extend
+// both together when a cap needs a shape not covered here.
+export type CapIconKey = "file" | "hash" | "database" | "users" | "mail" | "gauge";
+
+// Consumer-owned cap definition. `usage`/`usageBatch` receive the SAME
+// unfiltered system-mode TenantDb the handler itself reads through — the
+// callback is responsible for scoping its own app-owned tables by tenantId,
+// same obligation the rest of this feature carries (see feature.ts SECURITY
+// note).
+export type CapSpec = {
+  readonly id: string;
+  readonly label: string;
+  // `null` = unlimited (a pure usage meter: counted but never capped).
+  // `<= 0` = not part of this tier — existing, unchanged meaning (usage-math.ts).
+  // Resolved once per (cap, tier) per request, so a config read here is cheap.
+  readonly limit: (
+    tier: string,
+    context: CapLimitContext,
+  ) => number | null | Promise<number | null>;
+  // `null` means "no measurement exists yet for this cap" (not "0 used") —
+  // callers that haven't wired up instrumentation return null instead of a
+  // number they don't actually have.
+  readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number | null>;
+  // Batched usage lookup for the tenant-caps:list screen — called once per
+  // cap with the current page's tenant ids instead of once per (cap, row).
+  // Optional: falls back to per-row `usage()` when absent. A tenant absent
+  // from the returned map still means 0 (unchanged) — only an explicit
+  // `null` value means "not measured".
+  readonly usageBatch?: (
+    db: TenantDb,
+    tenantIds: readonly TenantId[],
+  ) => Promise<Map<TenantId, number | null>>;
+  readonly unit?: "count" | "mb" | "tokens";
+  /** Icon chip on the dashboard cards. Optional — omitted renders the card
+   *  without an icon, same as before this field existed. */
+  readonly icon?: CapIconKey;
+  /** Icon-chip accent — same raw-CSS-value contract as DashboardStatPanel's
+   *  `accentColor` (packages/types/src/screen.ts): a theme token
+   *  (`var(--color-status-ok)`), not a literal palette hex. Optional. */
+  readonly accentColor?: string;
+};
+
+export type CapUsageTone = "default" | "warn" | "danger";
+
+export type CapUsage = {
+  // `null` means not measured yet — `fraction`/`tone` stay non-nullable
+  // (0 / "default") so no consumer needs null-arithmetic to render.
+  readonly used: number | null;
+  // `limit: null` means unlimited — a pure usage meter with no cap to hit.
+  readonly limit: number | null;
+  readonly fraction: number;
+};
+
+export type CapUsageWithMeta = CapUsage & {
+  readonly id: string;
+  readonly label: string;
+  readonly tone: CapUsageTone;
+  readonly percent: number | null;
+  readonly icon?: CapIconKey;
+  readonly accentColor?: string;
+};

package/packages/bundled-features/src/cap-overview/usage-math.ts

@@ -0,0 +1,34 @@
+// @runtime client
+// Pure math with no runtime deps — both the query handlers (runtime → client
+// is allowed by the compat matrix) and cap-usage-bar.tsx (client → client)
+// import it.
+import type { CapUsageTone } from "./types.js";
+
+const WARN_THRESHOLD = 0.8;
+const DANGER_THRESHOLD = 1;
+
+// limit === null means unlimited (no cap to measure against); limit <= 0
+// means "not part of this tier" — both render as 0, never NaN/Infinity.
+function rawFraction(used: number, limit: number | null): number {
+  if (limit === null) return 0;
+  if (limit <= 0) return 0;
+  const fraction = used / limit;
+  return Number.isFinite(fraction) ? fraction : 0;
+}
+
+export function computeFraction(used: number, limit: number | null): number {
+  return Math.min(1, Math.max(0, rawFraction(used, limit)));
+}
+
+// Unclamped — for display of the over-limit case (e.g. "140%"). Bar width
+// and tone still use the clamped computeFraction; only percent shows the
+// real ratio.
+export function computeUnclampedFraction(used: number, limit: number | null): number {
+  return rawFraction(used, limit);
+}
+
+export function computeTone(fraction: number): CapUsageTone {
+  if (fraction >= DANGER_THRESHOLD) return "danger";
+  if (fraction >= WARN_THRESHOLD) return "warn";
+  return "default";
+}

package/packages/bundled-features/src/cap-overview/web/cap-cards-panel.tsx

@@ -0,0 +1,119 @@
+// @runtime client
+import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  EmptyState,
+  StatCard,
+  StatusBadge,
+  type StatusTone,
+} from "@cosmicdrift/kumiko-renderer-web";
+import { Database, FileText, Gauge, Hash, Mail, Users } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { CapOverviewQueries } from "../constants.js";
+import type { CapIconKey, CapUsageTone, CapUsageWithMeta } from "../types.js";
+import { CapUsageBar } from "./cap-usage-bar.js";
+
+type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
+
+// caps:usage's wire tone stays "default"/"warn"/"danger" (matches the
+// server-side thresholds literally); mapped here to the renderer's actual
+// StatusTone vocabulary instead of inventing new CSS ("danger" has no
+// StatusBadge tone equivalent — "critical" is the closer semantic fit).
+const TONE_TO_STATUS: Record<CapUsageTone, StatusTone> = {
+  default: "muted",
+  warn: "warn",
+  danger: "critical",
+};
+
+// Matches CapIconKey (types.ts) 1:1 — extend both together.
+const CAP_ICONS: Record<CapIconKey, ComponentType<{ className?: string }>> = {
+  file: FileText,
+  hash: Hash,
+  database: Database,
+  users: Users,
+  mail: Mail,
+  gauge: Gauge,
+};
+
+// Narrows `used` only — `percent` can independently be null for an
+// unlimited cap (limit: null) even though used is measured.
+function isMeasured(cap: CapUsageWithMeta): cap is CapUsageWithMeta & { used: number } {
+  return cap.used !== null;
+}
+
+export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  const tenantId =
+    typeof filterParams?.["tenantId"] === "string" ? filterParams["tenantId"] : undefined;
+  const query = useQuery<CapsUsageResponse | null>(CapOverviewQueries.capsUsage, {
+    ...(tenantId !== undefined && { tenantId }),
+  });
+
+  if (query.error !== null) {
+    return (
+      <Banner variant="error" testId="cap-cards-panel-error">
+        {query.error.message}
+      </Banner>
+    );
+  }
+
+  const rows = query.data?.rows ?? [];
+
+  if (!query.loading && rows.length === 0) {
+    return <EmptyState title={t("cap-overview.cards.empty")} testId="cap-cards-panel-empty" />;
+  }
+
+  return (
+    <div
+      // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
+      // styles.css's Tailwind v4 @source scan only covers renderer-web/src,
+      // renderer/src and samples/**/src (see its comment) — bundled-features
+      // isn't scanned, so a class unique to this file has no generated rule
+      // and silently no-ops (the grid fell back to one implicit column,
+      // stacking every card full-width). Reusing the exact classes
+      // dashboard-body.tsx's own panel grid already uses guarantees the
+      // rule exists, since that file IS in the scanned surface.
+      className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4"
+      data-testid="cap-cards-panel"
+    >
+      {query.loading && rows.length === 0 && (
+        <div className="text-sm text-muted-foreground">{t("cap-overview.cards.loading")}</div>
+      )}
+      {rows.map((cap) => {
+        const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
+        // An unlimited, measured cap has neither a badge nor a bar; StatCard still
+        // wraps any defined child in a spacing div, so pass undefined then.
+        const body =
+          !isMeasured(cap) || cap.limit !== null ? (
+            <div className="flex flex-col gap-2">
+              {cap.percent !== null && (
+                <div className="flex items-center justify-between gap-2">
+                  <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
+                </div>
+              )}
+              <CapUsageBar usage={cap} showLabel={false} />
+            </div>
+          ) : undefined;
+        return (
+          <StatCard
+            key={cap.id}
+            icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
+            label={t(cap.label)}
+            value={
+              !isMeasured(cap)
+                ? "—"
+                : cap.limit === null
+                  ? String(cap.used)
+                  : `${cap.used} / ${cap.limit}`
+            }
+            {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
+            testId="cap-card"
+          >
+            {body}
+          </StatCard>
+        );
+      })}
+    </div>
+  );
+}

package/packages/bundled-features/src/cap-overview/web/cap-usage-bar.tsx

@@ -0,0 +1,56 @@
+// @runtime client
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types.js";
+import { computeTone } from "../usage-math.js";
+
+export function CapUsageBar({
+  usage,
+  showLabel = true,
+}: {
+  readonly usage: CapUsage;
+  // The cap-cards-panel StatCard already shows used/limit as its headline
+  // value — the bar's own label would just repeat it there.
+  readonly showLabel?: boolean;
+}): ReactNode {
+  const { Progress, Text, Banner } = usePrimitives();
+  const t = useTranslation();
+
+  if (usage.used === null) {
+    return (
+      <Text variant="small" testId="cap-usage-not-measured">
+        {t("cap-overview.notMeasured")}
+      </Text>
+    );
+  }
+
+  if (usage.limit === null) {
+    // A progress bar with no denominator says nothing — show the raw count instead.
+    return showLabel ? (
+      <Text variant="small" testId="cap-usage-unlimited">
+        {t("cap-overview.unlimited", { used: usage.used })}
+      </Text>
+    ) : null;
+  }
+
+  return (
+    <div className="flex flex-col gap-1">
+      {Progress ? (
+        <Progress
+          value={usage.fraction}
+          tone={computeTone(usage.fraction)}
+          testId="cap-usage-bar"
+        />
+      ) : (
+        // Progress is typed optional only so partial CorePrimitives test
+        // doubles keep compiling — production always registers it via
+        // defaultPrimitives. If it's ever missing, say so instead of
+        // silently dropping the bar (it's the requested content, not decoration).
+        <Banner variant="error" testId="cap-usage-bar-missing-primitive">
+          {t("cap-overview.errors.progressPrimitiveMissing")}
+        </Banner>
+      )}
+      {showLabel && <Text variant="small">{`${usage.used} / ${usage.limit}`}</Text>}
+    </div>
+  );
+}

package/packages/bundled-features/src/cap-overview/web/cap-usage-cell.tsx

@@ -0,0 +1,21 @@
+// @runtime client
+import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types.js";
+import { CapUsageBar } from "./cap-usage-bar.js";
+
+function isCapUsage(value: unknown): value is CapUsage {
+  if (typeof value !== "object" || value === null) return false;
+  const used = (value as { used?: unknown }).used;
+  const limit = (value as { limit?: unknown }).limit;
+  return (
+    (typeof used === "number" || used === null) &&
+    (typeof limit === "number" || limit === null) &&
+    typeof (value as { fraction?: unknown }).fraction === "number"
+  );
+}
+
+export function CapUsageCell({ value }: ColumnRendererProps): ReactNode {
+  if (!isCapUsage(value)) return null;
+  return <CapUsageBar usage={value} />;
+}

package/packages/bundled-features/src/cap-overview/web/client-plugin.tsx

@@ -0,0 +1,27 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_OVERVIEW_FEATURE,
+  CAP_USAGE_CELL_COMPONENT,
+} from "../constants.js";
+import { CapCardsPanel } from "./cap-cards-panel.js";
+import { CapUsageCell } from "./cap-usage-cell.js";
+
+export type CapOverviewClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function capOverviewClient(options?: CapOverviewClientOptions): ClientFeatureDefinition {
+  return {
+    name: CAP_OVERVIEW_FEATURE,
+    columnRenderers: {
+      [CAP_USAGE_CELL_COMPONENT]: CapUsageCell,
+    },
+    extensionSectionComponents: {
+      [CAP_CARDS_PANEL_COMPONENT]: CapCardsPanel,
+    },
+    ...(options?.translations !== undefined && { translations: options.translations }),
+  };
+}

package/packages/bundled-features/src/cap-overview/web/index.ts

@@ -0,0 +1,10 @@
+// @runtime client
+// Public exports for the browser side of the cap-overview feature.
+// Consumed via `@cosmicdrift/kumiko-bundled-features/cap-overview/web` —
+// the server side (createCapOverviewFeature) lives under
+// `@cosmicdrift/kumiko-bundled-features/cap-overview` and has no React deps.
+
+export { CapCardsPanel } from "./cap-cards-panel.js";
+export { CapUsageBar } from "./cap-usage-bar.js";
+export { CapUsageCell } from "./cap-usage-cell.js";
+export { type CapOverviewClientOptions, capOverviewClient } from "./client-plugin.js";

package/packages/bundled-features/src/channel-email/changes.json

@@ -0,0 +1,15 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Explicit List-Unsubscribe headers replace the automatic pair case-insensitively",
+    "detail": "The email channel now matches explicit `data.headers` case-insensitively against the automatic unsubscribe headers. Overriding `List-Unsubscribe` or `List-Unsubscribe-Post` in any spelling drops the whole automatic pair, so a mail client no longer sends a one-click POST to a URL that cannot handle it."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "Automatic List-Unsubscribe / List-Unsubscribe-Post headers for messages that carry a framework unsubscribeUrl",
+    "detail": "`createEmailChannel`'s `send()` now sets `List-Unsubscribe: <url>` and\n`List-Unsubscribe-Post: List-Unsubscribe=One-Click` whenever the\nnotification's `data.unsubscribeUrl` is an `http(s)` URL whose path is\nthe delivery feature's `DELIVERY_UNSUBSCRIBE_PATH` — only that route can\nhonor a one-click POST. An explicit `data.headers[\"List-Unsubscribe\"]`\n(or `-Post`) still wins over the automatic value. Apps whose\n`unsubscribeUrl` points somewhere else (their own page, a foreign path)\nget no automatic headers.",
+    "migration": "No action needed for apps already using the framework's unsubscribe\nroute via `data.unsubscribeUrl`. Apps with a GET-only unsubscribe page of\ntheir own keep getting no `List-Unsubscribe-Post` header, since a\none-click POST there would 404 or no-op."
+  }
+]

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -0,0 +1,127 @@
+import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type ChannelMessage,
+  DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
+  DELIVERY_UNSUBSCRIBE_PATH,
+  type DeliveryChannel,
+  type NotificationRenderer,
+  type RenderedMessage,
+} from "../delivery/index.js";
+import { guardEmailMessage } from "./pii-guard.js";
+import type { EmailTransport } from "./types.js";
+
+// Envelope (From / Reply-To / threading headers) rides on the channel data —
+// the notification's email template echoes it out of the notify() call, since
+// buildMessage collapses the raw data to the template's result. Content
+// (subject, html) is rendered; these three are copied straight to the message.
+function stringHeaders(raw: unknown): Readonly<Record<string, string>> | undefined {
+  if (raw === undefined || raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string") out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+const UNSUBSCRIBE_HEADER_NAMES: ReadonlySet<string> = new Set([
+  "list-unsubscribe",
+  "list-unsubscribe-post",
+]);
+
+// Only the framework's own unsubscribe route can honor a one-click POST.
+function listUnsubscribeHeaders(
+  data: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, string>> | undefined {
+  const rawUrl = data?.["unsubscribeUrl"];
+  if (typeof rawUrl !== "string") return undefined;
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
+  if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH) return undefined;
+  return {
+    "List-Unsubscribe": `<${url.toString()}>`,
+    "List-Unsubscribe-Post": DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
+  };
+}
+
+function emailEnvelopeFrom(data: Readonly<Record<string, unknown>> | undefined): {
+  from?: string;
+  replyTo?: string;
+  headers?: Readonly<Record<string, string>>;
+} {
+  if (!data) return {};
+  const from = typeof data["from"] === "string" ? data["from"] : undefined;
+  const replyTo = typeof data["replyTo"] === "string" ? data["replyTo"] : undefined;
+  const autoHeaders = listUnsubscribeHeaders(data);
+  const explicitHeaders = stringHeaders(data["headers"]);
+  // Header names are case-insensitive, and the auto pair only works together:
+  // an explicit override of either half must drop both, or a mail client would
+  // one-click POST to a URL that cannot handle it.
+  const overridesUnsubscribe =
+    explicitHeaders !== undefined &&
+    Object.keys(explicitHeaders).some((name) => UNSUBSCRIBE_HEADER_NAMES.has(name.toLowerCase()));
+  const headers =
+    (!overridesUnsubscribe && autoHeaders) || explicitHeaders
+      ? { ...(overridesUnsubscribe ? undefined : autoHeaders), ...explicitHeaders }
+      : undefined;
+  return { ...(from && { from }), ...(replyTo && { replyTo }), ...(headers && { headers }) };
+}
+
+export type EmailChannelOptions = {
+  readonly transport: EmailTransport;
+  readonly renderer: NotificationRenderer;
+  readonly resolveEmail: (
+    userId: string,
+    ctx: { db: unknown; tenantId: TenantId },
+  ) => Promise<string | null>;
+};
+
+export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
+  const { transport, renderer, resolveEmail } = options;
+
+  // Render is the expensive step (template engine, possibly a remote service)
+  // and runs in the delivery.render job, decoupled from the SMTP send so each
+  // can retry independently. Extracted so the inline fallback (no job runner)
+  // can reuse it without going through the channel's own render() indirection.
+  async function renderMessage(message: ChannelMessage): Promise<RenderedMessage> {
+    // Build renderer input: per-channel template data (if any) or fall back
+    // to title/body from the message. Renderer handles both cases.
+    const variables = (message.data as DbRow) ?? {
+      title: message.title,
+      body: message.body,
+    };
+    const html = await renderer.render({
+      template: message.notificationType,
+      variables,
+    });
+    const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
+    return { html, subject };
+  }
+
+  return {
+    name: "email",
+    mode: "queued",
+
+    async resolve(userId, ctx) {
+      return resolveEmail(userId, ctx);
+    },
+
+    render(message, _ctx) {
+      return renderMessage(message);
+    },
+
+    async send(address, message, _ctx, rendered) {
+      const { html, subject } = rendered ?? (await renderMessage(message));
+      const envelope = emailEnvelopeFrom(message.data);
+      await transport.send(guardEmailMessage({ to: address, subject, html, ...envelope }));
+      return { status: "sent", address };
+    },
+  };
+}

package/packages/bundled-features/src/channel-email/feature.ts

@@ -0,0 +1,26 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
+
+export function createChannelEmailFeature(options: EmailChannelOptions): FeatureDefinition {
+  const channel = createEmailChannel(options);
+
+  return defineFeature("channel-email", (r) => {
+    r.describe(
+      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.",
+    );
+    r.uiHints({
+      displayLabel: "Email Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
+      mode: channel.mode,
+      resolve: channel.resolve,
+      render: channel.render,
+      send: channel.send,
+    });
+  });
+}

package/packages/bundled-features/src/channel-email/index.ts

@@ -0,0 +1,10 @@
+export { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
+export { createChannelEmailFeature } from "./feature.js";
+export { guardEmailMessage, withPiiCiphertextGuard } from "./pii-guard.js";
+export {
+  createSmtpTransport,
+  createSmtpTransportFromEnv,
+  type SmtpEnv,
+  type SmtpTransportOptions,
+} from "./smtp-transport.js";
+export { createInMemoryTransport, type EmailMessage, type EmailTransport } from "./types.js";