@lupinum/nuxt-email 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/agent/pages/docs/reference/render-email.md

@@ -0,0 +1,107 @@
+---
+title: "renderEmail"
+description: "The one public render API — its signature, deterministic result shape, plain-text contract, and security boundary."
+url: "https://nuxt-email.lupinum.com/docs/reference/render-email"
+route: "/docs/reference/render-email"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# renderEmail
+
+> The one public render API — its signature, deterministic result shape, plain-text contract, and security boundary.
+
+`renderEmail(name, props)` is the one public application rendering path. Nuxt generates template names and prop types from the Vue single-file components (`.vue` files) in `app/emails/`. It resolves the selected component through the same server-only registry used by the development preview.
+
+```ts
+const result = await renderEmail('welcome', {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+})
+```
+
+It is a **Nitro auto-import** — available in server handlers and other Nitro server code, not in Vue components, client plugins, or production client bundles. Do not import it from `@lupinum/nuxt-email` or `#imports`.
+
+## Result shape
+
+The promise resolves to the canonical `RenderedEmail` type, available from the package root as a type-only import:
+
+```ts
+import type { RenderedEmail } from '@lupinum/nuxt-email'
+```
+
+- `html` — the rendered document. Begins with the XHTML 1.0 Transitional doctype.
+- `text` — authored metadata when declared, otherwise the derived plain-text fallback (see below).
+- `subject` — present only when the template declares one via [`defineEmail`](/raw/docs/guides/subject-lines.md); otherwise absent.
+
+There is no preview metadata, provider result, diagnostics object, timing, or size field. Sending is not part of this function — your application supplies recipients, sender identity, subject, credentials, and provider-specific options directly to its chosen provider SDK.
+
+## HTML contract
+
+- A template must render exactly one `<html>` root containing exactly one `<body>`. `EHtml` requires an explicit non-empty language and defaults only `dir="ltr"`; the renderer never repairs or auto-wraps fragments, text roots, body-only templates, or multiple roots.
+- `EHead` is optional but supplies the recommended UTF-8 and Apple reformatting meta tags.
+- Vue SSR interpolation and attribute values are escaped.
+- A fresh isolated Vue SSR application is created for every call. Email templates receive E-components through server-only auto-imports.
+- Framework code never fetches images, stylesheets, fonts, or other remote assets during rendering.
+
+**Determinism:** two calls with the same template code and props return byte-identical `html` and `text`. Templates remain responsible for avoiding clocks, random values, mutable external state, and nondeterministic data.
+
+## Props and generated types
+
+Template names are relative `.vue` paths under `app/emails/`, without the extension and with `/` separators — `app/emails/account/reset-password.vue` becomes `account/reset-password`. Files under `app/emails/components/` are excluded.
+
+Props declared with ordinary `defineProps()` or Vue's `props` option drive both the generated call-site type and runtime validation. TypeScript rejects unknown template names, missing required props, wrong values, and extra props. Untyped runtime calls reject unknown or missing props deterministically before SSR.
+
+There is no public registry API — the generated registry is an internal server artifact and the sole source for rendering, generated types, and preview listings.
+
+## Select a template dynamically
+
+Keep each template name paired with its props in a literal dispatch map. Validate external input before choosing an entry. Do not cast an arbitrary string to a template name; that removes the generated type protection.
+
+```ts [server/utils/render-transactional-email.ts]
+interface WelcomeInput {
+  firstName: string
+  activationUrl: string
+}
+
+interface PasswordResetInput {
+  code: string
+  expiresInMinutes: number
+}
+
+export const emailDispatch = {
+  welcome: (input: WelcomeInput) => renderEmail('welcome', input),
+  passwordReset: (input: PasswordResetInput) => renderEmail('account/reset-password', input),
+} as const
+
+// Select an entry only after validating the event and its payload.
+await emailDispatch.welcome({
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+})
+```
+
+Each map entry contains a literal registry name. TypeScript checks its input against that template's generated props. A wrong name or prop shape fails where the entry is declared.
+
+## Plain-text contract
+
+Unless the template declares authored `text` with `defineEmail`, Nuxt Email derives `text` from the final HTML. It uses a fixed `html-to-text` version with no line wrapping.
+
+The conversion excludes head content, images, script and style content, and elements marked `data-skip-in-text="true"`. This removes `EPreview` from the fallback. Links retain destinations when their visible text differs. See the [plain-text guide](/raw/docs/guides/plain-text.md) for details and the `data-text-format="dataTable"` opt-in.
+
+## Security boundary
+
+Nuxt Email renders trusted application templates with untrusted values supplied only through normal escaped Vue bindings. It is **not** an HTML sanitizer.
+
+- All E-prefixed primitives reject `innerHTML`, `textContent`, and attributes beginning with `on`.
+- There is no raw-HTML component. Do not use `v-html` or native raw HTML with untrusted content inside a template.
+- `href` and `src` values are escaped but URL schemes are **not** validated. Validate application-controlled URLs before rendering.
+- When consumed through the canonical generated API, template modules and the renderer are server-only and excluded from the client build. Do not import email templates into client code.
+- Development fixture modules, preview UI, and preview endpoints are absent from production builds. Do not import fixture modules into production code.
+- No production HTTP render route and no send route are generated. A route exists only when you create one.
+
+The production server intentionally contains templates referenced by its registry. The guarantee is client exclusion, not removal from the server that renders them.
+
+For render and lookup failures, see [error types](/raw/docs/reference/errors.md).

package/dist/agent/pages/docs/reference.md

@@ -0,0 +1,30 @@
+---
+title: "Reference"
+description: "The precise contracts — renderEmail, module behavior, error types, conformance, and migration."
+url: "https://nuxt-email.lupinum.com/docs/reference"
+route: "/docs/reference"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Reference
+
+> The precise contracts — renderEmail, module behavior, error types, conformance, and migration.
+
+The reference section is the precise contract for Nuxt Email's public surface. Where a guide explains a task, the reference states exactly what is guaranteed.
+
+<cards cols="2">
+<card title="renderEmail" description="The render API, result shape, plain-text contract, and security boundary." icon="lucide:function-square" to="/docs/reference/render-email" />
+
+<card title="defineEmail" description="Template subject and authored plain-text metadata." icon="lucide:tags" to="/docs/reference/define-email" />
+
+<card title="Module behavior" description="Discovery, auto-imports, and opt-in syntax highlighting." icon="lucide:package" to="/docs/reference/module" />
+
+<card title="Error types" description="Every typed error and the stable information it carries." icon="lucide:triangle-alert" to="/docs/reference/errors" />
+
+<card title="Conformance and divergences" description="How compatibility is measured and where output intentionally differs." icon="lucide:git-compare" to="/docs/reference/conformance" />
+
+<card title="Migration from React Email" description="Translate JSX templates and rendering calls to Nuxt Email." icon="lucide:arrow-left-right" to="/docs/reference/migration" />
+</cards>

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.5.1 <5"
   },
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -191,9 +191,9 @@ const module$1 = defineNuxtModule({
     alias["@lupinum/nuxt-email/errors"] = errorsPublicPath;
     const externals = nitro.externals ??= {};
     const inline = externals.inline ??= [];
-    for (const publicRuntimePath of [defineEmailPublicPath, errorsPublicPath]) {
-      if (!inline.includes(publicRuntimePath)) {
-        inline.push(publicRuntimePath);
+    for (const runtimePath of [defineEmailPublicPath, errorsPublicPath, testingRendererPath]) {
+      if (!inline.includes(runtimePath)) {
+        inline.push(runtimePath);
       }
     }
     const typescript = nitro.typescript ??= {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/nuxt-email",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "Typed transactional email for Nuxt with email-safe Tailwind v4",
   "keywords": [
     "email",
@@ -50,7 +50,8 @@
     "./errors": {
       "types": "./dist/runtime/errors.d.ts",
       "import": "./dist/runtime/errors.js"
-    }
+    },
+    "./agent-docs": "./dist/agent/AGENTS.md"
   },
   "main": "./dist/module.mjs",
   "types": "./dist/module.d.mts",
@@ -61,7 +62,7 @@
   ],
   "peerDependencies": {
     "nuxt": ">=4.5.1 <5",
-    "vue": "^3.5.35"
+    "vue": "^3.5.40"
   },
   "dependencies": {
     "@nuxt/kit": ">=4.5.1 <5",
@@ -100,7 +101,7 @@
     "react-dom": "19.2.7",
     "react-email": "6.9.0",
     "tsx": "4.23.1",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.11",
     "vue": "3.5.42",
     "yaml": "2.9.0"
   },
@@ -115,20 +116,25 @@
     "oracle:check": "node --import tsx test/conformance/tooling/generate-react-oracle.ts --check",
     "oracle:write": "node --import tsx test/conformance/tooling/generate-react-oracle.ts --write",
     "performance:measure": "node --expose-gc --import tsx test/performance/measure.ts",
-    "docs:build": "pnpm docs:theme && nuxt-module-build prepare && pnpm prepack && pnpm --dir docs build",
+    "docs:build": "pnpm docs:theme && nuxt-module-build prepare && pnpm build && pnpm --dir docs build",
+    "docs:onboarding": "node scripts/sync-consumer-onboarding.mjs --write",
+    "docs:package": "node scripts/build-agent-docs.mjs",
     "docs:theme": "node scripts/check-docs-theme.mjs",
     "proofs:generate": "node --import tsx scripts/proofs/generate.ts",
     "proofs:send": "node --import tsx scripts/proofs/send.ts",
     "repo:check": "node scripts/check-repository-policy.mjs",
-    "release:verify": "pnpm verify && node --import tsx scripts/verify-release.ts",
+    "release:verify": "pnpm verify && pnpm release:pack",
     "release:prepare": "changelogen --bump --clean --hideAuthorEmail",
     "release:artifact": "pnpm release:verify --output .release/lupinum-nuxt-email.tgz && node scripts/write-release-manifest.mjs",
-    "lint": "eslint .",
-    "test": "pnpm prepack && vitest run --exclude test/preview.test.ts && pnpm test:preview",
+    "lint": "node scripts/sync-consumer-onboarding.mjs && eslint .",
+    "test": "pnpm build && vitest run --exclude test/preview.test.ts --reporter=default --reporter=./test/conformance/tooling/reporter.ts && pnpm test:preview",
     "test:preview": "vitest run test/preview.test.ts",
     "test:conformance": "vitest run test/conformance",
     "test:watch": "vitest watch",
     "test:types": "pnpm dev:prepare && nuxt prepare test/fixtures/basic && nuxt prepare test/fixtures/code-block && nuxt prepare test/fixtures/preview && vue-tsc --noEmit && vue-tsc --noEmit -p test/fixtures/basic/.nuxt/tsconfig.server.json && vue-tsc --noEmit -p test/fixtures/code-block/.nuxt/tsconfig.server.json && vue-tsc --noEmit -p test/fixtures/preview/.nuxt/tsconfig.server.json && cd playground && vue-tsc --noEmit",
-    "verify": "pnpm audit:all && pnpm repo:check && pnpm lint && pnpm test:types && pnpm test && pnpm conformance:check && pnpm docs:build"
+    "verify": "pnpm check:dependencies && pnpm audit:all && pnpm repo:check && pnpm lint && pnpm test:types && pnpm test && pnpm docs:build",
+    "check:dependencies": "node scripts/check-dependency-policy.mjs",
+    "build": "nuxt-module-build build",
+    "release:pack": "node --import tsx scripts/verify-release.ts"
   }
 }