# OpenSpec Change: enterprise-email-templates

- **Change ID**: enterprise-email-templates
- **Package**: `@suaveplan/email-templates`
- **Category**: communication / emails
- **Target path**: `packages/communication/emails/email-templates`
- **Status**: IN PROGRESS
- **Date**: 2026-05-25
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/email-templates.md`

---

## Summary

Deliver `@suaveplan/email-templates` on genesis as a universal-tier, **React-free** email template engine. Upstream ships JSX components rendered via `react-dom/server`; the genesis rebuild honours enterprise spec §3 ("Zero browser / Node / React dependencies — pure TypeScript, runs in Bun, Node, and browser") by re-implementing the full upstream surface as **VNode factories** (`{ tag, attrs, children }`) walked by a pure-string HTML renderer.

The full public surface is preserved: nine reusable components (`EmailLayout`, `EmailContainer`, `EmailHeading`, `EmailText`, `EmailLink`, `EmailImage`, `EmailDivider`, `EmailButton`, `EmailFooter`), five built-in templates (`welcome`, `verification`, `password-reset`, `notification`, `invoice`), a typed `TemplateRegistry`, fluent `TemplateBuilder`, theming primitives (`defaultTheme` / `createTheme` / `mergeThemes`), the `createEmailMessage` adapter, and renderer helpers (`renderToHtml`, `wrapInDocument`, `resolveSubject`, `escapeHtml`, `stripHtml`). Genesis adds structured `EmailTemplatesError` codes, Zod-validated public schemas, injectable `Clock` (to remove `new Date().getFullYear()` at module scope inside the footer), and OTel instruments on every render.

---

## Current-state audit (genesis)

The package does not exist on genesis yet. Upstream lives at `/mnt/s/web/suaveplan/packages/universal/email-templates/` (73 files, 4,949 LOC, React 19 runtime dep, 100% coverage). Every consumer presently imports JSX-returning `ComponentType`s; the genesis port must change the **component shape** from `ComponentType<P>` to `(props: P) => VNode` while keeping the same exported names.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` | `EmailTemplatesError`; `EMAIL_TEMPLATES.*` code registry via `defineCodes` |
| `@suaveplan/types` | `Clock`, injectable for the footer copyright year |
| `@suaveplan/opentelemetry` | Lazy meter accessor (sibling-package convention) |
| `@opentelemetry/api` (`catalog:observability`) | Counters + histogram |
| `zod` (`catalog:forms`) | Public-input validation |
| `tslib` (`catalog:build`) | Runtime helpers |

Dev deps: `@suaveplan/testing` (runner wrapper), `@vitest/coverage-istanbul`, `vitest`, `vite`, `vite-plugin-dts`.

---

## Public API surface (React-stripped)

### VNode core

```ts
export interface VNode {
  readonly tag: string;                                 // 'table' | 'tr' | 'td' | 'a' | ...
  readonly attrs: Readonly<Record<string, string | number | undefined>>;
  readonly children: ReadonlyArray<VNode | string>;
  readonly self_closing?: boolean;                      // img, br, hr, meta
}
export type EmailNode = VNode | string;
export type EmailChildren = EmailNode | ReadonlyArray<EmailNode>;

export function h(
  tag: string,
  attrs?: Record<string, string | number | undefined>,
  children?: EmailChildren,
): VNode;
```

### Components (factories returning `VNode`)

```ts
EmailLayout(props: EmailLayoutProps): VNode
EmailContainer(props: EmailContainerProps): VNode
EmailHeading(props: EmailHeadingProps): VNode
EmailText(props: EmailTextProps): VNode
EmailLink(props: EmailLinkProps): VNode
EmailImage(props: EmailImageProps): VNode
EmailDivider(props: EmailDividerProps): VNode
EmailButton(props: EmailButtonProps): VNode
EmailFooter(props: EmailFooterProps): VNode
```

Each prop shape is identical to upstream **except** `children` is now `EmailChildren` instead of `ReactNode`, and `style` is `Record<string, string | number>` instead of `CSSProperties`.

### Templates

```ts
WelcomeEmail(props: WelcomeProps & { theme?: EmailTheme; clock?: Clock }): VNode
VerificationEmail(props: VerificationProps & { theme?: EmailTheme; clock?: Clock }): VNode
PasswordResetEmail(props: PasswordResetProps & { theme?: EmailTheme; clock?: Clock }): VNode
NotificationEmail(props: NotificationProps & { theme?: EmailTheme; clock?: Clock }): VNode
InvoiceEmail(props: InvoiceProps & { theme?: EmailTheme; clock?: Clock }): VNode

export const welcomeTemplate:      EmailTemplate<WelcomeProps>;
export const verificationTemplate: EmailTemplate<VerificationProps>;
export const passwordResetTemplate:EmailTemplate<PasswordResetProps>;
export const notificationTemplate: EmailTemplate<NotificationProps>;
export const invoiceTemplate:      EmailTemplate<InvoiceProps>;
```

### Renderer / registry / builder / theme / message

```ts
export interface EmailTemplate<TProps = unknown> {
  readonly name: string;
  readonly subject: string | ((props: TProps) => string);
  readonly component: (props: TProps & { theme?: EmailTheme; clock?: Clock }) => VNode;
  readonly defaultProps?: Partial<TProps>;
}

export function renderToHtml<T>(template: EmailTemplate<T>, props: T, options?: RenderOptions): RenderResult;
export function wrapInDocument(body: string, options?: HtmlDocumentOptions): string;
export function resolveSubject<T>(template: EmailTemplate<T>, props: T): string;
export function escapeHtml(str: string): string;
export function stripHtml(html: string): string;
export function renderVNode(node: EmailNode): string;          // new — VNode → HTML

export class TemplateRegistry<TMap extends TemplateMap = TemplateMap> { /* register/get/has/list/search/remove/clear */ }
export function createRegistry<T extends TemplateMap = TemplateMap>(opts?: RegistryOptions): TemplateRegistry<T>;

export class TemplateBuilder<TProps> { /* name / subject / component / defaultProps / build */ }
export function createTemplateBuilder<TProps>(): TemplateBuilder<TProps>;

export const defaultTheme: EmailTheme;
export function createTheme(opts?: EmailThemeOptions): EmailTheme;
export function mergeThemes(base: EmailTheme, override: EmailThemeOptions): EmailTheme;

export function createEmailMessage<T>(
  template: EmailTemplate<T>,
  props: T,
  recipient: EmailRecipient,
  options?: CreateEmailMessageOptions,
): EmailMessageResult;
```

### Error codes

```ts
EMAIL_TEMPLATES.INVALID_TEMPLATE
EMAIL_TEMPLATES.INVALID_OPTIONS
EMAIL_TEMPLATES.RENDER_FAILURE
EMAIL_TEMPLATES.DUPLICATE_NAME
EMAIL_TEMPLATES.UNKNOWN_TEMPLATE
EMAIL_TEMPLATES.INVALID_HEADING_LEVEL
```

### OTel instruments

- `email_templates.render_total{template,outcome}` — counter
- `email_templates.render_duration_ms{template}` — histogram
- `email_templates.registry_register_total{outcome}` — counter
- `email_templates.validation_failure_total{reason}` — counter

---

## Genesis additions

1. **VNode renderer** — new `renderVNode` function walks the tree producing HTML with: HTML-encoded text (`&<>"'`), inline `style="..."` emission from object styles, MSO-conditional comments preserved from upstream `wrapInDocument`, self-closing for `img`/`br`/`hr`/`meta`.
2. **Injectable `Clock`** — footer copyright year reads from `clock.now()` instead of `new Date().getFullYear()` at call time; default supplied if omitted.
3. **Structured errors** — `EmailTemplatesError` extends `SuaveplanError` with six stable codes.
4. **Zod schemas** — public input validation for `EmailButtonProps.variant/size`, heading level (1–6), notification level, footer link, registry options.
5. **OTel instrumentation** — counters + histogram wired in `renderToHtml`, `TemplateRegistry.register`, and the validation pathway.
6. **Structured-HTML test assertions** — tests use `htmlparser2` (added to a sensible catalog) to parse rendered output and assert tag structure / attributes — never raw string snapshots, never mocks.

---

## File layout

```text
packages/communication/emails/email-templates/
  package.json
  tsconfig.lib.json
  vite.config.ts
  vitest.config.ts
  README.md
  src/
    index.ts
    error-codes/{error-codes.ts, error-codes.test.ts, error-codes.md, index.ts}
    telemetry/{telemetry.ts, telemetry.test.ts, telemetry.md, index.ts}
    vnode/{vnode.ts, vnode.test.ts, vnode.md, vnode.types.ts, index.ts}
    theme/{theme.ts, theme.test.ts, theme.md, theme.types.ts, index.ts}
    renderer/{renderer.ts, renderer.test.ts, renderer.md, renderer.types.ts, index.ts}
    message/{message.ts, message.test.ts, message.md, message.types.ts, index.ts}
    template-builder/{template-builder.ts, template-builder.test.ts, template-builder.md, template-builder.types.ts, index.ts}
    template-registry/{template-registry.ts, template-registry.test.ts, template-registry.md, template-registry.types.ts, index.ts}
    components/
      email-layout/{email-layout.ts, email-layout.test.ts, email-layout.md, email-layout.types.ts, index.ts}
      email-container/{...}
      email-heading/{...}
      email-text/{...}
      email-link/{...}
      email-image/{...}
      email-divider/{...}
      email-button/{...}
      email-footer/{...}
    templates/
      welcome/{welcome.ts, welcome.test.ts, welcome.md, welcome.types.ts, index.ts}
      verification/{...}
      password-reset/{...}
      notification/{...}
      invoice/{...}
```

---

## Affected dependents

None on genesis yet — `emailer`/`campaigns` consume their own minimal templating today; they may opt in to this package post-archive.

## Workspace dep prerequisites

`@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry`. All ✅ on `genesis`.