@stacksjs/email 0.70.88 → 0.70.91

package/dist/mailable.d.ts

@@ -0,0 +1,116 @@
+import type { EmailAddress, EmailAttachment, EmailResult } from '@stacksjs/types';
+/**
+ * Options accepted by {@link Mailable.send} — currently allows scoping
+ * the send to a specific driver registered on the Mail singleton (e.g.
+ * `'log'` to swallow the email in a test, `'ses'` to force production
+ * delivery during a one-off backfill).
+ */
+export declare interface MailableSendOptions {
+  driver?: string
+}
+/**
+ * Internal stash for template rendering — populated by {@link Mailable.template}
+ * and consumed in {@link Mailable.send} after `build()` resolves.
+ */
+/**
+ * Read-only snapshot of a Mailable's build state — produced by
+ * {@link Mailable.inspect}. Used by the preview server (#1900) so the
+ * UI can render what the email WOULD look like without dispatching.
+ *
+ * Generic over `TProps` so typed Mailables expose typed template
+ * props (stacksjs/stacks#1903). Defaults to `Record<string, unknown>`
+ * so untyped usages keep working without changes.
+ */
+export declare interface MailableInspection<TProps extends Record<string, unknown> = Record<string, unknown>> {
+  to: string[] | EmailAddress[]
+  cc: string[] | EmailAddress[]
+  bcc: string[] | EmailAddress[]
+  from?: EmailAddress
+  replyTo?: EmailAddress
+  subject?: string
+  text?: string
+  html?: string
+  template?: { name: string, props: TProps }
+  attachments: EmailAttachment[]
+}
+declare interface TemplateRef<TProps extends Record<string, unknown> = Record<string, unknown>> {
+  name: string
+  props: TProps
+}
+/**
+ * Allowed recipient input — accepts a single address, an array of addresses,
+ * or already-shaped {@link EmailAddress} objects. Strings are treated as
+ * `address` only (no display name).
+ */
+export type MailableAddressInput = string | string[] | EmailAddress | EmailAddress[];
+/**
+ * `true` iff `T` is the loose default (`Record<string, unknown>`),
+ * i.e. the caller didn't specialize the generic. Used to make
+ * `Mailable#template(name)` props-optional in the loose case and
+ * props-required when a concrete `TProps` is supplied.
+ */
+declare type IsLooseProps<T> = Record<string, unknown> extends T ? true : false;
+/**
+ * Builds the variadic tail of {@link Mailable.template}'s parameter list.
+ * Untyped Mailable accepts `.template('name')`; typed `Mailable<P>` must
+ * pass props matching `P`.
+ */
+declare type TemplateArgs<T extends Record<string, unknown>> = IsLooseProps<T> extends true ? [props?: T] : [props: T];
+/**
+ * Laravel-style class-based email definition. Subclass `Mailable`,
+ * implement `build()`, and call `.send()` to dispatch.
+ *
+ * Compared to the existing function-form `Email` / direct `mail.send()`
+ * APIs this gives you:
+ *  - encapsulation of recipient/subject/body building per email type
+ *  - chainable, immutable-feeling fluent setters
+ *  - a single hook (`build`) where view-model -> message translation happens
+ *  - automatic STX template rendering via the existing `template()` helper
+ *
+ * The class still ultimately routes through the same `mail` singleton, so
+ * configured drivers, queueing, and `from` defaults all behave identically.
+ *
+ * @example
+ * ```ts
+ * import { Mailable } from '@stacksjs/email'
+ *
+ * export default class WelcomeMail extends Mailable {
+ *   constructor(private user: { name: string, email: string }) { super() }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.user.email)
+ *       .subject('Welcome!')
+ *       .template('welcome', { name: this.user.name })
+ *   }
+ * }
+ *
+ * await new WelcomeMail(user).send()
+ * ```
+ */
+export declare abstract class Mailable<TProps extends Record<string, unknown> = Record<string, unknown>> {
+  protected _to: string[] | EmailAddress[];
+  protected _cc: string[] | EmailAddress[];
+  protected _bcc: string[] | EmailAddress[];
+  protected _replyTo?: EmailAddress;
+  protected _from?: EmailAddress;
+  protected _subject?: string;
+  protected _text?: string;
+  protected _html?: string;
+  protected _template?: TemplateRef<TProps>;
+  protected _attachments: EmailAttachment[];
+  abstract build(): this | Promise<this>;
+  to(address: MailableAddressInput): this;
+  cc(address: MailableAddressInput): this;
+  bcc(address: MailableAddressInput): this;
+  replyTo(address: string | EmailAddress): this;
+  from(addr: EmailAddress): this;
+  subject(s: string): this;
+  text(body: string): this;
+  html(body: string): this;
+  template(name: string, ...rest: TemplateArgs<TProps>): this;
+  inspect(): MailableInspection<TProps>;
+  attach(path: string, name?: string): this;
+  attachData(buffer: Uint8Array | string, name: string, mime?: string): this;
+  send(options?: MailableSendOptions): Promise<EmailResult>;
+}

package/dist/mailable.js

@@ -0,0 +1,145 @@
+import { config } from "@stacksjs/config";
+import { mail } from "./email";
+import { template as renderTemplate } from "./template";
+
+export class Mailable {
+  _to = [];
+  _cc = [];
+  _bcc = [];
+  _replyTo;
+  _from;
+  _subject;
+  _text;
+  _html;
+  _template;
+  _attachments = [];
+  to(address) {
+    this._to = normalizeAddresses(address);
+    return this;
+  }
+  cc(address) {
+    this._cc = normalizeAddresses(address);
+    return this;
+  }
+  bcc(address) {
+    this._bcc = normalizeAddresses(address);
+    return this;
+  }
+  replyTo(address) {
+    this._replyTo = typeof address === "string" ? { address } : address;
+    return this;
+  }
+  from(addr) {
+    this._from = addr;
+    return this;
+  }
+  subject(s) {
+    this._subject = s;
+    return this;
+  }
+  text(body) {
+    this._text = body;
+    return this;
+  }
+  html(body) {
+    this._html = body;
+    return this;
+  }
+  template(name, ...rest) {
+    const props = rest[0] ?? {};
+    this._template = { name, props };
+    return this;
+  }
+  inspect() {
+    return {
+      to: this._to,
+      cc: this._cc,
+      bcc: this._bcc,
+      from: this._from,
+      replyTo: this._replyTo,
+      subject: this._subject,
+      text: this._text,
+      html: this._html,
+      template: this._template,
+      attachments: this._attachments
+    };
+  }
+  attach(path, name) {
+    this._attachments.push({
+      filename: name || basename(path),
+      content: `__file__:${path}`,
+      encoding: "binary"
+    });
+    return this;
+  }
+  attachData(buffer, name, mime) {
+    this._attachments.push({
+      filename: name,
+      content: buffer,
+      contentType: mime,
+      encoding: typeof buffer === "string" ? "utf8" : "binary"
+    });
+    return this;
+  }
+  async send(options = {}) {
+    await Promise.resolve(this.build());
+    if (this._to.length === 0)
+      throw Error("[Mailable] no recipients \u2014 call this.to(...) inside build()");
+    if (!this._subject)
+      throw Error("[Mailable] no subject \u2014 call this.subject(...) inside build()");
+    let html = this._html, text = this._text;
+    if (this._template) {
+      const rendered = await renderTemplate(this._template.name, {
+        variables: this._template.props,
+        subject: this._subject
+      });
+      if (!html)
+        html = rendered.html;
+      if (!text)
+        text = rendered.text;
+    }
+    const message = {
+      to: this._to,
+      subject: this._subject,
+      from: this._from || resolveDefaultFrom(),
+      ...this._cc.length ? { cc: this._cc } : {},
+      ...this._bcc.length ? { bcc: this._bcc } : {},
+      ...html ? { html } : {},
+      ...text ? { text } : {},
+      ...this._attachments.length ? { attachments: await materializeAttachments(this._attachments) } : {}
+    };
+    if (this._replyTo)
+      message.replyTo = this._replyTo;
+    return (options.driver ? mail.use(options.driver) : mail).send(message);
+  }
+}
+function normalizeAddresses(input) {
+  const arr = Array.isArray(input) ? input : [input];
+  if (arr.some((a) => typeof a === "object" && a !== null))
+    return arr.map((a) => typeof a === "string" ? { address: a } : a);
+  return arr;
+}
+function resolveDefaultFrom() {
+  return {
+    name: config.email.from?.name || "Stacks",
+    address: config.email.from?.address || "no-reply@stacksjs.com"
+  };
+}
+function basename(p) {
+  const idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+  return idx === -1 ? p : p.slice(idx + 1);
+}
+async function materializeAttachments(atts) {
+  return Promise.all(atts.map(async (att) => {
+    if (typeof att.content === "string" && att.content.startsWith("__file__:")) {
+      const filePath = att.content.slice(9), file = Bun.file(filePath), buf = new Uint8Array(await file.arrayBuffer());
+      return {
+        ...att,
+        content: buf,
+        contentType: att.contentType || file.type || void 0,
+        encoding: "binary"
+      };
+    }
+    return att;
+  }));
+}

package/dist/mime.d.ts

@@ -0,0 +1,37 @@
+import type { EmailAttachment } from '@stacksjs/types';
+/**
+ * Encode an SMTP header value with RFC 2047 base64 encoding when it
+ * contains non-ASCII characters. Without this, subjects like
+ * "Encore d'idées" or "你好" produce headers that violate RFC 5322
+ * (which mandates 7-bit ASCII for headers) and get mangled or rejected
+ * by downstream relays.
+ */
+export declare function encodeRfc2047IfNeeded(value: string): string;
+/**
+ * Build the full raw bytes for an RFC 5322 / 2045 email message.
+ *
+ * Returns a single string with CRLF line endings — both SMTP DATA and
+ * SES `SendRawEmail.RawMessage.Data` consume this shape directly.
+ *
+ * Shape decision tree:
+ *
+ *   no attachments:
+ *     - both html+text → multipart/alternative
+ *     - one of either   → single-part
+ *   with attachments:
+ *     - multipart/mixed envelope wrapping the body (alternative or
+ *       single-part) + one part per attachment
+ */
+export declare function buildMimeMessage(options: MimeMessageOptions): string;
+export declare interface MimeMessageOptions {
+  from: string
+  to: string
+  cc?: string
+  replyTo?: string
+  subject: string
+  text?: string
+  html?: string
+  attachments?: EmailAttachment[]
+  messageIdDomain?: string
+  customHeaders?: Record<string, string>
+}

package/dist/mime.js

@@ -0,0 +1,89 @@
+import { Buffer } from "node:buffer";
+export function encodeRfc2047IfNeeded(value) {
+  if (/^[\x00-\x7F]*$/.test(value))
+    return value;
+  return `=?UTF-8?B?${Buffer.from(value, "utf-8").toString("base64")}?=`;
+}
+export function buildMimeMessage(options) {
+  const {
+    from,
+    to,
+    cc,
+    replyTo,
+    subject,
+    text,
+    html,
+    attachments,
+    messageIdDomain,
+    customHeaders
+  } = options, lines = [], hasAttachments = !!(attachments && attachments.length > 0), boundary = `----=_Part_${Date.now()}_${Math.random().toString(36).substring(2)}`;
+  lines.push(`From: ${from}`);
+  lines.push(`To: ${to}`);
+  if (cc)
+    lines.push(`Cc: ${cc}`);
+  if (replyTo)
+    lines.push(`Reply-To: ${replyTo}`);
+  lines.push(`Subject: ${encodeRfc2047IfNeeded(subject)}`);
+  lines.push("MIME-Version: 1.0");
+  lines.push(`Date: ${new Date().toUTCString()}`);
+  lines.push(`Message-ID: <${Date.now()}.${Math.random().toString(36).substring(2)}@${messageIdDomain || "localhost"}>`);
+  if (customHeaders)
+    for (const [k, v] of Object.entries(customHeaders))
+      lines.push(`${k}: ${v}`);
+  if (hasAttachments) {
+    const mixedBoundary = boundary, altBoundary = `${boundary}_alt`;
+    lines.push(`Content-Type: multipart/mixed; boundary="${mixedBoundary}"`);
+    lines.push("");
+    lines.push(`--${mixedBoundary}`);
+    pushBodyParts(lines, { text, html, altBoundary });
+    for (const attachment of attachments) {
+      lines.push(`--${mixedBoundary}`);
+      pushAttachmentPart(lines, attachment);
+    }
+    lines.push(`--${mixedBoundary}--`);
+  } else
+    pushBodyParts(lines, { text, html, altBoundary: boundary });
+  return lines.join(`\r
+`);
+}
+function pushBodyParts(lines, options) {
+  const { text, html, altBoundary } = options;
+  if (html && text) {
+    lines.push(`Content-Type: multipart/alternative; boundary="${altBoundary}"`);
+    lines.push("");
+    lines.push(`--${altBoundary}`);
+    lines.push("Content-Type: text/plain; charset=UTF-8");
+    lines.push("Content-Transfer-Encoding: 7bit");
+    lines.push("");
+    lines.push(text);
+    lines.push("");
+    lines.push(`--${altBoundary}`);
+    lines.push("Content-Type: text/html; charset=UTF-8");
+    lines.push("Content-Transfer-Encoding: 7bit");
+    lines.push("");
+    lines.push(html);
+    lines.push("");
+    lines.push(`--${altBoundary}--`);
+  } else if (html) {
+    lines.push("Content-Type: text/html; charset=UTF-8");
+    lines.push("Content-Transfer-Encoding: 7bit");
+    lines.push("");
+    lines.push(html);
+  } else if (text) {
+    lines.push("Content-Type: text/plain; charset=UTF-8");
+    lines.push("Content-Transfer-Encoding: 7bit");
+    lines.push("");
+    lines.push(text);
+  }
+}
+function pushAttachmentPart(lines, attachment) {
+  const contentType = attachment.contentType || "application/octet-stream", safeFilename = encodeRfc2047IfNeeded(attachment.filename.replace(/\\/g, "\\\\").replace(/"/g, "\\\""));
+  lines.push(`Content-Type: ${contentType}; name="${safeFilename}"`);
+  lines.push(`Content-Disposition: attachment; filename="${safeFilename}"`);
+  lines.push("Content-Transfer-Encoding: base64");
+  lines.push("");
+  const raw = typeof attachment.content === "string" ? Buffer.from(attachment.content, "utf-8").toString("base64") : Buffer.from(attachment.content).toString("base64"), wrapped = raw.match(/.{1,76}/g)?.join(`\r
+`) ?? raw;
+  lines.push(wrapped);
+  lines.push("");
+}

package/dist/preview-ui.d.ts

@@ -0,0 +1,11 @@
+import type { DiscoveredMailable, MailablePreview } from './preview';
+/**
+ * Render the index page listing every discovered Mailable.
+ */
+export declare function renderIndexHtml(mailables: DiscoveredMailable[]): string;
+/**
+ * Render the preview page for a single Mailable. `view` controls the
+ * iframe width: 'desktop' (default) / 'mobile' / 'text' (renders the
+ * plain-text version instead of HTML).
+ */
+export declare function renderPreviewHtml(mailable: DiscoveredMailable, preview: MailablePreview, view?: 'desktop' | 'mobile' | 'text'): string;

package/dist/preview-ui.js

@@ -0,0 +1,132 @@
+const ROOT = "/_stacks/mail/preview";
+function escape(s) {
+  return String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+function fmtAddresses(addresses) {
+  if (!addresses?.length)
+    return "\u2014";
+  return addresses.map((a) => {
+    if (typeof a === "string")
+      return escape(a);
+    if (a.name)
+      return `${escape(a.name)} &lt;${escape(a.address)}&gt;`;
+    return escape(a.address);
+  }).join(", ");
+}
+function shell(title, body) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escape(title)} \u2014 Stacks Mail Preview</title>
+  <style>
+    :root { color-scheme: light dark; }
+    * { box-sizing: border-box; }
+    body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; background: #f4f4f5; color: #111827; line-height: 1.5; }
+    @media (prefers-color-scheme: dark) {
+      body { background: #0a0a0a; color: #ededed; }
+      .panel { background: #1a1a1a; border-color: #2a2a2a; }
+      a { color: #818cf8; }
+      .muted { color: #9ca3af; }
+      pre { background: #2a2a2a; color: #ededed; }
+    }
+    header { padding: 16px 24px; background: #fff; border-bottom: 1px solid #e5e7eb; }
+    @media (prefers-color-scheme: dark) { header { background: #1a1a1a; border-color: #2a2a2a; } }
+    header h1 { margin: 0; font-size: 16px; font-weight: 600; }
+    header h1 a { color: inherit; text-decoration: none; }
+    header .crumb { font-size: 13px; color: #6b7280; }
+    main { padding: 24px; max-width: 1200px; margin: 0 auto; }
+    .panel { background: #fff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; margin-bottom: 16px; }
+    .grid { display: grid; grid-template-columns: 220px 1fr; gap: 16px; }
+    .pill { display: inline-block; padding: 2px 8px; font-size: 12px; border-radius: 999px; background: #eef2ff; color: #3730a3; }
+    .toolbar { display: flex; gap: 8px; padding: 8px 0; flex-wrap: wrap; align-items: center; }
+    .toolbar a { padding: 6px 12px; border: 1px solid #d1d5db; border-radius: 6px; text-decoration: none; color: inherit; font-size: 13px; }
+    .toolbar a.active { background: #4f46e5; color: white; border-color: #4f46e5; }
+    .muted { color: #6b7280; font-size: 13px; }
+    iframe { width: 100%; min-height: 800px; border: 0; background: #fff; border-radius: 8px; }
+    iframe.mobile { max-width: 375px; margin: 0 auto; display: block; min-height: 700px; }
+    pre { background: #f3f4f6; padding: 12px; border-radius: 6px; overflow: auto; font-size: 12px; line-height: 1.5; max-height: 400px; }
+    .meta { display: grid; grid-template-columns: 80px 1fr; gap: 6px 12px; font-size: 13px; }
+    .meta dt { color: #6b7280; }
+    .meta dd { margin: 0; }
+    .empty { text-align: center; padding: 48px 24px; color: #6b7280; }
+    ul.list { list-style: none; padding: 0; margin: 0; }
+    ul.list li { padding: 12px; border-bottom: 1px solid #e5e7eb; }
+    @media (prefers-color-scheme: dark) { ul.list li { border-color: #2a2a2a; } }
+    ul.list li:last-child { border-bottom: 0; }
+    ul.list a { color: inherit; text-decoration: none; font-weight: 500; }
+    ul.list a:hover { color: #4f46e5; }
+    .error { background: #fef2f2; border: 1px solid #fecaca; color: #991b1b; padding: 12px 16px; border-radius: 6px; }
+    @media (prefers-color-scheme: dark) { .error { background: #1f0a0a; border-color: #7f1d1d; color: #fca5a5; } }
+  </style>
+</head>
+<body>
+  <header>
+    <h1><a href="${ROOT}">Mail Preview</a> <span class="crumb">${escape(title)}</span></h1>
+  </header>
+  <main>${body}</main>
+</body>
+</html>`;
+}
+export function renderIndexHtml(mailables) {
+  if (mailables.length === 0)
+    return shell("Index", `
+      <div class="empty panel">
+        <p>No Mailables found in <code>app/Mail/</code>.</p>
+        <p class="muted">Run <code>./buddy make:mail Welcome</code> to scaffold one.</p>
+      </div>
+    `);
+  const items = mailables.map((m) => `
+    <li>
+      <a href="${ROOT}/${escape(m.slug)}">${escape(m.name)}</a>
+      <div class="muted">app/Mail/${escape(m.name)}.ts \xB7 template: ${escape(m.slug)}.stx</div>
+    </li>
+  `).join("");
+  return shell("Index", `
+    <div class="panel">
+      <p class="muted">${mailables.length} mailable${mailables.length === 1 ? "" : "s"} discovered. Add sample props at
+      <code>resources/emails/_previews/&lt;slug&gt;.ts</code> for richer previews.</p>
+      <ul class="list">${items}</ul>
+    </div>
+  `);
+}
+export function renderPreviewHtml(mailable, preview, view = "desktop") {
+  const { inspection, text, sampleProps, error } = preview, baseUrl = `${ROOT}/${mailable.slug}`, rawUrl = `${baseUrl}/raw`, errorBlock = error ? `<div class="panel"><div class="error"><strong>${escape(mailable.name)} failed to render:</strong> ${escape(error)}</div></div>` : "", iframeBlock = error ? "" : view === "text" ? `<div class="panel"><pre>${escape(text || "(no plain-text body)")}</pre></div>` : `<div class="panel"><iframe src="${rawUrl}" class="${view === "mobile" ? "mobile" : ""}" title="${escape(mailable.name)} body" sandbox="allow-same-origin"></iframe></div>`, sampleHint = sampleProps ? `<dd><code>resources/emails/_previews/${escape(mailable.slug)}.ts</code></dd>` : `<dd class="muted">No sample file \u2014 edit <code>resources/emails/_previews/${escape(mailable.slug)}.ts</code> to customize.</dd>`;
+  return shell(mailable.name, `
+    ${errorBlock}
+
+    <div class="grid">
+      <aside>
+        <div class="panel">
+          <dl class="meta">
+            <dt>Subject</dt><dd>${escape(inspection.subject || "(no subject)")}</dd>
+            <dt>To</dt><dd>${fmtAddresses(inspection.to)}</dd>
+            ${inspection.cc?.length ? `<dt>Cc</dt><dd>${fmtAddresses(inspection.cc)}</dd>` : ""}
+            ${inspection.bcc?.length ? `<dt>Bcc</dt><dd>${fmtAddresses(inspection.bcc)}</dd>` : ""}
+            ${inspection.from ? `<dt>From</dt><dd>${fmtAddresses([inspection.from])}</dd>` : ""}
+            ${inspection.replyTo ? `<dt>Reply-To</dt><dd>${fmtAddresses([inspection.replyTo])}</dd>` : ""}
+            ${inspection.template ? `<dt>Template</dt><dd>${escape(inspection.template.name)}.stx</dd>` : ""}
+            ${inspection.attachments?.length ? `<dt>Attachments</dt><dd>${inspection.attachments.length}</dd>` : ""}
+          </dl>
+        </div>
+
+        <div class="panel">
+          <h3 style="margin: 0 0 8px; font-size: 13px; font-weight: 600;">Sample props</h3>
+          ${sampleHint}
+          ${sampleProps ? `<pre>${escape(JSON.stringify(sampleProps, null, 2))}</pre>` : ""}
+        </div>
+      </aside>
+
+      <section>
+        <div class="toolbar">
+          <a href="${baseUrl}" class="${view === "desktop" ? "active" : ""}">Desktop</a>
+          <a href="${baseUrl}?view=mobile" class="${view === "mobile" ? "active" : ""}">Mobile</a>
+          <a href="${baseUrl}?view=text" class="${view === "text" ? "active" : ""}">Text</a>
+          <span class="muted" style="margin-left: auto;">${escape(mailable.name)}</span>
+        </div>
+        ${iframeBlock}
+      </section>
+    </div>
+  `);
+}

package/dist/preview.d.ts

@@ -0,0 +1,50 @@
+import type { MailableInspection } from './mailable';
+/*.ts` and return the discovered Mailables. Non-`.ts`
+ * files (test files, `.d.ts`, etc.) are skipped.
+ *
+ * Filesystem scan is synchronous + cheap (one directory, no recursion)
+ * — fine for a dev-only preview surface; not a hot path.
+ */
+export declare function discoverMailables(): DiscoveredMailable[];
+/**
+ * Look up sample props for a Mailable. Convention:
+ *
+ *   resources/emails/_previews/<slug>.ts
+ *     → default export is the props object passed to `new Mailable(props)`
+ *
+ * Returns `null` when no sample file is present — the caller falls back
+ * to instantiating with `{}` so apps without samples still render
+ * (defaulted props in the Mailable's build() show their fallback values).
+ */
+export declare function loadSampleProps(slug: string): Promise<Record<string, unknown> | null>;
+/**
+ * Render a Mailable to its preview payload. Imports the source file,
+ * picks the first exported subclass of `Mailable`, instantiates with
+ * sample props (or `{}` when none exist), runs `build()`, and resolves
+ * the bound template through `template()` from this same package.
+ *
+ * Errors at any step (import failure, no Mailable export, build()
+ * throws, template not found) are returned as `error` on the preview
+ * payload rather than thrown — the route layer renders them as part
+ * of the UI so the user sees what broke.
+ */
+export declare function renderMailablePreview(mailable: DiscoveredMailable): Promise<MailablePreview>;
+/**
+ * One Mailable discovered under `app/Mail/`.
+ */
+export declare interface DiscoveredMailable {
+  name: string
+  path: string
+  slug: string
+}
+/**
+ * The fully-rendered preview of one Mailable. Returned by
+ * {@link renderMailablePreview} and consumed by the preview HTML.
+ */
+export declare interface MailablePreview {
+  inspection: MailableInspection
+  html: string
+  text: string
+  sampleProps: Record<string, unknown> | null
+  error?: string
+}

package/dist/preview.js

@@ -0,0 +1,97 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { existsSync } from "@stacksjs/storage";
+import { userEmailsPath, userMailPath } from "@stacksjs/path";
+import { kebabCase } from "@stacksjs/strings";
+import { Mailable } from "./mailable";
+import { template } from "./template";
+export function discoverMailables() {
+  const dir = userMailPath();
+  if (!existsSync(dir))
+    return [];
+  const entries = readdirSync(dir, { withFileTypes: !0 }), out = [];
+  for (const entry of entries) {
+    if (!entry.isFile())
+      continue;
+    if (!entry.name.endsWith(".ts"))
+      continue;
+    if (entry.name.endsWith(".d.ts"))
+      continue;
+    if (entry.name.endsWith(".test.ts"))
+      continue;
+    if (entry.name.endsWith(".spec.ts"))
+      continue;
+    const base = entry.name.replace(/\.ts$/, "");
+    out.push({
+      name: base,
+      path: join(dir, entry.name),
+      slug: kebabCase(base)
+    });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+export async function loadSampleProps(slug) {
+  const samplePath = userEmailsPath(`_previews/${slug}.ts`);
+  if (!existsSync(samplePath))
+    return null;
+  try {
+    const mod = await import(samplePath), props = mod.default ?? mod.props ?? null;
+    return props && typeof props === "object" ? props : null;
+  } catch (err) {
+    return { __preview_error__: `Failed to load sample props: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+export async function renderMailablePreview(mailable) {
+  const empty = {
+    inspection: { to: [], cc: [], bcc: [], attachments: [] },
+    html: "",
+    text: "",
+    sampleProps: null
+  };
+  try {
+    const mod = await import(mailable.path), Cls = pickMailableConstructor(mod);
+    if (!Cls)
+      return { ...empty, error: `No subclass of \`Mailable\` exported from ${mailable.path}.` };
+    const sampleProps = await loadSampleProps(mailable.slug), instance = new Cls(sampleProps ?? {});
+    if (!(instance instanceof Mailable))
+      return { ...empty, sampleProps, error: "Constructor did not produce a Mailable instance." };
+    await instance.build();
+    const inspection = instance.inspect();
+    if (!inspection.template)
+      return {
+        inspection,
+        html: inspection.html ?? "",
+        text: inspection.text ?? "",
+        sampleProps
+      };
+    const rendered = await template(inspection.template.name, {
+      variables: inspection.template.props,
+      subject: inspection.subject
+    });
+    return {
+      inspection,
+      html: rendered.html,
+      text: rendered.text,
+      sampleProps
+    };
+  } catch (err) {
+    return { ...empty, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) };
+  }
+}
+function pickMailableConstructor(mod) {
+  const candidates = [];
+  if (mod.default)
+    candidates.push(mod.default);
+  for (const key of Object.keys(mod))
+    if (key !== "default")
+      candidates.push(mod[key]);
+  for (const candidate of candidates) {
+    if (typeof candidate !== "function")
+      continue;
+    if (!(candidate.prototype instanceof Mailable))
+      continue;
+    return candidate;
+  }
+  return null;
+}