npm - toiljs - Versions diffs - 0.0.45 → 0.0.46 - Mend

toiljs 0.0.45 → 0.0.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/CHANGELOG.md +9 -0
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +12 -2
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/email-preview.d.ts +12 -0
package/build/compiler/email-preview.js +253 -0
package/build/compiler/emails.d.ts +6 -3
package/build/compiler/emails.js +52 -12
package/build/compiler/index.js +14 -0
package/build/compiler/plugin.js +64 -2
package/build/compiler/vite.js +1 -0
package/docs/email.md +35 -19
package/package.json +2 -2
package/src/cli/create.ts +2 -2
package/src/cli/doctor.ts +15 -0
package/src/compiler/email-preview.ts +305 -0
package/src/compiler/emails.ts +82 -12
package/src/compiler/index.ts +19 -0
package/src/compiler/plugin.ts +88 -4
package/src/compiler/vite.ts +4 -0
package/test/email-preview.test.ts +68 -0
package/test/emails.test.ts +58 -0

package/build/compiler/email-preview.js ADDED Viewed

@@ -0,0 +1,253 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderEmailFile, toPascal } from './emails.js';
+export function emailsDir(cfg) {
+    return path.join(cfg.root, 'emails');
+}
+export function emailsVersion(cfg) {
+    let newest = 0;
+    let count = 0;
+    const CSS = /\.(css|scss|sass|less|styl|pcss|postcss)$/;
+    const walk = (dir, match) => {
+        let entries;
+        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 {
+                }
+            }
+        }
+    };
+    walk(emailsDir(cfg), /\.(tsx|jsx|css|scss|sass|less|styl|pcss|postcss)$/);
+    walk(cfg.clientAbsDir, CSS);
+    return `${String(newest)}:${String(count)}`;
+}
+export function listEmails(cfg) {
+    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),
+    }));
+}
+export async function renderEmailByName(server, cfg, name) {
+    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);
+}
+export function previewShellHtml() {
+    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/build/compiler/emails.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { type ViteDevServer } from 'vite';
 import type { ResolvedToilConfig } from './config.js';
 interface EmailModule {
     default: unknown;
@@ -5,7 +6,7 @@ interface EmailModule {
     text?: unknown;
     purpose?: unknown;
 }
-interface RenderedEmail {
+export interface RenderedEmail {
     name: string;
     subject: string;
     html: string;
@@ -15,8 +16,10 @@ interface RenderedEmail {
 }
 declare function tokenProps(seen: Set<string>): Record<string, unknown>;
 declare function htmlToText(html: string): string;
-declare function renderModule(name: string, mod: EmailModule, render: (el: unknown) => string): Promise<RenderedEmail | null>;
-declare function toPascal(base: string): string;
+declare function renderModule(name: string, mod: EmailModule, render: (el: unknown) => string, css?: string): Promise<RenderedEmail | null>;
+export declare function collectModuleCss(server: ViteDevServer, moduleId: string): Promise<string>;
+export declare function renderEmailFile(server: ViteDevServer, emailsDir: string, file: string, render: (el: unknown) => string): Promise<RenderedEmail | null>;
+export declare function toPascal(base: string): string;
 declare function renderModuleSource(rendered: RenderedEmail[]): string;
 export declare function renderEmails(cfg: ResolvedToilConfig): Promise<void>;
 export declare const __test: {

package/build/compiler/emails.js CHANGED Viewed

@@ -59,13 +59,13 @@ function htmlToText(html) {
         .replace(/[ \t]*\n[ \t]*/g, '\n')
         .trim();
 }
-async function renderModule(name, mod, render) {
+async function renderModule(name, mod, render, css = '') {
     if (typeof mod.default !== 'function')
         return null;
     const seen = new Set();
     const component = mod.default;
     let html = render(component(tokenProps(seen)));
-    html = await inlineCss(html);
+    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);
     const purpose = typeof mod.purpose === 'string' && mod.purpose.length > 0
@@ -81,7 +81,51 @@ async function renderModule(name, mod, render) {
     ].sort();
     return { name, subject, html, text, tokens, purpose };
 }
-function toPascal(base) {
+const CSS_RE = /\.(css|scss|sass|less|styl|pcss|postcss)(\?|$)/;
+export async function collectModuleCss(server, moduleId) {
+    const seen = new Set();
+    const cssIds = new Set();
+    const visit = (id) => {
+        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`));
+            if (typeof mod.default === 'string')
+                css += mod.default + '\n';
+        }
+        catch {
+        }
+    }
+    return css;
+}
+export async function renderEmailFile(server, emailsDir, file, render) {
+    const name = toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''));
+    const filePath = path.join(emailsDir, file);
+    const mod = (await server.ssrLoadModule(filePath));
+    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);
+}
+export function toPascal(base) {
     return base
         .split(/[-_\s.]+/)
         .filter(Boolean)
@@ -171,20 +215,16 @@ export async function renderEmails(cfg) {
     const rendered = [];
     try {
         for (const file of files) {
-            const name = toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, ''));
-            let mod;
             try {
-                mod = (await server.ssrLoadModule(path.join(emailsDir, file)));
+                const r = await renderEmailFile(server, emailsDir, file, renderToStaticMarkup);
+                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);
-            if (r)
-                rendered.push(r);
-            else
-                warn(`skipped ${file} (no default-exported component)`);
         }
     }
     finally {

package/build/compiler/index.js CHANGED Viewed

@@ -187,6 +187,18 @@ async function freeLoopbackPort() {
         });
     });
 }
+function printEmailsUrl(cfg, localUrl) {
+    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');
+}
 export async function dev(opts = {}) {
     const cfg = await loadConfig(opts);
     const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
@@ -201,6 +213,7 @@ export async function dev(opts = {}) {
         const server = await createServer(await createViteConfig(cfg));
         await server.listen();
         server.printUrls();
+        printEmailsUrl(cfg, server.resolvedUrls?.local?.[0]);
         return server;
     }
     const vitePort = await freeLoopbackPort();
@@ -228,6 +241,7 @@ export async function dev(opts = {}) {
         pc.cyan(`http://localhost:${pc.bold(String(front.port))}/`) +
         pc.dim('  (wasm server + vite)') +
         '\n');
+    printEmailsUrl(cfg, `http://localhost:${String(front.port)}/`);
     watchServer(cfg, server.watcher);
     return server;
 }

package/build/compiler/plugin.js CHANGED Viewed

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { version as viteVersion } from 'vite';
 import { AiProvider } from './config.js';
+import { emailsVersion, listEmails, previewShellHtml, renderEmailByName } from './email-preview.js';
 import { generate } from './generate.js';
 import { scanRoutes } from './routes.js';
 async function aiComplete(ai, prompt) {
@@ -191,7 +192,9 @@ export function toilPlugin(cfg) {
                     void (async () => {
                         try {
                             const parsed = JSON.parse(body || '{}');
-                            const prompt = typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                            const prompt = 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 }));
@@ -200,7 +203,9 @@ export function toilPlugin(cfg) {
                             process.stderr.write(`toil: /__toil/ai failed: ${e instanceof Error ? e.message : String(e)}\n`);
                             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).',
+                            }));
                         }
                     })();
                 });
@@ -247,6 +252,63 @@ export function toilPlugin(cfg) {
                     res.end();
                 }
             });
+            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) {
+                        process.stderr.write(`toil: /__toil/emails/render failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                })();
+            });
+            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());
+            });
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file) => {
                 if (file.replace(/\\/g, '/').startsWith(routesPrefix)) {

package/build/compiler/vite.js CHANGED Viewed

@@ -98,6 +98,7 @@ export async function createViteConfig(cfg) {
             alias: {
                 'toiljs/client': cfg.runtimePath,
                 'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
+                client: cfg.clientAbsDir,
                 ...polyfillShimAliases,
             },
             dedupe: ['react', 'react-dom'],

package/docs/email.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.45",
+    "version": "0.0.46",
     "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 CHANGED Viewed

@@ -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.