@cosmicdrift/kumiko-bundled-features 0.3.0 → 0.4.1

package/src/renderer-foundation/__tests__/api.test.ts

@@ -0,0 +1,188 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { createRendererFoundationApi } from "../api";
+import {
+  type RendererContext,
+  RendererError,
+  type RendererPlugin,
+  type RenderRequest,
+  type RenderResponse,
+} from "../types";
+
+// Stub-Context für Plugin-Render-Calls in Unit-Tests. makePlugin ignoriert
+// ctx; db+registry sind hier null-cast weil Unit-Tests keinen echten
+// Stack haben — Integration-Tests (collect-plugins.integration.ts) nutzen
+// echte stack.db / stack.registry. tenantId ist valid UUID (Memory-Lesson
+// feedback_system_tenant_id_is_uuid).
+const STUB_CTX: RendererContext = {
+  db: null as never,
+  registry: null as never,
+  tenantId: "11111111-1111-4111-8111-111111111111" as TenantId,
+};
+
+// Test-Helper: minimal Plugin mit fix-Response. Mehrere im Pool für
+// Multi-Kind- + Tenant-Override-Tests.
+function makePlugin(name: string, kinds: RendererPlugin["kinds"]): RendererPlugin {
+  return {
+    name,
+    kinds,
+    render: async (req: RenderRequest): Promise<RenderResponse> => {
+      // shape-by-kind, gibt name in der response damit Tests sehen welcher plugin lief
+      switch (req.kind) {
+        case "notification":
+          return { kind: "notification", html: `from:${name}` };
+        case "mail-html":
+          return { kind: "mail-html", html: `from:${name}`, text: `from:${name}` };
+        case "document-pdf":
+          return {
+            kind: "document-pdf",
+            pdfBytes: new Uint8Array([1, 2, 3]),
+            pageCount: 1,
+            sizeBytes: 3,
+          };
+        case "image-snapshot":
+          return {
+            kind: "image-snapshot",
+            imageBytes: new Uint8Array([1]),
+            format: "png",
+            width: 1,
+            height: 1,
+          };
+      }
+    },
+  };
+}
+
+const TENANT: TenantId = "22222222-2222-4222-8222-222222222222" as TenantId;
+
+describe("renderer-foundation :: Plugin-Selection", () => {
+  test("default-plugin für notification = 'simple'", async () => {
+    const api = createRendererFoundationApi([
+      makePlugin("simple", ["notification"]),
+      makePlugin("other", ["notification"]),
+    ]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("simple");
+  });
+
+  test("default-plugin für mail-html = 'mail-html'", async () => {
+    const api = createRendererFoundationApi([
+      makePlugin("simple", ["notification", "mail-html"]),
+      makePlugin("mail-html", ["mail-html"]),
+    ]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "mail-html" });
+    expect(plugin.name).toBe("mail-html");
+  });
+
+  test("default-plugin für document-pdf = 'puppeteer'", async () => {
+    const api = createRendererFoundationApi([
+      makePlugin("puppeteer", ["document-pdf", "image-snapshot"]),
+    ]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "document-pdf" });
+    expect(plugin.name).toBe("puppeteer");
+  });
+
+  test("Tenant-Override gewinnt vor Default", async () => {
+    const api = createRendererFoundationApi(
+      [makePlugin("simple", ["notification"]), makePlugin("custom-notif", ["notification"])],
+      (tid) => (tid === TENANT ? { notification: "custom-notif" } : null),
+    );
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("custom-notif");
+  });
+
+  test("Tenant-Override auf nicht-registriertes Plugin → fällt durch auf Default", async () => {
+    const api = createRendererFoundationApi([makePlugin("simple", ["notification"])], () => ({
+      notification: "ghost-plugin",
+    }));
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("simple");
+  });
+
+  test("Fallback auf erstes passendes Plugin wenn weder Tenant-Config noch Default-Name matchen", async () => {
+    const api = createRendererFoundationApi([makePlugin("nonstandard-name", ["notification"])]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("nonstandard-name");
+  });
+
+  test("kein Plugin für kind → RendererError", () => {
+    const api = createRendererFoundationApi([makePlugin("simple", ["notification"])]);
+    expect(() => api.createRendererForTenant({ tenantId: TENANT, kind: "document-pdf" })).toThrow(
+      RendererError,
+    );
+  });
+
+  test("leerer Plugin-Pool → RendererError für jeden kind", () => {
+    const api = createRendererFoundationApi([]);
+    expect(() => api.createRendererForTenant({ tenantId: TENANT, kind: "notification" })).toThrow(
+      RendererError,
+    );
+    expect(() => api.createRendererForTenant({ tenantId: TENANT, kind: "mail-html" })).toThrow(
+      RendererError,
+    );
+    expect(() => api.createRendererForTenant({ tenantId: TENANT, kind: "document-pdf" })).toThrow(
+      RendererError,
+    );
+    expect(() => api.createRendererForTenant({ tenantId: TENANT, kind: "image-snapshot" })).toThrow(
+      RendererError,
+    );
+  });
+
+  test("RendererError code='no_plugin_for_kind' wenn kein Plugin", () => {
+    const api = createRendererFoundationApi([]);
+    try {
+      api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+      expect.fail("expected RendererError");
+    } catch (e) {
+      expect(e).toBeInstanceOf(RendererError);
+      expect((e as RendererError).code).toBe("no_plugin_for_kind");
+    }
+  });
+
+  test("Plugin mit mehreren kinds wird für jeden passend gewählt", async () => {
+    const multi = makePlugin("multi", ["notification", "mail-html", "document-pdf"]);
+    const api = createRendererFoundationApi([multi]);
+    expect(api.createRendererForTenant({ tenantId: TENANT, kind: "notification" }).name).toBe(
+      "multi",
+    );
+    expect(api.createRendererForTenant({ tenantId: TENANT, kind: "mail-html" }).name).toBe("multi");
+    expect(api.createRendererForTenant({ tenantId: TENANT, kind: "document-pdf" }).name).toBe(
+      "multi",
+    );
+  });
+
+  test("Plugin mit leeren kinds wird nie ausgewählt", () => {
+    const api = createRendererFoundationApi([
+      makePlugin("empty-kinds", []),
+      makePlugin("simple", ["notification"]),
+    ]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("simple");
+  });
+
+  test("Tenant-Override mit falschem kind-Plugin → ignoriert, Fallback", async () => {
+    // Tenant config sagt "puppeteer" für notification, aber puppeteer kann
+    // nur document-pdf. Foundation muss den falsche-kind-Eintrag ignorieren.
+    const api = createRendererFoundationApi(
+      [makePlugin("simple", ["notification"]), makePlugin("puppeteer", ["document-pdf"])],
+      () => ({ notification: "puppeteer" }),
+    );
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    expect(plugin.name).toBe("simple");
+  });
+});
+
+describe("renderer-foundation :: Plugin executes render", () => {
+  test("Plugin.render returnt RenderResponse mit gleichem kind", async () => {
+    const api = createRendererFoundationApi([makePlugin("simple", ["notification"])]);
+    const plugin = api.createRendererForTenant({ tenantId: TENANT, kind: "notification" });
+    const response = await plugin.render(
+      { kind: "notification", payload: { content: "hello", contentFormat: "markdown" } },
+      STUB_CTX,
+    );
+    expect(response.kind).toBe("notification");
+    if (response.kind === "notification") {
+      expect(response.html).toBe("from:simple");
+    }
+  });
+});

package/src/renderer-foundation/__tests__/collect-plugins.integration.ts

@@ -0,0 +1,101 @@
+import { defineFeature, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createTemplateResolverFeature } from "../../template-resolver/feature";
+import { createRendererFoundationApi } from "../api";
+import { collectRendererPlugins, createRendererFoundationFeature } from "../feature";
+import type { RenderRequest, RenderResponse } from "../types";
+
+const TEST_TENANT = "11111111-1111-4111-8111-111111111111" as TenantId;
+
+let stack: TestStack;
+
+// Mini-Plugin via defineFeature + r.useExtension — wie ein echter
+// renderer-plugin (renderer-simple, renderer-mail-html) sich registriert.
+function createTestPluginFeature(name: string, kinds: ReadonlyArray<string>) {
+  return defineFeature(`renderer-${name}`, (r) => {
+    r.requires("renderer-foundation");
+    r.useExtension("renderer", name, {
+      kinds,
+      render: async (req: RenderRequest): Promise<RenderResponse> => {
+        if (req.kind === "notification") return { kind: "notification", html: `via:${name}` };
+        if (req.kind === "mail-html")
+          return { kind: "mail-html", html: `via:${name}`, text: `via:${name}` };
+        if (req.kind === "document-pdf")
+          return {
+            kind: "document-pdf",
+            pdfBytes: new Uint8Array([1]),
+            pageCount: 1,
+            sizeBytes: 1,
+          };
+        return {
+          kind: "image-snapshot",
+          imageBytes: new Uint8Array([1]),
+          format: "png",
+          width: 1,
+          height: 1,
+        };
+      },
+    });
+  });
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createTemplateResolverFeature(),
+      createRendererFoundationFeature(),
+      createTestPluginFeature("simple", ["notification"]),
+      createTestPluginFeature("mail-html", ["mail-html"]),
+      createTestPluginFeature("puppeteer", ["document-pdf", "image-snapshot"]),
+    ],
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("renderer-foundation :: Plugin-Pool aus Registry", () => {
+  test("collectRendererPlugins findet alle registrierten Plugins", () => {
+    const plugins = collectRendererPlugins(stack.registry);
+    const names = plugins.map((p) => p.name).sort();
+    expect(names).toEqual(["mail-html", "puppeteer", "simple"]);
+  });
+
+  test("jeder Plugin behält seine kinds-Deklaration", () => {
+    const plugins = collectRendererPlugins(stack.registry);
+    const byName = new Map(plugins.map((p) => [p.name, p]));
+    expect([...byName.get("simple")!.kinds]).toEqual(["notification"]);
+    expect([...byName.get("mail-html")!.kinds]).toEqual(["mail-html"]);
+    expect([...byName.get("puppeteer")!.kinds].sort()).toEqual(["document-pdf", "image-snapshot"]);
+  });
+
+  test("API findet Default-Plugin pro kind aus echtem Pool", () => {
+    const plugins = collectRendererPlugins(stack.registry);
+    const api = createRendererFoundationApi(plugins);
+    expect(api.createRendererForTenant({ tenantId: TEST_TENANT, kind: "notification" }).name).toBe(
+      "simple",
+    );
+    expect(api.createRendererForTenant({ tenantId: TEST_TENANT, kind: "mail-html" }).name).toBe(
+      "mail-html",
+    );
+    expect(api.createRendererForTenant({ tenantId: TEST_TENANT, kind: "document-pdf" }).name).toBe(
+      "puppeteer",
+    );
+  });
+
+  test("Plugin.render mit echtem Pool fließt end-to-end durch", async () => {
+    const plugins = collectRendererPlugins(stack.registry);
+    const api = createRendererFoundationApi(plugins);
+    const plugin = api.createRendererForTenant({ tenantId: TEST_TENANT, kind: "notification" });
+    const result = await plugin.render(
+      { kind: "notification", payload: { content: "hello", contentFormat: "markdown" } },
+      { db: stack.db, registry: stack.registry, tenantId: TEST_TENANT },
+    );
+    expect(result.kind).toBe("notification");
+    if (result.kind === "notification") {
+      expect(result.html).toBe("via:simple");
+    }
+  });
+});

package/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";
+import { RendererError, type RendererPlugin } from "./types";
+
+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/src/renderer-foundation/constants.ts

@@ -0,0 +1,21 @@
+// 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";
+
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  RENDER_KINDS,
+  type RenderKind,
+} from "../template-resolver";
+
+// 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/src/renderer-foundation/feature.ts

@@ -0,0 +1,47 @@
+import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { RendererPlugin } from "./types";
+
+// 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.requires("template-resolver");
+
+    r.extendsRegistrar("renderer", {
+      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");
+  return usages.map((usage) => {
+    // @cast-boundary engine-payload — extension-usage carries unknown options
+    const opts = usage.options as {
+      kinds: RendererPlugin["kinds"];
+      render: RendererPlugin["render"];
+    };
+    return {
+      name: usage.entityName,
+      kinds: opts.kinds,
+      render: opts.render,
+    };
+  });
+}

package/src/renderer-foundation/index.ts

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

package/src/renderer-foundation/types.ts

@@ -0,0 +1,109 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ContentFormat, RenderKind } from "./constants";
+
+// 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";
+  }
+}

package/src/renderer-simple/__tests__/adapter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { RendererError } from "../../renderer-foundation";
+import { adaptToFoundation } from "../feature";
+
+describe("renderer-simple :: adaptToFoundation", () => {
+  test("kind='notification' rendert via simpleRenderer und gibt RenderResponse zurück", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: {
+        template: "welcome",
+        variables: { title: "Welcome!", body: "Hello there" },
+      },
+    });
+    expect(res.kind).toBe("notification");
+    if (res.kind === "notification") {
+      // simpleRenderer baut HTML mit title als header + body als section
+      expect(res.html).toContain("Welcome!");
+      expect(res.html).toContain("Hello there");
+      expect(res.html).toContain("<!DOCTYPE html>");
+    }
+  });
+
+  test("leere variables → leerer body, kein crash", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: { template: "", variables: {} },
+    });
+    expect(res.kind).toBe("notification");
+  });
+
+  test("non-notification kind → RendererError mit code 'invalid_payload'", async () => {
+    await expect(
+      adaptToFoundation({
+        kind: "mail-html",
+        payload: { content: "test", contentFormat: "markdown" },
+      }),
+    ).rejects.toThrow(RendererError);
+
+    try {
+      await adaptToFoundation({
+        kind: "document-pdf",
+        payload: { content: "test", contentFormat: "markdown" },
+      });
+      expect.fail("expected RendererError");
+    } catch (e) {
+      expect(e).toBeInstanceOf(RendererError);
+      expect((e as RendererError).code).toBe("invalid_payload");
+    }
+  });
+});