@company-semantics/contracts 27.12.0 → 27.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "27.12.0",
+  "version": "27.13.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/email/README.md

@@ -2,17 +2,25 @@
 
 ## Purpose
 
-TypeScript types and registry for transactional email kinds and their metadata.
+Transactional email vocabulary **and** render layer: kind types, the subject
+registry, and the shared component system (`render/`) that both the backend
+(real sends) and the app (Ladle preview) compose. See ADR-CONTRACTS-077.
 
 ## Invariants
 
-- Types only; minimal runtime code (pure functions for registry lookup)
-- No external dependencies (contracts policy)
-- `EmailKind` union MUST match keys in `EMAIL_KINDS` registry
-- `EMAIL_KINDS` is the single source of truth for subjects and rendering rules
-- OTP values MUST NEVER appear in contracts (security: logged if leaked)
-- Subjects are owned by the registry, never duplicated in templates
-- Unknown email kinds MUST be rejected at API boundaries via `isValidEmailKind()`
+- Types + **pure** render functions only — no classes, no side effects, no
+  external imports beyond `zod` (vocabulary-guard enforced).
+- `render/blocks.ts` owns all styled markup; templates supply only content text.
+  Editing a block restyles every email — HTML and plain text — in both repos.
+- `renderEmail(kind, payload, options?)` is the single dispatcher; subject comes
+  from `EMAIL_KINDS`, never hardcoded in a template.
+- `EmailKind` union MUST match keys in `EMAIL_KINDS` registry.
+- OTP values MUST NEVER appear as literals in contracts (security: logged if
+  leaked) — they are runtime payload fields only.
+- Every user-controlled field in an HTML variant MUST pass through `escapeHtml`.
+- Rendered output is locked by `render/__tests__/render-snapshot.test.ts`
+  (production-parity markup — a snapshot change means a real email changed).
+- Unknown email kinds MUST be rejected at API boundaries via `isValidEmailKind()`.
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 

package/src/email/index.ts

@@ -28,3 +28,9 @@ export {
   getEmailKindDefinition,
   isValidEmailKind,
 } from "./registry";
+
+// =============================================================================
+// Render Layer
+// =============================================================================
+
+export * from "./render";