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

package/dist/agent/pages/docs/guides/client-compatibility.md

@@ -0,0 +1,65 @@
+---
+title: "Client compatibility and proofs"
+description: "What is automatically proven, and the manual email-client QA checklist that closes the remaining gap."
+url: "https://nuxt-email.lupinum.com/docs/guides/client-compatibility"
+route: "/docs/guides/client-compatibility"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Client compatibility and proofs
+
+> What is automatically proven, and the manual email-client QA checklist that closes the remaining gap.
+
+Nuxt Email separates automated compatibility evidence from manual client results.
+
+## What is automatically proven
+
+The [conformance suite](/raw/docs/reference/conformance.md) compares covered behavior with fixed React Email versions. It checks exact bytes, normalized output, or specific semantics. Presentation tables, Outlook-specific button spacers, preview hiding, font declarations, and Tailwind inlining have regression cases.
+
+This is useful implementation evidence, but it is a comparison to a reference renderer, not proof that every email client will display a message identically.
+
+## Completed beta smoke test
+
+Matthias completed the owner-run `1.0.0-beta.1` smoke test on 2026-08-22. The same `proof-kit` message passed in Gmail web, Apple Mail on macOS, and Outlook classic on Windows in light and dark modes. The [signed QA record](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/release/client-qa-checklist.md#100-beta1-smoke-test) records the tested commit and artifact hashes.
+
+This smoke test is enough for the published beta. It does not complete the full eight-client checklist required for stable `1.0.0`. An external transactional beta also remains pending.
+
+## Run the stable checklist
+
+Automated tests do not open real email clients. Run the stable checklist against the fixed `proof-kit` fixture.
+
+<steps>
+### Render the fixture
+
+Run `pnpm proofs:generate`, then use the committed `proof-kit` template and props. Optionally replace only the logo URL with an HTTPS image you control.
+
+### Send with your own account
+
+Send the exact rendered `html` and `text` to test mailboxes through a provider SDK you choose. Nuxt Email does not send mail.
+
+### Inspect in three clients
+
+Open the same message in **Gmail web**, **Apple Mail** (macOS or iOS), and **Outlook for Windows**.
+
+### Record the result
+
+Note client versions, screenshots, defects, and a final accept/reject decision.
+</steps>
+
+## Required checks
+
+- Inbox preview shows only the intended preview sentence and does not expose filler characters.
+- The remote logo has useful alternative text when images are blocked.
+- Heading, paragraphs, divider, and footer links retain readable spacing.
+- The activation button is clickable, visually centered, and has comparable horizontal and vertical padding **in Outlook**.
+- Two columns stay in one row at desktop email widths and remain readable when the client narrows the message.
+- Link destinations and the `mailto:` link are correct.
+- Plain-text fallback contains the meaningful content and destinations but excludes preview filler and images.
+- No script, hydration payload, framework state, or event-handler attribute is present.
+
+<card title="Beta QA is not stable approval" icon="lucide:shield-alert">
+The three-client smoke test is complete. Stable `1.0.0` still waits for the full eight-client record and external beta evidence.
+</card>

package/dist/agent/pages/docs/guides/plain-text.md

@@ -0,0 +1,42 @@
+---
+title: "Plain text"
+description: "How the plain-text fallback is produced from the rendered HTML, what it excludes, and how to control table output."
+url: "https://nuxt-email.lupinum.com/docs/guides/plain-text"
+route: "/docs/guides/plain-text"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Plain text
+
+> How the plain-text fallback is produced from the rendered HTML, what it excludes, and how to control table output.
+
+Every render returns a `text` string alongside `html`. By default it is a deterministic fallback produced from the **final rendered HTML**. Nuxt Email uses a fixed `html-to-text` version with no line wrapping.
+
+When automatic conversion is not good enough, the template can declare authored text with `defineEmail({ text: '…' })` or a synchronous `text` function. Authored text replaces derivation for that render; it does not create a second template or rendering path.
+
+## What plain text includes and excludes
+
+- **Excluded:** head content, images, `<script>`/`<style>` content, and any element marked `data-skip-in-text="true"`. `EPreview` is therefore absent from the fallback.
+- **Links:** destinations are retained when the visible text differs from the URL. Fragment links and `mailto:` links follow the recorded React Email comparison behavior.
+- **Structure:** nested lists, ordered-list starts, blockquotes, hard breaks, preformatted content, Unicode, and ordinary tables all have exact conformance cases.
+
+## Controlling table output
+
+By default tables render as plain rows. When you specifically need aligned, column-formatted output for a table, add `data-text-format="dataTable"` to that table:
+
+```vue
+<table data-text-format="dataTable">
+  <!-- rows -->
+</table>
+```
+
+## Inspect it every time
+
+Plain text is a real deliverable that some recipients and spam filters read. Inspect it in the [development preview](/raw/docs/guides/preview-workflow.md)'s **Plain text** tab for every transactional template, exactly as you would review the HTML.
+
+<card title="ECodeInline appears once" icon="lucide:info">
+`ECodeInline` keeps two copies in HTML for `Orange.fr` compatibility, but marks the hidden copy to be skipped by plain-text generation. Recipients therefore receive the code once in the text alternative. This is an intentional divergence from React Email.
+</card>

package/dist/agent/pages/docs/guides/preview-workflow.md

@@ -0,0 +1,83 @@
+---
+title: "Preview workflow"
+description: "Use the development-only /__email preview, add fixtures, and monitor exact rendered size without treating it as a client guarantee."
+url: "https://nuxt-email.lupinum.com/docs/guides/preview-workflow"
+route: "/docs/guides/preview-workflow"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Preview workflow
+
+> Use the development-only /__email preview, add fixtures, and monitor exact rendered size without treating it as a client guarantee.
+
+Nuxt Email exposes `/__email` while the development server is running. The path follows the configured Nuxt base URL. Open `/__email` with the default base URL, or `/sub/__email` with `app.baseURL: '/sub/'`.
+
+The preview lists every template under `app/emails/` and marks templates without fixture data. It shows rendered HTML, exact HTML source, or plain text. The visible page polls once per second, so saved template and fixture changes appear without a restart. Polling pauses in a hidden tab.
+
+When Nuxt DevTools is available, its **Nuxt Email** iframe shortcut opens the same baseURL-aware preview. The shortcut adds no second preview application or route.
+
+The preview calls the same server-only registry and `renderEmail()` implementation your handlers use. It is a rendering and debugging tool — not a second rendering path and not an email-client compatibility guarantee.
+
+## Add a fixture
+
+Place one exact sibling file beside a template. Only the `.fixtures.ts` suffix is recognized, and it must default-export one props object:
+
+```ts [app/emails/welcome.fixtures.ts]
+import type { EmailComponentProps } from '@lupinum/nuxt-email'
+import type WelcomeEmail from './welcome.vue'
+
+export default {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+} satisfies EmailComponentProps<typeof WelcomeEmail>
+```
+
+The preview intentionally supports **one fixed scenario per template** and does not accept request-provided props or generate editing forms.
+
+## Inspect output
+
+<steps>
+### Preview
+
+Loads the raw rendered HTML in a sandboxed iframe (no script permission).
+
+### HTML
+
+Displays the exact `html` returned by `renderEmail()`.
+
+### Plain text
+
+Displays the exact `text` returned by `renderEmail()`.
+
+### Copy / Open
+
+**Copy** copies the active representation; **Open** opens the raw development render in a separate tab.
+</steps>
+
+Render failures show the template name, the `EmailRenderError` stack, and its original cause. Use the [error reference](/raw/docs/reference/errors.md) to find the recovery step by symptom.
+
+A template without a fixture remains in the list. Add its sibling fixture before trying to render it.
+
+## Mind the approximate Gmail clipping budget
+
+Gmail is commonly observed clipping messages around **102 KB**, but behavior can vary with the account, message, and delivery path. Nuxt Email reports the rendered HTML's exact UTF-8 byte count; the Gmail-specific interpretation is an approximate authoring warning, not a guarantee:
+
+```ts
+const { html } = await renderEmail('welcome', props)
+console.log('bytes:', Buffer.byteLength(html, 'utf8'))
+```
+
+Keep the rendered HTML comfortably below the warning area and test the delivered message in your target Gmail accounts. Inlined Tailwind utilities and repeated markup add up quickly, so measure your largest, most dynamic template.
+
+The preview has no dark-mode simulation. Email clients transform dark-mode content differently, so test dark rendering in the real clients you support.
+
+## Production boundary
+
+The preview page, endpoints, and fixture imports exist **only in development**. Production builds contain none of their routes or fixture data. The raw render endpoint uses a restrictive content security policy. Its iframe has no script permission.
+
+The development endpoints cannot become production render or send APIs. Use the typed server-only [`renderEmail`](/raw/docs/reference/render-email.md) in your handlers.
+
+Next, [render the template from Nitro](/raw/docs/getting-started/render-from-nitro.md).

package/dist/agent/pages/docs/guides/sending-email.md

@@ -0,0 +1,132 @@
+---
+title: "Sending email"
+description: "Hand Nuxt Email output to a provider SDK or a local Mailpit SMTP server."
+url: "https://nuxt-email.lupinum.com/docs/guides/sending-email"
+route: "/docs/guides/sending-email"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Sending email
+
+> Hand Nuxt Email output to a provider SDK or a local Mailpit SMTP server.
+
+Nuxt Email renders content; your application sends it. This keeps recipients, credentials, retries, idempotency, rate limits, and delivery logs in application code where they belong.
+
+`renderEmail` returns `html`, `text`, and an optional `subject`. Pass those values directly to your delivery client. Decide the fallback subject in the application when a template does not declare one.
+
+## Provider SDK example
+
+Install your provider's SDK in the application. This example uses [Resend's Node SDK](https://resend.com/docs/api-reference/emails/send-email), whose send call accepts `subject`, `html`, and `text`:
+
+```bash
+pnpm add resend
+```
+
+```ts [server/utils/send-welcome.ts]
+import { Resend } from 'resend'
+
+const resend = new Resend(process.env.NUXT_EMAIL_RESEND_API_KEY)
+
+export async function sendWelcomeEmail(to: string, firstName: string) {
+  const email = await renderEmail('welcome', {
+    firstName,
+    activationUrl: 'https://example.com/activate',
+  })
+
+  const { data, error } = await resend.emails.send({
+    from: 'Example <hello@example.com>',
+    to,
+    subject: email.subject ?? 'Welcome',
+    html: email.html,
+    text: email.text,
+  })
+
+  if (error) {
+    throw error
+  }
+
+  return data
+}
+```
+
+Keep the API key server-only. Validate and authorize the action that chooses `to`; do not accept arbitrary recipients from an unauthenticated request. For production retries, use the provider's idempotency feature so one application event cannot send the same message twice.
+
+## Local SMTP with Mailpit
+
+[Mailpit](https://mailpit.axllent.org/docs/install/) captures development email instead of delivering it. Its defaults are SMTP on `1025` without authentication or encryption and a browser UI at `http://localhost:8025`. Install Nodemailer in the application:
+
+```bash
+pnpm add nodemailer
+pnpm add -D @types/nodemailer
+```
+
+```ts [server/utils/send-welcome-local.ts]
+import nodemailer from 'nodemailer'
+
+const mailpit = nodemailer.createTransport({
+  host: '127.0.0.1',
+  port: 1025,
+  secure: false,
+})
+
+export async function sendWelcomeEmailLocally(to: string, firstName: string) {
+  const email = await renderEmail('welcome', {
+    firstName,
+    activationUrl: 'http://localhost:3000/activate',
+  })
+
+  return await mailpit.sendMail({
+    from: 'Example <hello@example.test>',
+    to,
+    subject: email.subject ?? 'Welcome',
+    html: email.html,
+    text: email.text,
+  })
+}
+```
+
+1. Start Mailpit separately.
+2. Run the application action that sends the email.
+3. Open `http://localhost:8025` and inspect the captured message.
+
+This tests the provider handoff and the full message with headers. It does not replace the [real email-client checklist](/raw/docs/guides/client-compatibility.md).
+
+## Inline images with CID attachments
+
+Hosted HTTPS images are usually simpler. Use a Content-ID (CID) attachment when the image bytes must travel inside the message.
+
+Reference one unique CID from the template:
+
+```vue [app/emails/receipt.vue]
+<EImg src="cid:logo@example.com" alt="Example" width="120" height="32" />
+```
+
+Give the Nodemailer attachment the exact same `cid` value:
+
+```ts [server/utils/send-receipt.ts]
+const email = await renderEmail('receipt', receiptProps)
+
+await mailer.sendMail({
+  from: 'Example <receipts@example.com>',
+  to,
+  subject: email.subject ?? 'Your receipt',
+  html: email.html,
+  text: email.text,
+  attachments: [
+    {
+      filename: 'logo.png',
+      path: '/application-owned-assets/logo.png',
+      cid: 'logo@example.com',
+    },
+  ],
+})
+```
+
+The delivery client reads the attachment bytes and creates the related Multipurpose Internet Mail Extensions (MIME) parts. Nuxt Email only preserves the `cid:` image source. See Nodemailer's [embedded image documentation](https://nodemailer.com/message/embedded-images/).
+
+## Ownership boundary
+
+Nuxt Email deliberately does not provide a send function, provider adapter, queue, webhook handler, or SMTP configuration. The application owns delivery policy and can replace its provider without changing template authoring or rendering.

package/dist/agent/pages/docs/guides/standalone-rendering.md

@@ -0,0 +1,118 @@
+---
+title: "Render outside Nitro"
+description: "Compile the same Vue templates for a Node backend without booting Nuxt."
+url: "https://nuxt-email.lupinum.com/docs/guides/standalone-rendering"
+route: "/docs/guides/standalone-rendering"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Render outside Nitro
+
+> Compile the same Vue templates for a Node backend without booting Nuxt.
+
+Build a server-only email registry before you deploy your backend. The registry
+uses the same rendering core as Nitro and the development preview. Your
+application still owns delivery.
+
+## Compile the registry
+
+The output directory belongs to the build. Do not put source files there. The
+helper rejects an existing directory that it did not create. Do not import the
+generated registry into browser code.
+
+```js [scripts/build-emails.mjs]
+import { buildEmailRegistry } from '@lupinum/nuxt-email/build'
+
+await buildEmailRegistry({
+  rootDir: '.',
+  outDir: 'generated/emails',
+})
+```
+
+Run this script from the application root before the backend build. Run it again
+when templates or their imports change. Do not run it inside a request, action,
+or background delivery job.
+
+`rootDir` is the project root. Templates default to `app/emails`. For a custom
+Nuxt `srcDir`, pass `templatesDir: 'src/emails'`, relative to `rootDir`. The helper
+does not load Nuxt configuration. Relative `outDir` paths also use `rootDir`.
+The output must remain inside the project root, outside the template directory,
+so build-time declarations and the generated module can resolve project dependencies.
+
+The helper generates:
+
+- `generated/emails/index.mjs`: compiled Vue components and the runtime registry.
+- `generated/emails/index.d.mts`: template names and inferred prop types.
+- `generated/emails/types/`: Vue-generated declarations and their local imports.
+
+These files are derived output. Keep them out of version control and regenerate
+them in the deployment build. Ordinary TypeScript reads the declarations without
+a Vue compiler. A compilation failure leaves the previous successful output
+unchanged. Do not run concurrent builds against the same output path.
+
+## Render with runtime data
+
+```ts [backend/render-welcome.ts]
+import { renderEmail } from '../generated/emails/index.mjs'
+
+const email = await renderEmail('welcome', {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+})
+```
+
+The template controls the props. This example uses the welcome template from the
+quickstart. The result contains `html`, `text`, and an optional `subject`.
+Validate external input before calling the renderer.
+
+If your build already compiles Vue components, use the production renderer
+directly:
+
+```ts [backend/render-component.ts]
+import { renderEmailComponent } from '@lupinum/nuxt-email/render'
+import Welcome from './compiled/welcome.js'
+
+const email = await renderEmailComponent(Welcome, {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+})
+```
+
+## Keep templates portable
+
+Keep local imports inside the email directory. Import Vue helpers and
+`defineEmail` explicitly. Nuxt aliases, plugins, auto-imported composables and
+application state are not available in this build. The existing email components
+remain registered by the renderer. Put reusable components in `components/` and
+import them explicitly from templates.
+
+The standalone compiler supports HTML templates and JavaScript or TypeScript
+scripts, including `script setup`, async setup, and template-only components.
+It rejects SFC `style` blocks, custom blocks, external blocks (`src`), JSX and
+template preprocessors. Use `ETailwind` or inline styles. Nitro keeps its existing
+Vue compiler integration; this portable subset does not replace that integration
+or claim support for every feature in a Nuxt application.
+
+This first standalone build does not configure `ECodeBlock`. Use Nitro for
+templates that require configured syntax highlighting. There is no silent
+fallback renderer. Preview fixtures are not discovered or imported by the
+production registry.
+
+The build uses Vue's SFC compiler, esbuild, TypeScript and vue-tsc. They are build dependencies of
+the package, not imports of the production render entry. The runtime registry
+leaves package dependencies external; the application's backend bundler must
+include or resolve them.
+
+## Verify the deployment
+
+Node package rendering and generated declaration checks are separate from a
+hosted deployment test. Convex Node actions are a target for integration testing;
+this package change does not certify a deployed Convex application. The default
+Convex runtime and edge workers are not supported claims.
+
+Before production use, test the packed package in your actual backend, including
+concurrent renders, dynamic props, fonts and Tailwind output. Measure cold and
+warm execution. Never make auth delivery depend on an unverified rendering path.

package/dist/agent/pages/docs/guides/subject-lines.md

@@ -0,0 +1,95 @@
+---
+title: "Subject lines"
+description: "Compute a subject line from the same typed props with defineEmail, and read it back from the render result."
+url: "https://nuxt-email.lupinum.com/docs/guides/subject-lines"
+route: "/docs/guides/subject-lines"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Subject lines
+
+> Compute a subject line from the same typed props with defineEmail, and read it back from the render result.
+
+Nuxt Email does not own subjects — sending is your provider's job — but a template often knows how to phrase its own subject from the same data it renders. `defineEmail` lets a template declare a subject and, when needed, authored plain text beside the template.
+
+## Declare a subject
+
+Call `defineEmail` in the template's `<script setup>`. It is an explicit server-only import from `@lupinum/nuxt-email/define-email`.
+
+```vue [app/emails/welcome.vue]
+<script setup lang="ts">
+import { defineEmail } from '@lupinum/nuxt-email/define-email'
+
+const props = defineProps<{
+  firstName: string
+  activationUrl: string
+}>()
+
+defineEmail({
+  subject: () => `Welcome aboard, ${props.firstName}`,
+})
+</script>
+
+<template>
+  <EHtml lang="en">
+    <EHead><title>Activate your account</title></EHead>
+    <EBody>
+      <EPreview>Your account is ready.</EPreview>
+      <EContainer>
+        <EHeading>Welcome, {{ firstName }}</EHeading>
+        <EButton :href="activationUrl" :style="{ padding: '12px 20px' }">Activate</EButton>
+      </EContainer>
+    </EBody>
+  </EHtml>
+</template>
+```
+
+The zero-argument `subject` closure captures the template's real `defineProps()` value and returns the subject string. Constant strings work too. There is no separate generic prop declaration that can drift from the `.vue` file.
+
+To replace automatic plain-text derivation, add `text` to the same declaration:
+
+```ts
+defineEmail({
+  subject: () => `Welcome aboard, ${props.firstName}`,
+  text: () => `Welcome, ${props.firstName}. Activate your account: ${props.activationUrl}`,
+})
+```
+
+`defineEmail` requires at least one of `subject` or `text`. Both accept a string or a synchronous function returning a string.
+
+## Read it back
+
+When a template declares `subject` with `defineEmail`, the render result carries it:
+
+```ts [server/api/welcome.get.ts]
+export default defineEventHandler(async () => {
+  const { html, text, subject } = await renderEmail('welcome', {
+    firstName: 'Ada',
+    activationUrl: 'https://example.com/activate',
+  })
+
+  // subject === 'Welcome aboard, Ada'
+  return { html, text, subject }
+})
+```
+
+`subject` is `string | undefined` on `RenderedEmail`. It is absent when the template does not declare `subject`, including when `defineEmail` declares only `text`.
+
+## Rules and edge cases
+
+- **Runs during render only.** Calling `defineEmail` outside an email render throws `DefineEmailOutsideRenderError`.
+- **One declaration per render.** Calling it twice in one template render throws `DuplicateEmailDefinitionError`.
+- **Returns strings synchronously.** A non-string subject or text value fails the render with an `EmailRenderError` whose cause explains the invalid value. Promise-returning functions are rejected by TypeScript.
+- **Works before or after `await`.** The render context is propagated with `AsyncLocalStorage`, so declaring the subject after a top-level `await` in `<script setup>` (for example after fetching data) still resolves to the correct render.
+- **Concurrent renders are isolated.** Each render has its own context, so subjects never leak between simultaneous renders.
+
+<card title="You still pass it to your provider" icon="lucide:info">
+`subject` is a convenience for keeping subject phrasing beside the template. You still hand it to your provider SDK alongside `from`, `to`, `html`, and `text` — Nuxt Email does not send mail or set headers.
+</card>
+
+Continue with the [sending guide](/raw/docs/guides/sending-email.md) for a complete provider handoff.
+
+See the [`defineEmail` reference](/raw/docs/reference/define-email.md) for its exact signature, exports, precedence, and error contract.

package/dist/agent/pages/docs/guides/tailwind.md

@@ -0,0 +1,128 @@
+---
+title: "Using Tailwind"
+description: "How ETailwind inlines utilities, how nested-component classes are reached, and the exact documented limitations."
+url: "https://nuxt-email.lupinum.com/docs/guides/tailwind"
+route: "/docs/guides/tailwind"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Using Tailwind
+
+> How ETailwind inlines utilities, how nested-component classes are reached, and the exact documented limitations.
+
+Wrap an email document in `<ETailwind>` and Tailwind v4 utility classes on descendant elements are compiled into email-safe output at render time. Compatible declarations become inline styles; the boundary is server-only and requires a `<head>` inside it.
+
+```vue
+<ETailwind>
+  <EHtml lang="en">
+    <EHead />
+    <EBody class="bg-gray-100">
+      <EContainer class="p-4">
+        <EText class="text-red-500">Styled with Tailwind</EText>
+      </EContainer>
+    </EBody>
+  </EHtml>
+</ETailwind>
+```
+
+## Precedence and non-inlinable rules
+
+Inlining precedence is **component defaults < Tailwind utilities < author `style`**. Media queries and pseudo-classes cannot become inline styles. Nuxt Email moves them to a `<style>` element in `<head>`. It sanitizes residual class names and preserves Outlook-specific (`mso-*`) properties. Rendering fails with the affected class names when these rules have no head inside the boundary.
+
+Tailwind v4 emits nested CSS for variants such as `hover:` and responsive combinations. Nuxt Email recursively flattens that nesting and converts media range syntax before it places the CSS in the email. A Tailwind nesting shape that cannot be converted safely fails the render instead of leaving a raw `&` rule in the output.
+
+## Dark mode
+
+Keep the base colors readable on their own. Some email clients ignore dark-mode rules, and others transform colors without using your rules.
+
+The `dark:` variant emits `@media (prefers-color-scheme: dark)` CSS in `<head>`. Treat it as progressive enhancement.
+
+```vue
+<EBody class="bg-white text-slate-900 dark:bg-slate-900 dark:text-white">
+  <EText>Readable with or without dark-mode support.</EText>
+</EBody>
+```
+
+Support varies across Gmail and Outlook versions. Check the current [Can I Email evidence for `prefers-color-scheme`](https://www.caniemail.com/features/css-at-media-prefers-color-scheme/) and test the clients your recipients use.
+
+You can extend the engine through props:
+
+- `config` — a Tailwind config (everything except `content`), matching React Email's `TailwindConfig`.
+- `theme` — raw CSS appended to the `@theme` layer.
+- `utility` — raw CSS appended to the utilities layer.
+
+## Share tokens, not the Nuxt stylesheet
+
+Email rendering does not load the Nuxt application's CSS bundle, and browser CSS variables cannot be relied on in email clients. A class such as `text-primary` must resolve to a concrete value while the email renders.
+
+Keep one application-owned token source and feed its value into `ETailwind` explicitly:
+
+```vue
+<script setup lang="ts">
+import { emailTheme } from '~/shared/email-theme'
+</script>
+
+<template>
+  <ETailwind :theme="emailTheme">
+    <EHtml lang="en">
+      <EHead />
+      <EBody>
+        <EText class="text-primary">Concrete email color</EText>
+      </EBody>
+    </EHtml>
+  </ETailwind>
+</template>
+```
+
+```ts [shared/email-theme.ts]
+export const emailTheme = '@theme { --color-primary: #2563eb; }'
+```
+
+The same token module can generate or inform your Nuxt theme, but Nuxt Email does not add a second CSS discovery path or silently import application styles.
+
+`ETailwind` accepts the `config`, `theme`, and `utility` values you pass directly. It does not resolve arbitrary CSS file imports or CSS `@plugin` module imports at render time; supply executable Tailwind plugins through `config`. This keeps production rendering independent of the application filesystem.
+
+## Classes inside nested components
+
+Classes written directly in the email template are resolved during rendering. Classes emitted inside a nested component are resolved too. A reusable card or button therefore uses the same Tailwind behavior as inline markup:
+
+```vue [Card.vue]
+<template>
+  <div class="bg-red-500 p-4 md:text-lg">
+    <EText class="m-0">Title</EText>
+    <EButton class="bg-blue-600 px-4 py-2" href="https://example.com">Open</EButton>
+  </div>
+</template>
+```
+
+```vue [email template]
+<ETailwind>
+  <EHtml lang="en">
+    <EHead />
+    <EBody>
+      <Card />
+    </EBody>
+  </EHtml>
+</ETailwind>
+```
+
+Style-bearing primitives such as `EText` and `EButton` resolve their Tailwind classes before their email-specific layout work. Plain HTML and structural components such as `EHtml` are handled in a second pass over the rendered HTML. That pass changes only marked class targets. Outlook-specific conditional comments and every other byte stay unchanged.
+
+Rules that cannot be inlined, such as `md:text-lg`, still reach the `<head>` style element. Rendering fails if those rules have no head inside the boundary.
+
+## Documented limitations
+
+<card title="Limitations" icon="lucide:alert-triangle">
+- `ECodeInline`, `EMarkdown`, `EPreview`, and `EFont` do **not** treat a nested `class` as a Tailwind style target — their `class`/head semantics differ.
+- Nested `<ETailwind>` boundaries are **not** a supported configuration.
+- Arbitrary CSS imports and CSS `@plugin` module imports are **not** resolved during rendering; executable plugins belong in `config`.
+- Responsive or pseudo-class padding on `EContainer`, `ESection`, or `ERow` remains a CSS rule on the table; use an inner `EColumn` when that padding must survive clients that force collapsed table borders.
+- Animation utilities include only the keyframes used by that render. Treat animation as best-effort progressive enhancement: [estimated email-client animation support is limited](https://www.caniemail.com/features/css-animation/), so the message must remain understandable when animation does not run.
+- CSS nesting is downleveled because [estimated native nesting support in email clients is low](https://www.caniemail.com/features/css-nesting/). No raw nesting is intentionally emitted.
+- Output tracks the fixed Tailwind version compiled by the engine.
+</card>
+
+Emails without `<ETailwind>` do not run the Tailwind path. The conformance cases cover basic inlining, media queries, Outlook-specific properties, nested components, and residual class sanitization. See the [conformance report](/raw/docs/reference/conformance.md).