toiljs 0.0.45 → 0.0.47

package/docs/email.md

@@ -109,6 +109,7 @@ export default defineConfig({
     },
 });
 ```
+
 ```bash
 # .env.secrets  (gitignored)
 TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx
@@ -137,8 +138,8 @@ class Notify {
         const status = EmailService.send(
             'alice@example.com',
             'Welcome!',
-            'Thanks for signing up.',   // plain-text body
-            'welcome',                  // purpose tag (dedup / abuse keying)
+            'Thanks for signing up.', // plain-text body
+            'welcome', // purpose tag (dedup / abuse keying)
             '<h1>Thanks for signing up.</h1>', // optional HTML body
         );
         return status == EmailStatus.Sent
@@ -150,16 +151,16 @@ class Notify {
 
 `send(to, subject, body, purpose = 'tx', html = '')` returns an **`EmailStatus`**:
 
-| Status | Meaning | Retry? |
-| --- | --- | --- |
-| `Sent` | Accepted by the provider | — |
-| `Deduped` | An identical recent `(recipient, purpose)` was collapsed | treat as sent |
-| `Budget` | The host's per-minute budget is exhausted | yes, later |
-| `TryLater` | The mailer was saturated / a queue was full | yes, back off |
-| `RecipientCapped` | The per-recipient hourly cap was hit | no (this window) |
-| `BadRecipient` | The address failed validation (CRLF, multiple addresses) | no |
-| `Disabled` | This host has no `[email]` capability | no |
-| `ProviderError` | The provider rejected it, or transport failed after retries | no |
+| Status            | Meaning                                                     | Retry?           |
+| ----------------- | ----------------------------------------------------------- | ---------------- |
+| `Sent`            | Accepted by the provider                                    | —                |
+| `Deduped`         | An identical recent `(recipient, purpose)` was collapsed    | treat as sent    |
+| `Budget`          | The host's per-minute budget is exhausted                   | yes, later       |
+| `TryLater`        | The mailer was saturated / a queue was full                 | yes, back off    |
+| `RecipientCapped` | The per-recipient hourly cap was hit                        | no (this window) |
+| `BadRecipient`    | The address failed validation (CRLF, multiple addresses)    | no               |
+| `Disabled`        | This host has no `[email]` capability                       | no               |
+| `ProviderError`   | The provider rejected it, or transport failed after retries | no               |
 
 `purpose` is a short, non-PII tag (`"welcome"`, `"reset"`, …). The mailer folds
 it into the **dedup** key (identical `(host, recipient, purpose)` within ~30s is
@@ -175,8 +176,8 @@ when the same email is sent with different values:
 
 ```ts
 const welcome = new EmailTemplate(
-    'Welcome, {{name}}!',                                  // subject
-    'Hi {{name}}, your code is {{code}}.',                 // plain-text body
+    'Welcome, {{name}}!', // subject
+    'Hi {{name}}, your code is {{code}}.', // plain-text body
     '<h1>Welcome, {{name}}</h1><p>Code: <b>{{code}}</b></p>', // html (optional)
 );
 
@@ -208,12 +209,16 @@ export const subject = 'Welcome, {{name}}!';
 
 export default function Welcome({ name, code }: { name: string; code: string }) {
     return (
-        <table width="100%" style={{ fontFamily: 'Arial, sans-serif' }}>
+        <table
+            width="100%"
+            style={{ fontFamily: 'Arial, sans-serif' }}>
             <tbody>
                 <tr>
                     <td style={{ padding: '24px' }}>
                         <h1 style={{ color: '#111' }}>Welcome, {name}!</h1>
-                        <p>Your code is <b>{code}</b>.</p>
+                        <p>
+                            Your code is <b>{code}</b>.
+                        </p>
                     </td>
                 </tr>
             </tbody>
@@ -232,9 +237,12 @@ const status = Emails.Welcome.send('alice@example.com', '123456', 'Alice');
 
 Authoring notes:
 
-- **Use inline `style={{ ... }}`.** Email clients strip `<style>`/external CSS;
-  inline styles render everywhere. A CSS file imported into the component is
-  inlined for you at build (via `juice`).
+- **Styles must end up inline.** Email clients strip `<style>`/external CSS, so
+  write inline `style={{ ... }}`, or import a stylesheet and its rules are
+  inlined into element `style="…"` for you at build (a bare CSS import has no
+  effect on its own under SSR). Keep email-only styles next to the email, e.g.
+  `import './styles/email.css'`, or **reuse existing project CSS** with `import
+'client/styles/…'` (the `client/*` alias points at your client source).
 - **Optional exports:** `export const subject` (a token template; defaults to the
   email name), `export const text` (a plain-text alternative; otherwise derived
   from the HTML), `export const purpose`.
@@ -246,6 +254,14 @@ Authoring notes:
 - The generated `server/_emails.ts` is regenerated on `build`/`dev` and should be
   gitignored.
 
+### Preview while you author
+
+While `toiljs dev` runs, open **`/__toil/emails`** (the dev banner prints the
+link). It lists every `emails/*.tsx`, renders the selected one exactly as the
+build does (imported `client/*` CSS inlined), lets you fill each `{{token}}` to
+see the result, toggle the HTML and plain-text parts, and open the file in your
+editor. It refreshes live as you edit the template or its CSS.
+
 ## Email verification codes (`TwoFactor`)
 
 `TwoFactor` is a **stateless** email-code primitive (2FA, email confirmation,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.45",
+    "version": "0.0.47",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -153,7 +153,7 @@
         "@btc-vision/as-pect-cli": "^8.3.0",
         "@btc-vision/as-pect-transform": "^8.3.0",
         "@clack/prompts": "^1.5.0",
-        "@microsoft/api-extractor": "7.58.8",
+        "@microsoft/api-extractor": "7.58.9",
         "@testing-library/dom": "^10.4.1",
         "@testing-library/react": "^16.3.2",
         "@types/node": "^25.9.1",

package/src/cli/create.ts

@@ -156,14 +156,14 @@ function scaffold(
             '    "compilerOptions": {\n' +
             '        "paths": { "shared/*": ["./shared/*"] }\n' +
             '    },\n' +
-            '    "include": ["client", "shared", "toil-env.d.ts", "toil-routes.d.ts"]\n' +
+            '    "include": ["client", "shared", "emails", "toil.config.ts", "toil-env.d.ts", "toil-routes.d.ts"]\n' +
             '}\n',
         'eslint.config.js': "import toiljs from 'toiljs/eslint';\n\nexport default toiljs;\n",
         '.prettierrc': '"toiljs/prettier"\n',
         // Generated files don't need formatting. (toilscript server decorators like @main /
         // @remote-on-functions are handled by the toiljs/prettier-plugin, so server/ is not ignored.)
         '.prettierignore':
-            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n',
+            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/toil-server-env.d.ts\n',
         '.gitignore':
             'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n',
         // Use the project's pinned TypeScript (node_modules) instead of VS Code's bundled version.

package/src/cli/doctor.ts

@@ -296,9 +296,24 @@ function applyRpcFix(root: string): RpcFixResult {
         // and synthesizing one would narrow what TypeScript sees.
         if (Array.isArray(tsconfig.include)) {
             const include = [...(tsconfig.include as unknown[])];
+            let changedInclude = false;
+            // `shared` (the @data/@remote RPC alias target) right after `client`.
             if (!include.includes('shared')) {
                 const at = include.indexOf('client');
                 include.splice(at >= 0 ? at + 1 : include.length, 0, 'shared');
+                changedInclude = true;
+            }
+            // `emails` (the React email-template pipeline) + `toil.config.ts`, so the
+            // typescript-eslint project service / editor cover them — otherwise
+            // `emails/*.tsx` (and a typed `toil.config.ts`) raise "not found by the
+            // project service". Harmless when absent (a non-matching glob).
+            for (const entry of ['emails', 'toil.config.ts']) {
+                if (!include.includes(entry)) {
+                    include.push(entry);
+                    changedInclude = true;
+                }
+            }
+            if (changedInclude) {
                 tsconfig.include = include;
                 touched = true;
             }

package/src/compiler/email-preview.ts

@@ -0,0 +1,312 @@
+/**
+ * Dev-only email preview tool. Backs the `/__toil/emails*` endpoints (wired in
+ * `plugin.ts`): a standalone page that lists `emails/*.tsx`, renders the selected
+ * one through the live Vite SSR server (so edits and imported `client/*` CSS show
+ * up), and fills `{{token}}` holes from inputs the same way the edge does at send
+ * time. Build-path parity comes from sharing `renderEmailFile` with the codegen
+ * pass (`emails.ts`), so what you preview is what gets baked into `server/_emails.ts`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { ViteDevServer } from 'vite';
+
+import type { ResolvedToilConfig } from './config.js';
+import { renderEmailFile, toPascal, type RenderedEmail } from './emails.js';
+
+/** One discoverable email: its generated `Emails.<name>` and its absolute file. */
+export interface EmailListItem {
+    name: string;
+    /** Absolute path, used for "open in editor" (`/__toil/open?file=`). */
+    file: string;
+}
+
+/** The `emails/` dir for a project (sibling of `client/` and `server/`). */
+export function emailsDir(cfg: ResolvedToilConfig): string {
+    return path.join(cfg.root, 'emails');
+}
+
+/**
+ * A cheap change fingerprint (`<newestMtime>:<fileCount>`) over `emails/*.tsx|jsx`
+ * and the project's client CSS, polled by the preview page to detect edits (any
+ * save bumps an mtime to ~now; add/remove changes the count). Stat-only, so it is
+ * fine to poll ~1/s. Used instead of a long-lived stream, which the buffering wasm
+ * dev proxy can't forward.
+ */
+export function emailsVersion(cfg: ResolvedToilConfig): string {
+    let newest = 0;
+    let count = 0;
+    const CSS = /\.(css|scss|sass|less|styl|pcss|postcss)$/;
+    const walk = (dir: string, match: RegExp): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name !== 'node_modules') walk(full, match);
+            } else if (match.test(e.name)) {
+                try {
+                    const m = fs.statSync(full).mtimeMs;
+                    if (m > newest) newest = m;
+                    count++;
+                } catch {
+                    // file vanished between readdir and stat; ignore
+                }
+            }
+        }
+    };
+    // Email templates and any styles beside them (emails/styles/*), plus client
+    // CSS in case an email reuses `client/styles/*`.
+    walk(emailsDir(cfg), /\.(tsx|jsx|css|scss|sass|less|styl|pcss|postcss)$/);
+    walk(cfg.clientAbsDir, CSS);
+    return `${String(newest)}:${String(count)}`;
+}
+
+/** List `emails/*.tsx|jsx`, mapped to their generated names. Cheap (no render). */
+export function listEmails(cfg: ResolvedToilConfig): EmailListItem[] {
+    const dir = emailsDir(cfg);
+    if (!fs.existsSync(dir)) return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => /\.(tsx|jsx)$/.test(f))
+        .sort()
+        .map((f) => ({
+            name: toPascal(path.basename(f).replace(/\.(tsx|jsx)$/, '')),
+            file: path.join(dir, f),
+        }));
+}
+
+/**
+ * Render the email whose generated name is `name` through the live SSR server,
+ * or `null` if there is no such file. Drops the module from the SSR cache first
+ * so an edit is reflected on every request (the watcher also invalidates on save;
+ * this makes a manual refresh fresh too).
+ */
+export async function renderEmailByName(
+    server: ViteDevServer,
+    cfg: ResolvedToilConfig,
+    name: string,
+): Promise<RenderedEmail | null> {
+    const item = listEmails(cfg).find((e) => e.name === name);
+    if (!item) return null;
+    const node =
+        server.moduleGraph.getModuleById(item.file) ??
+        (await server.moduleGraph.getModuleByUrl(item.file));
+    if (node) server.moduleGraph.invalidateModule(node);
+    const { renderToStaticMarkup } = await import('react-dom/server');
+    return renderEmailFile(
+        server,
+        emailsDir(cfg),
+        path.basename(item.file),
+        renderToStaticMarkup as (el: unknown) => string,
+    );
+}
+
+/**
+ * The self-contained preview page (served at `/__toil/emails`). Plain HTML + a
+ * tiny inline script -- no client-runtime dependency, so it works in both the
+ * client-only and wasm-server dev modes. Token substitution happens here in the
+ * browser (`{{token}}` -> input value), so typing is instant and the iframe shows
+ * exactly the edge's hole-fill path.
+ */
+export function previewShellHtml(): string {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Email preview · toiljs</title>
+<style>
+  /* Matches the toiljs demo brand (examples/basic/client/styles/main.css). */
+  :root {
+    color-scheme: dark;
+    --bg: #080d11; --surface: #0e1520; --surface2: #131d2e; --border: #1b2330;
+    --text: #f5f6fa; --muted: #8b9ab4; --accent: #2563ff; --accent3: #22e3ab;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; height: 100vh; display: flex; font: 14px/1.5 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); }
+  #side { width: 248px; flex: 0 0 auto; border-right: 1px solid var(--border); display: flex; flex-direction: column; background: var(--surface); }
+  .brand { display: flex; align-items: center; gap: 10px; padding: 15px 16px; font-family: 'Montserrat', system-ui, sans-serif; font-weight: 800; font-size: 15px; letter-spacing: -0.01em; border-bottom: 1px solid var(--border); }
+  .brand .mark { width: 26px; height: 26px; flex: 0 0 auto; border-radius: 7px; display: flex; align-items: center; justify-content: center; color: #fff; font-size: 13px; background: linear-gradient(135deg, var(--accent), #7c3aed 55%, var(--accent3)); }
+  #list { list-style: none; margin: 0; padding: 8px; overflow: auto; flex: 1; }
+  #list li { padding: 8px 11px; border-radius: 8px; cursor: pointer; color: var(--muted); transition: background 150ms, color 150ms; }
+  #list li:hover { background: rgba(255,255,255,0.04); color: var(--text); }
+  #list li.on { background: rgba(37,99,255,0.14); color: #fff; box-shadow: inset 2px 0 0 var(--accent); }
+  #list li.muted, #list li.muted:hover { color: #5d6a82; cursor: default; background: none; }
+  .hint { padding: 12px 16px; font-size: 12px; color: #5d6a82; border-top: 1px solid var(--border); }
+  .hint code { color: var(--muted); }
+  #main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+  .empty { margin: auto; color: #5d6a82; }
+  #view { display: flex; flex-direction: column; height: 100%; }
+  .bar { display: flex; align-items: center; gap: 14px; padding: 14px 18px; border-bottom: 1px solid var(--border); }
+  .subj { min-width: 0; flex: 1; display: flex; align-items: baseline; gap: 9px; }
+  .subj .lbl { font-size: 10px; text-transform: uppercase; letter-spacing: .08em; color: #5d6a82; }
+  #subject { font-weight: 600; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .actions { display: flex; align-items: center; gap: 8px; flex: 0 0 auto; }
+  .seg { display: flex; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+  .seg-btn { background: var(--surface); border: 0; color: var(--muted); font: inherit; padding: 6px 14px; cursor: pointer; transition: color 150ms; }
+  .seg-btn:hover { color: var(--text); }
+  .seg-btn.on { background: var(--accent); color: #fff; }
+  .btn { background: var(--surface); border: 1px solid var(--border); color: var(--text); font: inherit; padding: 6px 13px; border-radius: 8px; cursor: pointer; transition: border-color 150ms, background 150ms; }
+  .btn:hover { border-color: var(--accent); background: var(--surface2); }
+  .body { display: flex; flex: 1; min-height: 0; }
+  .tokens { width: 248px; flex: 0 0 auto; border-right: 1px solid var(--border); padding: 14px; overflow: auto; }
+  .field { display: flex; flex-direction: column; gap: 5px; margin-bottom: 13px; }
+  .fname { font-size: 12px; color: var(--muted); }
+  .field input { background: var(--bg); border: 1px solid var(--border); border-radius: 7px; color: var(--text); font: inherit; padding: 7px 9px; }
+  .field input:focus { outline: none; border-color: var(--accent); }
+  .muted { color: #5d6a82; font-size: 12px; }
+  .preview { flex: 1; min-width: 0; display: flex; background: var(--bg); padding: 18px; }
+  #frame { flex: 1; width: 100%; border: 1px solid var(--border); border-radius: 12px; background: var(--bg); }
+  #text { flex: 1; width: 100%; margin: 0; padding: 18px; overflow: auto; background: var(--surface); color: var(--muted); white-space: pre-wrap; border: 1px solid var(--border); border-radius: 12px; font: 13px/1.6 'SFMono-Regular', Consolas, monospace; }
+</style>
+</head>
+<body>
+<aside id="side">
+  <div class="brand"><span class="mark">✦</span>Emails</div>
+  <ul id="list"></ul>
+  <div class="hint">Author in <code>emails/*.tsx</code>; this updates live on save.</div>
+</aside>
+<main id="main">
+  <div id="empty" class="empty">Select an email to preview.</div>
+  <section id="view" hidden>
+    <header class="bar">
+      <div class="subj"><span class="lbl">Subject</span><span id="subject"></span></div>
+      <div class="actions">
+        <div class="seg"><button id="tab-html" class="seg-btn on">HTML</button><button id="tab-text" class="seg-btn">Text</button></div>
+        <button id="open" class="btn">Open in editor</button>
+      </div>
+    </header>
+    <div class="body">
+      <div class="tokens" id="tokens"></div>
+      <div class="preview"><iframe id="frame" title="email preview"></iframe><pre id="text" hidden></pre></div>
+    </div>
+  </section>
+</main>
+<script>
+(function () {
+  var BASE = '/__toil/emails';
+  var listEl = document.getElementById('list');
+  var subjectEl = document.getElementById('subject');
+  var frame = document.getElementById('frame');
+  var textEl = document.getElementById('text');
+  var tokensEl = document.getElementById('tokens');
+  var emptyEl = document.getElementById('empty');
+  var viewEl = document.getElementById('view');
+  var tabHtml = document.getElementById('tab-html');
+  var tabText = document.getElementById('tab-text');
+  var openBtn = document.getElementById('open');
+  var current = null, rendered = null, format = 'html', values = {};
+
+  function fill(s) {
+    return String(s).replace(/\\{\\{\\s*([A-Za-z_$][\\w$]*)\\s*\\}\\}/g, function (m, k) {
+      return Object.prototype.hasOwnProperty.call(values, k) ? values[k] : m;
+    });
+  }
+  function paint() {
+    if (!rendered) return;
+    subjectEl.textContent = fill(rendered.subject);
+    if (format === 'html') {
+      frame.hidden = false; textEl.hidden = true;
+      frame.srcdoc = fill(rendered.html);
+    } else {
+      frame.hidden = true; textEl.hidden = false;
+      textEl.textContent = fill(rendered.text);
+    }
+  }
+  function paintTokens() {
+    tokensEl.textContent = '';
+    if (!rendered.tokens.length) {
+      var none = document.createElement('div');
+      none.className = 'muted'; none.textContent = 'No {{tokens}} in this email.';
+      tokensEl.appendChild(none); return;
+    }
+    rendered.tokens.forEach(function (t) {
+      var row = document.createElement('label'); row.className = 'field';
+      var span = document.createElement('span'); span.className = 'fname'; span.textContent = t;
+      var inp = document.createElement('input');
+      inp.value = values[t] != null ? values[t] : t;
+      values[t] = inp.value;
+      inp.addEventListener('input', function () { values[t] = inp.value; paint(); });
+      row.appendChild(span); row.appendChild(inp); tokensEl.appendChild(row);
+    });
+  }
+  function setFormat(f) {
+    format = f;
+    tabHtml.classList.toggle('on', f === 'html');
+    tabText.classList.toggle('on', f === 'text');
+    paint();
+  }
+  tabHtml.addEventListener('click', function () { setFormat('html'); });
+  tabText.addEventListener('click', function () { setFormat('text'); });
+  openBtn.addEventListener('click', function () {
+    if (current) fetch('/__toil/open?file=' + encodeURIComponent(current.file)).catch(function () {});
+  });
+
+  function select(item, keep) {
+    current = item;
+    Array.prototype.forEach.call(listEl.children, function (li) {
+      li.classList.toggle('on', li.getAttribute('data-name') === item.name);
+    });
+    fetch(BASE + '/render?name=' + encodeURIComponent(item.name)).then(function (r) {
+      if (!r.ok) throw new Error('render failed');
+      return r.json();
+    }).then(function (data) {
+      rendered = data;
+      if (!keep) values = {};
+      emptyEl.hidden = true; viewEl.hidden = false;
+      paintTokens(); paint();
+    }).catch(function () {
+      emptyEl.hidden = false; viewEl.hidden = true;
+      emptyEl.textContent = 'Could not render ' + item.name + ' (see dev server logs).';
+    });
+  }
+  function buildList(items) {
+    listEl.textContent = '';
+    if (!items.length) {
+      var li = document.createElement('li');
+      li.className = 'muted'; li.textContent = 'No emails/*.tsx found.';
+      listEl.appendChild(li); return;
+    }
+    items.forEach(function (it) {
+      var li = document.createElement('li');
+      li.setAttribute('data-name', it.name);
+      li.textContent = it.name;
+      li.classList.toggle('on', !!current && it.name === current.name);
+      li.addEventListener('click', function () { select(it, false); });
+      listEl.appendChild(li);
+    });
+  }
+  function refresh() {
+    fetch(BASE + '/list').then(function (r) { return r.json(); }).then(function (items) {
+      buildList(items);
+      if (!items.length) {
+        current = null; rendered = null;
+        emptyEl.hidden = false; viewEl.hidden = true;
+        emptyEl.textContent = 'No emails/*.tsx found.';
+        return;
+      }
+      var match = current && items.filter(function (it) { return it.name === current.name; })[0];
+      select(match || items[0], !!match);
+    }).catch(function () {});
+  }
+  refresh();
+  // Live refresh: poll a cheap mtime fingerprint; re-render when it changes.
+  var version = null;
+  setInterval(function () {
+    fetch(BASE + '/version').then(function (r) { return r.text(); }).then(function (v) {
+      if (version === null) { version = v; return; }
+      if (v !== version) { version = v; refresh(); }
+    }).catch(function () {});
+  }, 1000);
+})();
+</script>
+</body>
+</html>
+`;
+}

package/src/compiler/emails.ts

@@ -21,7 +21,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { createServer } from 'vite';
+import pc from 'picocolors';
+import { createServer, type ViteDevServer } from 'vite';
 
 import type { ResolvedToilConfig } from './config.js';
 import { createViteConfig } from './vite.js';
@@ -38,7 +39,7 @@ interface EmailModule {
 }
 
 /** One email rendered to its baked, token-holed parts. */
-interface RenderedEmail {
+export interface RenderedEmail {
     name: string;
     subject: string;
     html: string;
@@ -132,13 +133,17 @@ async function renderModule(
     name: string,
     mod: EmailModule,
     render: (el: unknown) => string,
+    css = '',
 ): Promise<RenderedEmail | null> {
     if (typeof mod.default !== 'function') return null;
 
     const seen = new Set<string>();
     const component = mod.default as (props: unknown) => unknown;
     let html = render(component(tokenProps(seen)));
-    html = await inlineCss(html);
+    // CSS the component imported (e.g. `import 'client/styles/email.css'`) is
+    // prepended as a <style> block so it gets inlined into element style="" like
+    // an inline block would -- under SSR a bare CSS import otherwise has no effect.
+    html = await inlineCss(css ? `<style>${css}</style>${html}` : html);
 
     const subject = typeof mod.subject === 'string' ? mod.subject : name;
     const text = typeof mod.text === 'string' ? mod.text : htmlToText(html);
@@ -161,8 +166,71 @@ async function renderModule(
     return { name, subject, html, text, tokens, purpose };
 }
 
+const CSS_RE = /\.(css|scss|sass|less|styl|pcss|postcss)(\?|$)/;
+
+/**
+ * Collect the CSS an email module transitively imports, as one string. Under SSR
+ * a bare `import 'client/styles/email.css'` produces no output, so we walk the
+ * Vite module graph from the email module, collect its CSS deps, and re-import
+ * each with `?inline` (Vite then returns the processed CSS as the default export,
+ * Tailwind/PostCSS included). The caller hands the result to `renderModule`,
+ * which inlines it into the HTML. Best-effort: a CSS dep that can't be inlined is
+ * skipped (the component's inline `style={{}}` props still render).
+ */
+export async function collectModuleCss(server: ViteDevServer, moduleId: string): Promise<string> {
+    const seen = new Set<string>();
+    const cssIds = new Set<string>();
+    const visit = (id: string): void => {
+        if (seen.has(id)) return;
+        seen.add(id);
+        const mod = server.moduleGraph.getModuleById(id);
+        if (!mod) return;
+        for (const dep of mod.importedModules) {
+            const depId = dep.id ?? dep.url;
+            if (!depId) continue;
+            if (CSS_RE.test(depId)) cssIds.add(depId);
+            else visit(depId);
+        }
+    };
+    visit(moduleId);
+
+    let css = '';
+    for (const id of cssIds) {
+        const base = id.split('?')[0] ?? id;
+        try {
+            const mod = (await server.ssrLoadModule(`${base}?inline`)) as { default?: unknown };
+            if (typeof mod.default === 'string') css += mod.default + '\n';
+        } catch {
+            // skip a CSS dep we can't inline
+        }
+    }
+    return css;
+}
+
+/**
+ * Load one `emails/*.tsx` through `server` (SSR), collect any CSS it imports, and
+ * render it to its baked, token-holed parts. Shared by the build/codegen pass and
+ * the dev preview tool so both produce byte-identical output. Throws if the module
+ * fails to load; returns `null` if it has no default-exported component.
+ */
+export async function renderEmailFile(
+    server: ViteDevServer,
+    emailsDir: string,
+    file: string,
+    render: (el: unknown) => string,
+): Promise<RenderedEmail | null> {
+    const name = toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''));
+    const filePath = path.join(emailsDir, file);
+    const mod = (await server.ssrLoadModule(filePath)) as EmailModule;
+    const node =
+        server.moduleGraph.getModuleById(filePath) ??
+        (await server.moduleGraph.getModuleByUrl(filePath));
+    const css = node?.id ? await collectModuleCss(server, node.id) : '';
+    return renderModule(name, mod, render, css);
+}
+
 /** `welcome-email` / `welcome_email` -> `WelcomeEmail`. */
-function toPascal(base: string): string {
+export function toPascal(base: string): string {
     return base
         .split(/[-_\s.]+/)
         .filter(Boolean)
@@ -222,7 +290,9 @@ function renderModuleSource(rendered: RenderedEmail[]): string {
             .concat(params.map((p) => `${p.param}: string`))
             .concat(`purpose: string = ${asLit(e.purpose)}`)
             .join(', ');
-        out.push(`    /** Render and send this email to \`to\`. Returns the send's EmailStatus. */`);
+        out.push(
+            `    /** Render and send this email to \`to\`. Returns the send's EmailStatus. */`,
+        );
         out.push(`    export function send(${sig}): EmailStatus {`);
         out.push(`      const __v = new Map<string, string>();`);
         for (const p of params) out.push(`      __v.set(${asLit(p.token)}, ${p.param});`);
@@ -274,17 +344,18 @@ export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
     const rendered: RenderedEmail[] = [];
     try {
         for (const file of files) {
-            const name = toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''));
-            let mod: EmailModule;
             try {
-                mod = (await server.ssrLoadModule(path.join(emailsDir, file))) as EmailModule;
+                const r = await renderEmailFile(
+                    server,
+                    emailsDir,
+                    file,
+                    renderToStaticMarkup as (el: unknown) => string,
+                );
+                if (r) rendered.push(r);
+                else warn(`skipped ${file} (no default-exported component)`);
             } catch (err) {
                 warn(`skipped ${file} (${err instanceof Error ? err.message : String(err)})`);
-                continue;
             }
-            const r = await renderModule(name, mod, renderToStaticMarkup as (el: unknown) => string);
-            if (r) rendered.push(r);
-            else warn(`skipped ${file} (no default-exported component)`);
         }
     } finally {
         await server.close();
@@ -301,9 +372,13 @@ export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
     fs.mkdirSync(path.dirname(generatedPath), { recursive: true });
     fs.writeFileSync(generatedPath, next);
     process.stdout.write(
-        `  ✓ emails: generated ${String(rendered.length)} template${rendered.length === 1 ? '' : 's'} (${rendered
-            .map((r) => r.name)
-            .join(', ')})\n`,
+        pc.green('  ✓ ') +
+            pc.dim(
+                `emails: generated ${String(rendered.length)} template${rendered.length === 1 ? '' : 's'} (${rendered
+                    .map((r) => r.name)
+                    .join(', ')})`,
+            ) +
+            '\n',
     );
 }