@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/rate-limiting/i18n.ts

@@ -0,0 +1,10 @@
+export const RATE_LIMITING_I18N = {
+  "rateLimiting.errors.bucketOutsideTenant": {
+    en: "You can only inspect rate-limit buckets that belong to your own tenant or user.",
+    de: "Du kannst nur Rate-Limit-Buckets deines eigenen Mandanten oder Benutzers einsehen.",
+  },
+  "rateLimiting.errors.resolverUnavailable": {
+    en: "Rate limiting is not available on this server.",
+    de: "Rate-Limiting ist auf diesem Server nicht verfügbar.",
+  },
+} as const;

package/packages/bundled-features/src/rate-limiting/index.ts

@@ -0,0 +1,2 @@
+export { RATE_LIMITING_FEATURE, RateLimitErrors, RateLimitQueries } from "./constants.js";
+export { createRateLimitingFeature } from "./feature.js";

package/packages/bundled-features/src/readiness/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/readiness/constants.ts

@@ -0,0 +1,7 @@
+// Feature name
+export const READINESS_FEATURE = "readiness" as const;
+
+// Qualified query handler names (QN format: scope:type:name)
+export const ReadinessQueries = {
+  status: "readiness:query:status",
+} as const;

package/packages/bundled-features/src/readiness/feature.ts

@@ -0,0 +1,31 @@
+// kumiko-feature-version: 1
+//
+// readiness — one-call tenant-onboarding rollup above config + secrets.
+//
+// `config:query:readiness` lists required config keys without a usable
+// value; `secrets:query:list` lists set secrets. Neither can verdict
+// "tenant is ready" alone. This feature requires both, so its status
+// query may roll up missing config + missing required secrets + a single
+// `ready` boolean — the settings-checklist call for admin UIs.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { statusQuery } from "./handlers/status.query.js";
+
+export const readinessFeature = defineFeature("readiness", (r) => {
+  r.describe(
+    "One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`.",
+  );
+  r.uiHints({
+    displayLabel: "Readiness · Onboarding Probe",
+    category: "operations",
+    recommended: false,
+  });
+  r.requires("config");
+  r.requires("secrets");
+
+  const queries = {
+    status: r.queryHandler(statusQuery),
+  };
+
+  return { queries };
+});

package/packages/bundled-features/src/readiness/handlers/status.query.ts

@@ -0,0 +1,55 @@
+import {
+  buildProviderSelectionGate,
+  collectMissingRequiredConfig,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { ReadinessQueries } from "../constants.js";
+
+export type ReadinessMissingSecret = { readonly key: string };
+
+// The one-call rollup config:query:readiness deliberately refused: that
+// query can't see secrets, this feature requires both — so it may verdict.
+export const statusQuery = defineQueryHandler({
+  name: "status",
+  description:
+    "Reports whether the caller's tenant is fully configured, naming every required config key and every required secret that is still unset; use it to answer what is missing before go-live.",
+  schema: z.object({}),
+  // Same gate as secrets:query:list — the response names missing secrets.
+  access: { roles: ["TenantAdmin"] },
+  handler: async (query, ctx) => {
+    // One gate for both halves: required keys/secrets of provider-features
+    // count only while their provider is the selected one (r.extensionSelector).
+    const gate = await buildProviderSelectionGate(ctx, ReadinessQueries.status, query.user, ctx.db);
+    // skipAccessFilter: das Verdict muss ALLE required Keys zählen — der
+    // Handler selbst ist TenantAdmin-gated, der Per-Key-Filter wäre hier
+    // eine ready:true-Lüge für SystemAdmin-gated Keys (277/1).
+    const missingConfig = await collectMissingRequiredConfig(
+      ctx,
+      ReadinessQueries.status,
+      query.user,
+      ctx.db,
+      gate,
+      { skipAccessFilter: true },
+    );
+
+    // has() is metadata-only: no decryption, no read-audit event — a
+    // readiness probe must not pollute the credential-read trail.
+    const secrets = requireSecretsContext(ctx, ReadinessQueries.status);
+    const missingSecrets: ReadinessMissingSecret[] = [];
+    for (const [qualifiedName, keyDef] of ctx.registry.getAllSecretKeys()) {
+      if (keyDef.required !== true) continue;
+      if (!gate(qualifiedName)) continue;
+      if (!(await secrets.has(query.user.tenantId, qualifiedName))) {
+        missingSecrets.push({ key: qualifiedName });
+      }
+    }
+
+    return {
+      missingConfig,
+      missingSecrets,
+      ready: missingConfig.length === 0 && missingSecrets.length === 0,
+    };
+  },
+});

package/packages/bundled-features/src/readiness/index.ts

@@ -0,0 +1,3 @@
+export { READINESS_FEATURE, ReadinessQueries } from "./constants.js";
+export { readinessFeature } from "./feature.js";
+export type { ReadinessMissingSecret } from "./handlers/status.query.js";

package/packages/bundled-features/src/renderer-foundation/README.md

@@ -0,0 +1,86 @@
+# renderer-foundation
+
+Plugin-Foundation für Renderer (Notification, HTML-Mail, PDF, Image). Plugins (`renderer-simple`, `renderer-mail-html`, `renderer-puppeteer-client`) registrieren sich via `r.useExtension("renderer", "<name>", { kinds, render })`.
+
+**Plan-Doc:** [`kumiko-platform/docs/plans/features/renderer-foundation.md`](../../../../../../kumiko-platform/docs/plans/features/renderer-foundation.md)
+
+## Mount
+
+```typescript
+import {
+  collectRendererPlugins,
+  createRendererFoundationApi,
+  createRendererFoundationFeature,
+} from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+
+const features = [
+  createTemplateResolverFeature(),
+  createRendererFoundationFeature(),
+  createRendererSimpleFeature(),   // Plugin
+  createRendererMailHtmlFeature(), // Plugin (enterprise)
+  // weitere Plugins...
+];
+
+const app = createKumikoApp({
+  features,
+  extraContext: ({ registry }) => ({
+    rendererFoundation: createRendererFoundationApi(
+      collectRendererPlugins(registry),
+    ),
+  }),
+});
+```
+
+## Konsumtion
+
+```typescript
+import { requireRendererFoundation } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+
+async function sendMail(ctx, tenantId) {
+  const foundation = requireRendererFoundation(ctx, "sendMail");
+  const renderer = foundation.createRendererForTenant({ tenantId, kind: "mail-html" });
+  const result = await renderer.render(
+    {
+      kind: "mail-html",
+      payload: { content: "Hello {{name}}", contentFormat: "markdown", variables: { name: "Frau Schmidt" } },
+    },
+    { db: ctx.db, registry: ctx.registry, tenantId },
+  );
+  // result.html, result.text
+}
+```
+
+Plugins ohne Service-Deps (`renderer-simple`) ignorieren den zweiten `ctx`-Parameter.
+
+## Plugin-Auswahl-Reihenfolge
+
+1. Tenant-Override (Config-Key `rendererPluginByKind`, z.B. `{ "mail-html": "mail-html" }`)
+2. `DEFAULT_PLUGIN_BY_KIND` aus constants
+3. Erstes Plugin im Pool das das kind bedient
+4. `RendererError("no_plugin_for_kind")` wenn nichts passt
+
+## Eigenes Plugin schreiben
+
+```typescript
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const myRendererFeature = defineFeature("renderer-myown", (r) => {
+  r.requires("renderer-foundation");
+  r.useExtension("renderer", "myown", {
+    kinds: ["document-pdf"],
+    // ctx ist optional — nur nehmen wenn Service-Access nötig
+    render: async (req, ctx) => {
+      // ctx.db, ctx.registry, ctx.tenantId verfügbar
+      // eigene PDF-Logik
+      return { kind: "document-pdf", pdfBytes: ..., pageCount: 1, sizeBytes: ... };
+    },
+  });
+});
+```
+
+## Out-of-Scope
+
+- Template-Storage (kommt aus `template-resolver`)
+- Resource-URL-Substitution (Caller-Verantwortung: signed-URL vs. data-URI je nach kind)
+- Template-Authoring-UI — `designer`-Bundle (geplant)
+- Mail-Versand — `delivery` + `mail-transport-smtp`

package/packages/bundled-features/src/renderer-foundation/api.ts

@@ -0,0 +1,106 @@
+// RendererFoundationApi — Cross-Feature-Schnittstelle. Konsumenten
+// (delivery, mail-Sender, Solon NKA-PDF-Generator) holen sich pro
+// Render-Call den passenden Plugin via `createRendererForTenant`.
+// Pattern symmetrisch zu ai-foundation's `createLLMProviderForTenant`.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { DEFAULT_PLUGIN_BY_KIND, type RenderKind } from "./constants.js";
+import { RendererError, type RendererPlugin } from "./types.js";
+
+export type RendererFoundationApi = {
+  /**
+   * Wählt + returnt ein RendererPlugin für (tenantId × kind). Caller
+   * rufen anschließend `plugin.render(req, ctx)`.
+   *
+   * **Auswahl-Reihenfolge:**
+   *   1. Tenant-spezifische Config (config-Bundle: `rendererPluginByKind`)
+   *   2. DEFAULT_PLUGIN_BY_KIND aus constants
+   *   3. Erstes Plugin im Pool das das kind bedient
+   *   4. `RendererError("no_plugin_for_kind")` wenn nichts passt
+   *
+   * **Caller-Pattern:** `tenantId` MUSS vom Server kommen (typisch
+   * `ctx.user.tenantId`). Plugins, die Service-Access brauchen (z.B.
+   * `renderer-mail-html` für Layout-Resolve via `template-resolver`),
+   * erhalten `RendererContext` als zweites Argument zu `render()` —
+   * matcht das Pattern von `DeliveryChannel.send(addr, msg, ctx)`.
+   * Plugins ohne Service-Deps (z.B. `renderer-simple`) ignorieren ctx.
+   */
+  readonly createRendererForTenant: (args: {
+    readonly tenantId: TenantId;
+    readonly kind: RenderKind;
+  }) => RendererPlugin;
+};
+
+// Plugin-Pool wird zur Boot-Zeit aus Extension-Usages aufgebaut.
+// Aus dem Registry kommen alle registrierten Plugins. Foundation-Feature
+// baut den Pool via `collectRendererPlugins(registry)` und steckt das
+// Result in extraContext.
+export function createRendererFoundationApi(
+  plugins: ReadonlyArray<RendererPlugin>,
+  tenantConfigLookup: (tenantId: TenantId) => Record<string, string> | null = () => null,
+): RendererFoundationApi {
+  const byKind = indexByKind(plugins);
+  return {
+    createRendererForTenant: ({ tenantId, kind }) => {
+      const tenantConfig = tenantConfigLookup(tenantId) ?? {};
+
+      // 1. Tenant-Override
+      const tenantPluginName = tenantConfig[kind];
+      if (tenantPluginName) {
+        const plugin = plugins.find((p) => p.name === tenantPluginName && p.kinds.includes(kind));
+        if (plugin) return plugin;
+        // Tenant-Config zeigt auf nicht-registriertes Plugin — fällt durch zu Default
+      }
+
+      // 2. Default-Plugin
+      const defaultName = DEFAULT_PLUGIN_BY_KIND[kind];
+      if (defaultName) {
+        const plugin = plugins.find((p) => p.name === defaultName && p.kinds.includes(kind));
+        if (plugin) return plugin;
+      }
+
+      // 3. Erstes Plugin im Pool das das kind bedient
+      const first = byKind.get(kind)?.[0];
+      if (first) return first;
+
+      // 4. Kein Plugin → Error
+      throw new RendererError(
+        `[renderer-foundation] no plugin registered for kind="${kind}". Mount at least one plugin (renderer-simple, renderer-mail-html, renderer-puppeteer-client) for this kind.`,
+        "no_plugin_for_kind",
+      );
+    },
+  };
+}
+
+function indexByKind(plugins: ReadonlyArray<RendererPlugin>): Map<RenderKind, RendererPlugin[]> {
+  const map = new Map<RenderKind, RendererPlugin[]>();
+  for (const plugin of plugins) {
+    for (const kind of plugin.kinds) {
+      const list = map.get(kind) ?? [];
+      list.push(plugin);
+      map.set(kind, list);
+    }
+  }
+  return map;
+}
+
+// Single point of truth für "dieser Handler braucht renderer-foundation".
+// Pattern symmetrisch zu requireTemplateResolver + requireTextContent.
+export function requireRendererFoundation(
+  ctx: { readonly rendererFoundation?: RendererFoundationApi } | object,
+  callerName: string,
+): RendererFoundationApi {
+  // @cast-boundary engine-bridge — rendererFoundation kommt per extraContext
+  // aus App-Bootstrap.
+  const api = (ctx as { rendererFoundation?: RendererFoundationApi }).rendererFoundation;
+  if (!api) {
+    throw new InternalError({
+      message:
+        `[${callerName}] ctx.rendererFoundation missing — App-Bootstrap muss ` +
+        `extraContext: { rendererFoundation: createRendererFoundationApi(plugins) } setzen ` +
+        `(siehe renderer-foundation/README.md).`,
+    });
+  }
+  return api;
+}

package/packages/bundled-features/src/renderer-foundation/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "Bundled extension points (renderer, deliveryChannel, mailTransport, inboundMailProvider, subscriptionProvider) are typed",
+    "migration": "r.useExtension options for renderer ({ kinds, render }), deliveryChannel ({ mode, resolve, render?, send, accept? }), mailTransport (MailTransportPlugin), inboundMailProvider (InboundMailProviderPlugin) and subscriptionProvider (SubscriptionProviderPlugin) are now type-checked and required; renderer and deliveryChannel registrations do not pass name (it comes from the entity name). Prefer the new constants RENDERER_EXTENSION, DELIVERY_CHANNEL_EXTENSION and MAIL_TRANSPORT_EXTENSION over string literals. A registration whose options do not match the plugin shape now throws with the entity name when channels or renderers are collected."
+  }
+]

package/packages/bundled-features/src/renderer-foundation/constants.ts

@@ -0,0 +1,25 @@
+// Re-export aus template-resolver — gleiche RenderKind-Domäne. Beide
+// Bundles teilen sich die Enum, damit Plugins (renderer-mail-html etc.)
+// nicht zwei Quellen importieren müssen. Cross-feature-Imports gehen
+// über das Barrel (../template-resolver), nicht via deep-import.
+import type { RenderKind as RenderKindLocal } from "../template-resolver/index.js";
+
+// Extension-point name for renderer plugins (renderer-simple,
+// renderer-mail-html, renderer-puppeteer-client, ...).
+export const RENDERER_EXTENSION = "renderer" as const;
+
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  RENDER_KINDS,
+  type RenderKind,
+} from "../template-resolver/index.js";
+
+// Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
+// gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.
+export const DEFAULT_PLUGIN_BY_KIND: Readonly<Record<RenderKindLocal, string>> = {
+  notification: "simple",
+  "mail-html": "mail-html",
+  "document-pdf": "puppeteer",
+  "image-snapshot": "puppeteer",
+};

package/packages/bundled-features/src/renderer-foundation/feature.ts

@@ -0,0 +1,52 @@
+import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { RENDERER_EXTENSION } from "./constants.js";
+import { isRendererRegistrationPlugin, type RendererPlugin } from "./types.js";
+
+// renderer-foundation — Plugin-Foundation für Renderer (Notification,
+// HTML-Mail, PDF, Image). Plan-Doc:
+// kumiko-platform/docs/plans/features/renderer-foundation.md
+//
+// Pattern symmetrisch zu ai-foundation: Foundation definiert den
+// Extension-Point `renderer`, Plugins (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client) registrieren sich via `r.useExtension`.
+// Konsumenten holen sich Plugin runtime via createRendererForTenant.
+export function createRendererFoundationFeature() {
+  return defineFeature("renderer-foundation", (r) => {
+    r.describe(
+      'Plugin registry for content rendering (notification HTML, mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block \u2014 add `renderer-simple` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.',
+    );
+    r.uiHints({
+      displayLabel: "Renderer Foundation",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("template-resolver");
+
+    r.extendsRegistrar(RENDERER_EXTENSION, {
+      onRegister: () => {
+        // Plugin-Konformitäts-Check könnte hier: shape-validation der
+        // options (kinds, render-Funktion present). Aktuell kein
+        // shape-check — Caller's TypeScript-Type-Sicherheit greift.
+      },
+    });
+
+    return {};
+  });
+}
+
+// Plugin-Pool-Aufbau zur Boot-Zeit. App-Bootstrap ruft das nach
+// Feature-Registration auf, baut den Pool, gibt ihn via extraContext
+// an die Handlers weiter.
+//
+// Symmetrisch zu collectChannels / collectRenderers in delivery-service.
+export function collectRendererPlugins(registry: Registry): RendererPlugin[] {
+  const usages = registry.getExtensionUsages(RENDERER_EXTENSION);
+  return usages.map((usage) => {
+    if (!isRendererRegistrationPlugin(usage.options)) {
+      throw new Error(
+        `${RENDERER_EXTENSION} registration for "${usage.entityName}" has invalid options`,
+      );
+    }
+    return { name: usage.entityName, ...usage.options };
+  });
+}

package/packages/bundled-features/src/renderer-foundation/index.ts

@@ -0,0 +1,28 @@
+export {
+  createRendererFoundationApi,
+  type RendererFoundationApi,
+  requireRendererFoundation,
+} from "./api.js";
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  DEFAULT_PLUGIN_BY_KIND,
+  RENDER_KINDS,
+  RENDERER_EXTENSION,
+  type RenderKind,
+} from "./constants.js";
+export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.js";
+export {
+  type DocumentPayload,
+  type ImageOptions,
+  isRendererRegistrationPlugin,
+  type MailHtmlPayload,
+  type NotificationPayload,
+  type PdfOptions,
+  type RendererContext,
+  RendererError,
+  type RendererPlugin,
+  type RendererRegistrationPlugin,
+  type RenderRequest,
+  type RenderResponse,
+} from "./types.js";

package/packages/bundled-features/src/renderer-foundation/types.ts

@@ -0,0 +1,131 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.js";
+
+// RenderRequest — Plugins erhalten das. Resource-Mode wählt der Caller
+// (renderer-foundation api) je nach kind oder explizit. Plugin selbst
+// entscheidet nicht — es bekommt eine schon aufgelöste Form.
+export type RenderRequest =
+  | { kind: "notification"; payload: NotificationPayload }
+  | { kind: "mail-html"; payload: MailHtmlPayload }
+  | { kind: "document-pdf"; payload: DocumentPayload; options?: PdfOptions }
+  | { kind: "image-snapshot"; payload: DocumentPayload; options?: ImageOptions };
+
+export type RenderResponse =
+  | { kind: "notification"; html: string }
+  | { kind: "mail-html"; html: string; text: string }
+  | { kind: "document-pdf"; pdfBytes: Uint8Array; pageCount: number; sizeBytes: number }
+  | {
+      kind: "image-snapshot";
+      imageBytes: Uint8Array;
+      format: "png" | "jpg";
+      width: number;
+      height: number;
+    };
+
+export type NotificationPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type MailHtmlPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  readonly subject?: string;
+};
+
+export type DocumentPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type PdfOptions = {
+  readonly format?: "A4" | "Letter";
+  readonly marginMm?: { top?: number; right?: number; bottom?: number; left?: number };
+  readonly headerTemplate?: string;
+  readonly footerTemplate?: string;
+  readonly printBackground?: boolean;
+  readonly displayHeaderFooter?: boolean;
+};
+
+export type ImageOptions = {
+  readonly width?: number;
+  readonly height?: number;
+  readonly format?: "png" | "jpg";
+  readonly quality?: number;
+};
+
+// RendererContext — schmale Surface (Kumiko-Style, matcht FileProviderContext
+// + ChannelContext). Plugins, die Service-Access brauchen, holen sich
+// templateResolver/etc. via direkten Bundle-Import + ctx.db (cross-feature-
+// public-API). KEIN extraContext-Pass-Through — Plugin importiert pure-
+// Function-Factories statt App-ctx zu casten.
+//
+// **Beispiel renderer-mail-html:**
+//   import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+//   const tplApi = createTemplateResolverApi(ctx.db);
+//   const layout = await tplApi.resolveTemplate({ tenantId: ctx.tenantId, slug, kind });
+export type RendererContext = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+};
+
+// RendererPlugin-Contract — pro Plugin (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client). Plugin deklariert welche kinds es bedienen
+// kann; Foundation-Resolver wählt basierend auf Tenant-Config + kind.
+//
+// **Plugin-Invarianten:**
+// - `kinds` muss min. 1 Element haben (sonst nie ausgewählt)
+// - `render(req, ctx)`-Response.kind MUSS req.kind matchen
+// - Plugin ist zustandslos: kein internal-state zwischen render-Calls
+// - Plugin wirft `RendererError` für domain-Fehler (nicht bare Error)
+// - `ctx` ist required. Plugins ohne Service-Deps (z.B. renderer-simple)
+//   ignorieren ihn einfach — TS function-arg variance erlaubt `(req) => ...`-
+//   Implementations weiterhin (Implementation-Args ≤ Contract-Args ist OK).
+export type RendererPlugin = {
+  readonly name: string;
+  readonly kinds: ReadonlyArray<RenderKind>;
+  render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+};
+
+export class RendererError extends Error {
+  constructor(
+    message: string,
+    public readonly code: "no_plugin_for_kind" | "invalid_payload" | "other",
+  ) {
+    super(message);
+    this.name = "RendererError";
+  }
+}
+
+// r.useExtension options-shape: `name` is NOT part of the registration
+// payload — collectRendererPlugins derives it from the usage's entityName.
+export type RendererRegistrationPlugin = Omit<RendererPlugin, "name">;
+
+export function isRendererRegistrationPlugin(o: unknown): o is RendererRegistrationPlugin {
+  return (
+    typeof o === "object" &&
+    o !== null &&
+    "kinds" in o &&
+    Array.isArray(o.kinds) &&
+    "render" in o &&
+    typeof o.render === "function"
+  );
+}
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [RENDERER_EXTENSION]: RendererRegistrationPlugin;
+  }
+}

package/packages/bundled-features/src/renderer-simple/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/renderer-simple/feature.ts

@@ -0,0 +1,57 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  RENDERER_EXTENSION,
+  type RendererContext,
+  RendererError,
+  type RenderRequest,
+  type RenderResponse,
+} from "../renderer-foundation/index.js";
+import { resolveNotificationVariables } from "./resolve-variables.js";
+import { simpleRenderer } from "./simple-renderer.js";
+
+// Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
+// NotificationRenderer-Contract), renderer-foundation erwartet
+// `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
+// die simpleRenderer-Implementierung (Template-Strings → HTML mit
+// Inline-CSS) und packt sie in den RendererPlugin-Contract.
+//
+// Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
+export async function adaptToFoundation(
+  req: RenderRequest,
+  ctx: RendererContext,
+): Promise<RenderResponse> {
+  if (req.kind !== "notification") {
+    // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
+    // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
+    throw new RendererError(
+      `renderer-simple supports only kind="notification", got "${req.kind}"`,
+      "invalid_payload",
+    );
+  }
+  const variables = await resolveNotificationVariables(req, ctx);
+  const html = await simpleRenderer.render({
+    template: req.payload.template ?? "",
+    variables,
+  });
+  return { kind: "notification", html };
+}
+
+export function createRendererSimpleFeature(): FeatureDefinition {
+  return defineFeature("renderer-simple", (r) => {
+    r.describe(
+      'Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.',
+    );
+    r.uiHints({
+      displayLabel: "Renderer \u00b7 Simple",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("renderer-foundation");
+    r.optionalRequires("template-resolver");
+
+    r.useExtension(RENDERER_EXTENSION, "simple", {
+      kinds: ["notification"] as const,
+      render: adaptToFoundation,
+    });
+  });
+}

package/packages/bundled-features/src/renderer-simple/index.ts

@@ -0,0 +1,2 @@
+export { createRendererSimpleFeature } from "./feature.js";
+export { simpleRenderer } from "./simple-renderer.js";