toiljs 0.0.45 → 0.0.46

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,305 @@
+/**
+ * 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>
+  :root { color-scheme: dark; }
+  * { 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: #0c0c11; color: #e7e9f0; }
+  #side { width: 240px; flex: 0 0 auto; border-right: 1px solid #23232e; display: flex; flex-direction: column; background: #101016; }
+  .brand { padding: 14px 16px; font-weight: 600; border-bottom: 1px solid #23232e; }
+  #list { list-style: none; margin: 0; padding: 6px; overflow: auto; flex: 1; }
+  #list li { padding: 8px 10px; border-radius: 8px; cursor: pointer; color: #c8cee0; }
+  #list li:hover { background: #181820; }
+  #list li.on { background: #1d1d6b33; color: #fff; }
+  #list li.muted { color: #6b7080; cursor: default; }
+  .hint { padding: 10px 16px; font-size: 12px; color: #6b7080; border-top: 1px solid #23232e; }
+  .hint code { color: #9aa1b8; }
+  #main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+  .empty { margin: auto; color: #6b7080; }
+  #view { display: flex; flex-direction: column; height: 100%; }
+  .bar { display: flex; align-items: center; gap: 14px; padding: 12px 16px; border-bottom: 1px solid #23232e; }
+  .subj { min-width: 0; flex: 1; display: flex; align-items: baseline; gap: 8px; }
+  .subj .lbl { font-size: 11px; text-transform: uppercase; letter-spacing: .04em; color: #6b7080; }
+  #subject { font-weight: 600; 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 #2c2c38; border-radius: 8px; overflow: hidden; }
+  .seg-btn { background: #15151c; border: 0; color: #8b90a4; font: inherit; padding: 6px 12px; cursor: pointer; }
+  .seg-btn.on { background: #2563ff; color: #fff; }
+  .btn { background: #15151c; border: 1px solid #2c2c38; color: #c8cee0; font: inherit; padding: 6px 12px; border-radius: 8px; cursor: pointer; }
+  .btn:hover { color: #fff; border-color: #3a3a48; }
+  .body { display: flex; flex: 1; min-height: 0; }
+  .tokens { width: 240px; flex: 0 0 auto; border-right: 1px solid #23232e; padding: 12px; overflow: auto; }
+  .field { display: flex; flex-direction: column; gap: 4px; margin-bottom: 12px; }
+  .fname { font-size: 12px; color: #9aa1b8; }
+  .field input { background: #0c0c11; border: 1px solid #2c2c38; border-radius: 6px; color: #e7e9f0; font: inherit; padding: 6px 8px; }
+  .field input:focus { outline: none; border-color: #2563ff; }
+  .muted { color: #6b7080; font-size: 12px; }
+  .preview { flex: 1; min-width: 0; background: #f6f7f9; }
+  #frame { width: 100%; height: 100%; border: 0; background: #fff; }
+  #text { width: 100%; height: 100%; margin: 0; padding: 16px; overflow: auto; background: #0c0c11; color: #c8cee0; white-space: pre-wrap; }
+</style>
+</head>
+<body>
+<aside id="side">
+  <div class="brand">✉ 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,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { createServer } from 'vite';
+import { createServer, type ViteDevServer } from 'vite';
 
 import type { ResolvedToilConfig } from './config.js';
 import { createViteConfig } from './vite.js';
@@ -38,7 +38,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 +132,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 +165,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 +289,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 +343,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();

package/src/compiler/index.ts

@@ -268,6 +268,23 @@ export interface ToilCommandOptions {
     readonly serverOnly?: boolean;
 }
 
+/** Prints the email-preview URL under the dev banner, when the project has an
+ *  `emails/` folder. `localUrl` is the resolved base (ends in `/`); skipped if
+ *  the server didn't report one. */
+function printEmailsUrl(cfg: ResolvedToilConfig, localUrl: string | undefined): void {
+    if (!localUrl || !fs.existsSync(path.join(cfg.root, 'emails'))) return;
+    process.stdout.write(
+        '  ' +
+            pc.green('✉') +
+            '  ' +
+            pc.bold('Emails') +
+            ':  ' +
+            pc.cyan(`${localUrl}__toil/emails`) +
+            pc.dim('  (preview)') +
+            '\n',
+    );
+}
+
 /**
  * Starts the dev server. Client-only projects get the plain Vite dev server on
  * the configured port, unchanged. Projects with a server target
@@ -293,6 +310,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
         const server = await createServer(await createViteConfig(cfg));
         await server.listen();
         server.printUrls();
+        printEmailsUrl(cfg, server.resolvedUrls?.local?.[0]);
         return server;
     }
 
@@ -325,6 +343,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
             pc.dim('  (wasm server + vite)') +
             '\n',
     );
+    printEmailsUrl(cfg, `http://localhost:${String(front.port)}/`);
 
     // Rebuild the server on server-file changes; Vite HMRs the regenerated shared/server.ts
     // and the dev server hot-swaps the recompiled wasm module.

package/src/compiler/plugin.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { type Plugin, version as viteVersion } from 'vite';
 
 import { AiProvider, type DevtoolsAiConfig, type ResolvedToilConfig } from './config.js';
+import { emailsVersion, listEmails, previewShellHtml, renderEmailByName } from './email-preview.js';
 import { generate } from './generate.js';
 import { scanRoutes } from './routes.js';
 
@@ -58,7 +59,9 @@ async function aiComplete(ai: DevtoolsAiConfig, prompt: string): Promise<string>
 /** Reads a package's version resolved from `<fromDir>`, or 'unknown'. */
 function depVersion(fromDir: string, name: string): string {
     try {
-        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(`${name}/package.json`);
+        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(
+            `${name}/package.json`,
+        );
         const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
         return raw.version ?? 'unknown';
     } catch {
@@ -69,7 +72,12 @@ function depVersion(fromDir: string, name: string): string {
 /** toiljs's own version (package.json two levels up from build/compiler). */
 function frameworkVersion(): string {
     try {
-        const p = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const p = path.resolve(
+            path.dirname(fileURLToPath(import.meta.url)),
+            '..',
+            '..',
+            'package.json',
+        );
         const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as { version?: string };
         return raw.version ?? '0.0.0';
     } catch {
@@ -231,7 +239,9 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             const parsed = JSON.parse(body || '{}') as { prompt?: string };
                             // Cap the prompt actually forwarded upstream (independent of the raw-body cap).
                             const prompt =
-                                typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                                typeof parsed.prompt === 'string'
+                                    ? parsed.prompt.slice(0, 16000)
+                                    : '';
                             const text = await aiComplete(ai, prompt);
                             res.setHeader('content-type', 'application/json');
                             res.end(JSON.stringify({ text }));
@@ -243,7 +253,11 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             );
                             res.statusCode = 500;
                             res.setHeader('content-type', 'application/json');
-                            res.end(JSON.stringify({ error: 'AI request failed (see dev server logs).' }));
+                            res.end(
+                                JSON.stringify({
+                                    error: 'AI request failed (see dev server logs).',
+                                }),
+                            );
                         }
                     })();
                 });
@@ -291,6 +305,76 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                 }
             });
 
+            // Email preview tool (dev only). `/__toil/emails` -> a standalone page that lists
+            // `emails/*.tsx`, renders the selected one through the live SSR server (so edits and
+            // imported `client/*` CSS show), and live-refreshes by polling `/version`.
+            // Sub-paths are registered before the page so connect's prefix match resolves them first.
+            server.middlewares.use('/__toil/emails/list', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(listEmails(cfg)));
+            });
+            server.middlewares.use('/__toil/emails/render', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                void (async () => {
+                    try {
+                        const name = new URL(req.url ?? '', 'http://localhost').searchParams.get(
+                            'name',
+                        );
+                        if (!name) {
+                            res.statusCode = 400;
+                            res.end();
+                            return;
+                        }
+                        const rendered = await renderEmailByName(server, cfg, name);
+                        if (!rendered) {
+                            res.statusCode = 404;
+                            res.end();
+                            return;
+                        }
+                        res.setHeader('content-type', 'application/json');
+                        res.end(JSON.stringify(rendered));
+                    } catch (e) {
+                        // Log the detail to the dev's terminal; the page shows a generic message.
+                        process.stderr.write(
+                            `toil: /__toil/emails/render failed: ${e instanceof Error ? e.message : String(e)}\n`,
+                        );
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                })();
+            });
+            // A tiny mtime fingerprint of `emails/*` + client CSS the page polls (~1s) to detect
+            // edits. Polling (not SSE) because the wasm dev server proxies `/__toil/*` to Vite by
+            // buffering the whole response, so a long-lived stream would hang; a short poll works
+            // in every mode.
+            server.middlewares.use('/__toil/emails/version', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                res.end(emailsVersion(cfg));
+            });
+            server.middlewares.use('/__toil/emails', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/html; charset=utf-8');
+                res.end(previewShellHtml());
+            });
+
             // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file: string): void => {

package/src/compiler/vite.ts

@@ -154,6 +154,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
             alias: {
                 'toiljs/client': cfg.runtimePath,
                 'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
+                // `client/*` -> the project's client source dir, so anything (pages, and notably
+                // `emails/*.tsx`) can reuse existing client assets, e.g. `import 'client/styles/x.css'`.
+                // Vite's string alias matches only `client` or `client/...`, never `toiljs/client`.
+                client: cfg.clientAbsDir,
                 // `shared/*` is resolved by sharedResolverPlugin (above) so a missing generated
                 // shared/server.ts gives an actionable error instead of an opaque load failure.
                 ...polyfillShimAliases,