react-email-rails 0.2.0 → 0.4.0

package/bin/build.mjs

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 import { createBuilder } from "vite"
-import { fail, isolatedViteConfig, loadReactEmailRailsConfig } from "./shared.mjs"
-import { RENDER_PROTOCOL_VERSION, VERSION } from "../dist/version.js"
+import {
+  exitIfHealthCheck,
+  fail,
+  isolatedViteConfig,
+  loadReactEmailRailsConfig,
+} from "./shared.mjs"
 
-if (process.argv.includes("--health")) {
-  process.stdout.write(
-    JSON.stringify({ ok: true, protocolVersion: RENDER_PROTOCOL_VERSION, packageVersion: VERSION }),
-  )
-  process.exit(0)
-}
+exitIfHealthCheck()
 
 const args = process.argv.slice(2)
 const readOption = (long, short) => {
@@ -52,9 +51,8 @@ const { userConfig, plugin, vite } = await loadReactEmailRailsConfig({
   configLoader,
 })
 
-// Build production emails with the same isolation principle as the dev renderer:
-// keep component resolution and transforms, but leave unrelated app plugins out
-// of the email environment so client/global plugin hooks cannot break SSR output.
+// Same isolation as the dev renderer: keep component resolve/transforms but leave unrelated
+// app plugins out of the email environment so their hooks can't break SSR output.
 const builder = await createBuilder(
   isolatedViteConfig(userConfig, vite, {
     root: root ?? userConfig.root,

package/bin/dev.mjs

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 import { createServer, isRunnableDevEnvironment } from "vite"
-import { fail, isolatedViteConfig, loadReactEmailRailsConfig } from "./shared.mjs"
-import { RENDER_PROTOCOL_VERSION, VERSION } from "../dist/version.js"
+import {
+  exitIfHealthCheck,
+  fail,
+  isolatedViteConfig,
+  loadReactEmailRailsConfig,
+} from "./shared.mjs"
 
-if (process.argv.includes("--health")) {
-  process.stdout.write(
-    JSON.stringify({ ok: true, protocolVersion: RENDER_PROTOCOL_VERSION, packageVersion: VERSION }),
-  )
-  process.exit(0)
-}
+exitIfHealthCheck()
 
 const toStderr = (message) => process.stderr.write(`${message}\n`)
 const logger = {
@@ -39,9 +38,7 @@ const { userConfig, plugin, vite } = await loadReactEmailRailsConfig({
   mode: "development",
 })
 
-// Forward config that affects how components resolve and compile (but not the
-// host's dev-server plugins, which have global side effects), so dev rendering
-// stays close to the production email bundle.
+// Forward only component resolve/compile config, so dev rendering stays close to the build.
 const server = await createServer(
   isolatedViteConfig(userConfig, vite, {
     configFile: false,
@@ -53,8 +50,7 @@ const server = await createServer(
   }),
 )
 
-// Render through the same `email` environment the production build uses, so dev
-// and build resolve and compile components identically.
+// Render through the same `email` environment as the production build, so the two match.
 const environment = server.environments.email
 if (!isRunnableDevEnvironment(environment)) {
   await server.close()
@@ -63,6 +59,7 @@ if (!isRunnableDevEnvironment(environment)) {
 
 try {
   const { run } = await environment.runner.import("virtual:react-email-rails/server")
+  // Restore before run(): serve() re-isolates stdout with its own protocol writer.
   restoreStdout()
   await run()
 } finally {

package/bin/shared.mjs

@@ -1,7 +1,11 @@
 import { loadConfigFromFile, mergeConfig } from "vite"
 
+import { RENDER_PROTOCOL_VERSION, VERSION } from "../dist/version.js"
+
+// Wire contract: must match the Symbol.for(...) keys in src/index.ts.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config")
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite")
+// Must mirror ReactEmailRailsViteOptions in src/index.ts and the option list in README.md.
 const EMAIL_VITE_CONFIG_KEYS = [
   "assetsInclude",
   "css",
@@ -13,6 +17,16 @@ const EMAIL_VITE_CONFIG_KEYS = [
   "resolve",
 ]
 
+// Emit the version/protocol handshake and exit on --health. Shared by the build and dev bins.
+export function exitIfHealthCheck() {
+  if (!process.argv.includes("--health")) return
+
+  process.stdout.write(
+    JSON.stringify({ ok: true, protocolVersion: RENDER_PROTOCOL_VERSION, packageVersion: VERSION }),
+  )
+  process.exit(0)
+}
+
 export async function loadReactEmailRailsConfig({
   command,
   mode,

package/dist/document.d.ts

@@ -1,6 +1,6 @@
 import { type Extensions } from "@tiptap/core";
-import type { DroppedNode, RenderResult } from "./runtime.js";
-export type { DroppedNode };
+import type { DroppedNode, ParseDocumentRequest, ParseResult, RenderDocumentRequest, RenderResult } from "./runtime.js";
+export type { DroppedNode, ParseDocumentRequest, RenderDocumentRequest };
 export type DocumentRenderer = {
     buildExtensions: (context: unknown) => Extensions;
     transformDocument?: (document: unknown, context: unknown) => unknown;
@@ -8,11 +8,12 @@ export type DocumentRenderer = {
 };
 export type DocumentLoader = DocumentRenderer | (() => Promise<DocumentRenderer>);
 export type DocumentRegistry = Record<string, DocumentLoader>;
-export type RenderDocumentRequest = {
-    kind: "document";
-    type: string;
-    document: unknown;
-    context?: unknown;
-    preview?: string | null;
+type GenerateJSON = (html: string, extensions: Extensions) => unknown;
+type RenderMarkdown = (markdown: string) => string | Promise<string>;
+type ParseDependencies = {
+    generateJSON?: GenerateJSON;
+    renderMarkdown?: RenderMarkdown;
 };
 export declare function composeDocument(request: RenderDocumentRequest, registry: DocumentRegistry): Promise<RenderResult>;
+export declare function parseDocument(request: ParseDocumentRequest, registry: DocumentRegistry, dependencies?: ParseDependencies): Promise<ParseResult>;
+export declare function createParseDocument(generateJSON: GenerateJSON, renderMarkdown?: RenderMarkdown): (request: ParseDocumentRequest, registry: DocumentRegistry) => Promise<ParseResult>;

package/dist/document.js

@@ -7,9 +7,8 @@ import { getSchema, resolveExtensions } from "@tiptap/core";
 const STRUCTURAL_NODE_TYPES = new Set(resolveExtensions([StarterKit, EmailTheming])
     .filter((extension) => extension.type === "node" && !(extension instanceof EmailNode))
     .map((extension) => extension.name));
-// composeReactEmail renders a node as null when no extension matches its type or
-// the match is not an EmailNode. Mirror that predicate over the document so
-// warnings report the silent case: an in-schema node with no email renderer.
+// composeReactEmail renders a node as null when no extension matches or the match isn't an
+// EmailNode; mirror that here so warnings catch the silent case (in-schema node, no email renderer).
 function collectDroppedNodes(document, extensions) {
     const byName = new Map();
     for (const extension of extensions)
@@ -35,6 +34,54 @@ function collectDroppedNodes(document, extensions) {
     walk(document.content);
     return [...counts].map(([type, count]) => ({ type, count }));
 }
+async function resolveRenderer(type, registry) {
+    const loader = registry[type];
+    if (!loader)
+        throw new Error(`React email document renderer not found: ${type}`);
+    const renderer = typeof loader === "function" ? await loader() : loader;
+    if (typeof renderer.buildExtensions !== "function") {
+        throw new Error(`React email document renderer must export a buildExtensions function: ${type}`);
+    }
+    return renderer;
+}
+async function loadGenerateJSON() {
+    try {
+        const mod = (await import(/* @vite-ignore */ "@tiptap/html"));
+        if (typeof mod.generateJSON === "function")
+            return mod.generateJSON;
+    }
+    catch (error) {
+        throw new Error(`@tiptap/html and happy-dom are required to parse HTML documents; install both packages before calling parse (${error instanceof Error ? error.message : "module load failed"})`);
+    }
+    throw new Error("@tiptap/html is missing the expected generateJSON export; check the installed version");
+}
+async function loadRenderMarkdown() {
+    try {
+        const mod = (await import(/* @vite-ignore */ "marked"));
+        const marked = mod.marked;
+        if (marked && typeof marked.parse === "function") {
+            const parse = marked.parse.bind(marked);
+            return (markdown) => parse(markdown);
+        }
+    }
+    catch (error) {
+        throw new Error(`marked is required to parse Markdown documents; install it before calling parse with markdown (${error instanceof Error ? error.message : "module load failed"})`);
+    }
+    throw new Error("marked is missing the expected parse export; check the installed version");
+}
+// Both inputs converge on HTML: markdown is rendered first, then parsed like any HTML.
+async function resolveHtmlInput(request, dependencies) {
+    const hasHtml = request.html !== undefined;
+    const hasMarkdown = request.markdown !== undefined;
+    if (hasHtml === hasMarkdown) {
+        throw new Error("parse request must include exactly one of `html` or `markdown`");
+    }
+    if (hasMarkdown) {
+        const renderMarkdown = dependencies.renderMarkdown ?? (await loadRenderMarkdown());
+        return renderMarkdown(request.markdown);
+    }
+    return request.html;
+}
 export async function composeDocument(request, registry) {
     // Fail legibly if the optional editor peers are present but their shape shifted.
     if (typeof composeReactEmail !== "function" ||
@@ -42,13 +89,7 @@ export async function composeDocument(request, registry) {
         typeof getSchema !== "function") {
         throw new Error("@react-email/editor or @tiptap/core is missing expected exports (composeReactEmail/resolveExtensions/getSchema); check the installed versions");
     }
-    const loader = registry[request.type];
-    if (!loader)
-        throw new Error(`React email document renderer not found: ${request.type}`);
-    const renderer = typeof loader === "function" ? await loader() : loader;
-    if (typeof renderer.buildExtensions !== "function") {
-        throw new Error(`React email document renderer must export a buildExtensions function: ${request.type}`);
-    }
+    const renderer = await resolveRenderer(request.type, registry);
     const document = renderer.transformDocument?.(request.document, request.context) ?? request.document;
     const extensions = resolveExtensions(renderer.buildExtensions(request.context));
     const schema = getSchema(extensions);
@@ -67,3 +108,18 @@ export async function composeDocument(request, registry) {
     const { html, text } = await composeReactEmail(params);
     return warnings.length > 0 ? { html, text, warnings } : { html, text };
 }
+export async function parseDocument(request, registry, dependencies = {}) {
+    const renderer = await resolveRenderer(request.type, registry);
+    const extensions = resolveExtensions(renderer.buildExtensions(request.context));
+    const schema = getSchema(extensions);
+    const html = await resolveHtmlInput(request, dependencies);
+    const parseHTML = dependencies.generateJSON ?? (await loadGenerateJSON());
+    const parsed = parseHTML(html, extensions);
+    const document = schema.nodeFromJSON(parsed).toJSON();
+    return { document };
+}
+export function createParseDocument(generateJSON, renderMarkdown) {
+    // Omit renderMarkdown entirely when unset; exactOptionalPropertyTypes forbids passing `undefined`.
+    const dependencies = renderMarkdown === undefined ? { generateJSON } : { generateJSON, renderMarkdown };
+    return (request, registry) => parseDocument(request, registry, dependencies);
+}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 const DEFAULT_IGNORE = ["**/_*", "**/_*/**"];
 const DEFAULT_EMAIL_PATH = "app/javascript/emails";
 const DEFAULT_EMAIL_EXTENSIONS = [".tsx", ".jsx"];
@@ -10,10 +11,20 @@ const RESOLVED_MAIN = `\0${VIRTUAL_MAIN}`;
 const VIRTUAL_MODULE_PATTERN = /virtual:react-email-rails\/(?:server|main)$/;
 // The dedicated build environment that emits the server-side email bundle.
 export const EMAIL_ENVIRONMENT = "email";
+// Wire contract: must match the Symbol.for(...) keys the bins read in bin/shared.mjs.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config");
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite");
+// Must match Ruby's Configuration::BUNDLE_PATH (check_version_sync.rb asserts it).
 const OUT_DIR = "tmp/react-email-rails";
 const BUNDLE_FILE = "emails.js";
+const require = createRequire(import.meta.url);
+// happy-dom (via @tiptap/html) pulls in `ws`, which guards optional native-addon requires behind
+// these flags. Setting them lets a standalone (noExternal) build tree-shake the uninstalled
+// bufferutil/utf-8-validate requires away; ws's pure-JS path is all the HTML parser needs.
+const WS_NATIVE_ADDON_OPT_OUT = {
+    "process.env.WS_NO_BUFFER_UTIL": "'1'",
+    "process.env.WS_NO_UTF_8_VALIDATE": "'1'",
+};
 function normalizeSource(option, defaultPath, defaultExtensions) {
     const source = typeof option === "string" ? { path: option } : (option ?? {});
     const path = (source.path ?? defaultPath).replace(/^\/|\/$/g, "");
@@ -38,6 +49,17 @@ function normalizeSource(option, defaultPath, defaultExtensions) {
     const globArg = JSON.stringify(globPatterns.length === 1 ? globPatterns[0] : globPatterns);
     return { path, extensions, ignore, root, globArg };
 }
+function optionalPeersAvailable(specifiers) {
+    return specifiers.every((specifier) => {
+        try {
+            require.resolve(specifier);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export function reactEmailRails(options = {}) {
     const emailSource = normalizeSource(options.emails, DEFAULT_EMAIL_PATH, DEFAULT_EMAIL_EXTENSIONS);
     const documentSource = options.documents === undefined || options.documents === false
@@ -59,13 +81,23 @@ export function reactEmailRails(options = {}) {
             filter: { id: VIRTUAL_MODULE_PATTERN },
             handler(id) {
                 if (id === RESOLVED_SERVER) {
-                    const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`];
-                    // Imported only here, so the editor stays out of the email build graph when off.
-                    if (documentSource)
-                        lines.push(`import { composeDocument } from "react-email-rails/document"`);
-                    lines.push(`const modules = import.meta.glob(${emailSource.globArg})`, `const extensions = ${JSON.stringify(emailSource.extensions)}`, `const registry = Object.create(null)`, `for (const path in modules) {`, `  const extension = extensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`, `  registry[toComponentName(path, ${JSON.stringify(emailSource.root)}, extension)] = modules[path]`, `}`);
+                    const lines = [`import { buildRegistry, serve } from "react-email-rails/runtime"`];
+                    const parserPeersAvailable = documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"]);
+                    // Markdown parsing layers `marked` on top of the HTML parser peers.
+                    const markdownPeerAvailable = parserPeersAvailable && optionalPeersAvailable(["marked"]);
+                    if (documentSource) {
+                        lines.push(parserPeersAvailable
+                            ? `import { composeDocument, createParseDocument } from "react-email-rails/document"`
+                            : `import { composeDocument, parseDocument } from "react-email-rails/document"`);
+                        if (parserPeersAvailable) {
+                            lines.push(`import { generateJSON } from "@tiptap/html"`);
+                            if (markdownPeerAvailable)
+                                lines.push(`import { marked } from "marked"`);
+                        }
+                    }
+                    lines.push(`const registry = buildRegistry(import.meta.glob(${emailSource.globArg}), ${JSON.stringify(emailSource.extensions)}, ${JSON.stringify(emailSource.root)})`);
                     if (documentSource) {
-                        lines.push(`const documentModules = import.meta.glob(${documentSource.globArg})`, `const documentExtensions = ${JSON.stringify(documentSource.extensions)}`, `const documentRegistry = Object.create(null)`, `for (const path in documentModules) {`, `  const extension = documentExtensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`, `  documentRegistry[toComponentName(path, ${JSON.stringify(documentSource.root)}, extension)] = documentModules[path]`, `}`, `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument })`);
+                        lines.push(`const documentRegistry = buildRegistry(import.meta.glob(${documentSource.globArg}), ${JSON.stringify(documentSource.extensions)}, ${JSON.stringify(documentSource.root)})`, `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument, parse: ${parserPeersAvailable ? `createParseDocument(generateJSON${markdownPeerAvailable ? ", (markdown) => marked.parse(markdown)" : ""})` : "parseDocument"} })`);
                     }
                     else {
                         lines.push(`export const run = () => serve(registry)`);
@@ -78,17 +110,15 @@ export function reactEmailRails(options = {}) {
             },
         },
         config(_config, env) {
-            // Register a dedicated `email` build environment. The official
-            // react-email-rails-build bin opts into building it with an isolated
-            // plugin stack so host app plugins cannot break email SSR builds.
-            // The environment is a server consumer. Production standalone builds inline
-            // Node dependencies by default so Rails runtime images do not need
-            // node_modules; dev rendering keeps dependencies external for Vite's module
-            // runner.
+            // Dedicated `email` build environment: the react-email-rails-build bin builds it with an
+            // isolated plugin stack so host plugins can't break email SSR. Standalone builds inline
+            // Node deps (so Rails images need no node_modules); dev keeps them external for the runner.
             return {
                 environments: {
                     [EMAIL_ENVIRONMENT]: {
-                        ...(standalone && env.command === "build" ? { resolve: { noExternal: true } } : {}),
+                        ...(standalone && env.command === "build"
+                            ? { resolve: { noExternal: true }, define: WS_NATIVE_ADDON_OPT_OUT }
+                            : {}),
                         build: {
                             ssr: true,
                             outDir: OUT_DIR,

package/dist/runtime.d.ts

@@ -24,6 +24,13 @@ export type RenderDocumentRequest = {
     context?: unknown;
     preview?: string | null;
 };
+export type ParseDocumentRequest = {
+    kind: "parse";
+    type: string;
+    html?: string;
+    markdown?: string;
+    context?: unknown;
+};
 export type DroppedNode = {
     type: string;
     count: number;
@@ -31,14 +38,19 @@ export type DroppedNode = {
 export type RenderResult = RenderedEmail & {
     warnings?: DroppedNode[];
 };
+export type ParseResult = {
+    document: unknown;
+};
 export type DocumentSupport<Registry = unknown> = {
     registry: Registry;
     compose: (request: RenderDocumentRequest, registry: Registry) => Promise<RenderResult>;
+    parse: (request: ParseDocumentRequest, registry: Registry) => Promise<ParseResult>;
 };
 export type EmailRenderOptions = {
     html?: ReactEmailRenderOptions;
     text?: ReactEmailRenderOptions;
 };
 export declare function toComponentName(globPath: string, root: string, extension: string): string;
+export declare function buildRegistry(modules: EmailRegistry, extensions: string[], root: string): EmailRegistry;
 export declare function renderEmail(request: RenderRequest, registry: EmailRegistry): Promise<RenderedEmail>;
 export declare function serve<Registry = unknown>(registry: EmailRegistry, documents?: DocumentSupport<Registry> | null): Promise<void>;

package/dist/runtime.js

@@ -5,6 +5,15 @@ export function toComponentName(globPath, root, extension) {
     const start = globPath.lastIndexOf(root) + root.length;
     return globPath.slice(start, globPath.length - extension.length);
 }
+// Map glob results to a component-name registry (used for both email and document registries).
+export function buildRegistry(modules, extensions, root) {
+    const registry = Object.create(null);
+    for (const [path, loader] of Object.entries(modules)) {
+        const extension = extensions.find((ext) => path.endsWith(ext)) ?? path.slice(path.lastIndexOf("."));
+        registry[toComponentName(path, root, extension)] = loader;
+    }
+    return registry;
+}
 export async function renderEmail(request, registry) {
     const loader = registry[request.component];
     if (!loader)
@@ -20,18 +29,26 @@ export async function renderEmail(request, registry) {
 function isDocumentRequest(request) {
     return (request !== null &&
         typeof request === "object" &&
+        "kind" in request &&
         request.kind === "document");
 }
+function isParseRequest(request) {
+    return (request !== null && typeof request === "object" && "kind" in request && request.kind === "parse");
+}
 function isHealthRequest(request) {
     return request !== null && typeof request === "object" && "health" in request;
 }
-// Requests without a document kind are component renders, preserving the email path.
 async function renderRequest(request, registry, documents) {
     if (isDocumentRequest(request)) {
         if (!documents)
             throw new Error("React email document rendering is not enabled");
         return documents.compose(request, documents.registry);
     }
+    if (isParseRequest(request)) {
+        if (!documents)
+            throw new Error("React email document rendering is not enabled");
+        return documents.parse(request, documents.registry);
+    }
     return renderEmail(request, registry);
 }
 export async function serve(registry, documents = null) {
@@ -56,13 +73,15 @@ export async function serve(registry, documents = null) {
         process.exitCode = 1;
     }
 }
-// Reserve stdout for the JSON render protocol. Stray writes from email components
-// or their dependencies — including console.log, which Node routes through
-// process.stdout.write — are diverted to stderr so they cannot corrupt or desync
-// a response frame. Returns the writer to use for protocol output.
+// Reserve stdout for the JSON render protocol: stray writes (e.g. console.log, which Node
+// routes through process.stdout.write) are diverted to stderr so they can't corrupt a frame.
+// Returns the writer to use for protocol output.
 function isolateStdout() {
     const protocolWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = ((chunk) => process.stderr.write(chunk));
+    // Forward encoding/callback (and the function-as-second-arg overload), not just chunk.
+    process.stdout.write = ((chunk, encoding, callback) => typeof encoding === "function"
+        ? process.stderr.write(chunk, encoding)
+        : process.stderr.write(chunk, encoding, callback));
     return (chunk) => protocolWrite(chunk);
 }
 function readStdin() {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0";
-export declare const RENDER_PROTOCOL_VERSION = 2;
+export declare const VERSION = "0.4.0";
+export declare const RENDER_PROTOCOL_VERSION = 3;

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.2.0";
-export const RENDER_PROTOCOL_VERSION = 2;
+export const VERSION = "0.4.0";
+export const RENDER_PROTOCOL_VERSION = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-email-rails",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Build and send emails using React and Rails",
   "license": "MIT",
   "type": "module",
@@ -64,6 +64,9 @@
     "@react-email/editor": "^1.5",
     "@react-email/render": "^2.0.0",
     "@tiptap/core": "^3",
+    "@tiptap/html": "^3",
+    "happy-dom": "^20.8.9",
+    "marked": "^18",
     "react": "^18.0 || ^19.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
@@ -73,15 +76,28 @@
     },
     "@tiptap/core": {
       "optional": true
+    },
+    "@tiptap/html": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
+    },
+    "marked": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@react-email/editor": "^1.5.3",
     "@react-email/render": "^2.0.8",
     "@tiptap/core": "^3",
+    "@tiptap/html": "^3",
+    "@tiptap/pm": "^3",
     "@types/node": "^25.9.1",
     "@types/react": "^19.2.15",
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "happy-dom": "^20.8.9",
+    "marked": "^18.0.5",
     "oxfmt": "^0.52.0",
     "oxlint": "^1.67.0",
     "oxlint-tsgolint": "^0.23.0",

package/src/document.ts

@@ -4,9 +4,16 @@ import { EmailTheming } from "@react-email/editor/plugins"
 import { getSchema, resolveExtensions, type Extensions } from "@tiptap/core"
 import type { Editor } from "@tiptap/core"
 
-import type { DroppedNode, RenderResult } from "./runtime.js"
+import type {
+  DroppedNode,
+  ParseDocumentRequest,
+  ParseResult,
+  RenderDocumentRequest,
+  RenderResult,
+} from "./runtime.js"
 
-export type { DroppedNode }
+// Re-exported from runtime.ts (the single source) to keep react-email-rails/document's surface.
+export type { DroppedNode, ParseDocumentRequest, RenderDocumentRequest }
 
 export type DocumentRenderer = {
   buildExtensions: (context: unknown) => Extensions
@@ -22,9 +29,8 @@ const STRUCTURAL_NODE_TYPES: ReadonlySet<string> = new Set(
     .map((extension) => extension.name),
 )
 
-// composeReactEmail renders a node as null when no extension matches its type or
-// the match is not an EmailNode. Mirror that predicate over the document so
-// warnings report the silent case: an in-schema node with no email renderer.
+// composeReactEmail renders a node as null when no extension matches or the match isn't an
+// EmailNode; mirror that here so warnings catch the silent case (in-schema node, no email renderer).
 function collectDroppedNodes(document: unknown, extensions: Extensions): DroppedNode[] {
   const byName = new Map<string, Extensions[number]>()
   for (const extension of extensions) byName.set(extension.name, extension)
@@ -53,12 +59,83 @@ function collectDroppedNodes(document: unknown, extensions: Extensions): Dropped
 export type DocumentLoader = DocumentRenderer | (() => Promise<DocumentRenderer>)
 export type DocumentRegistry = Record<string, DocumentLoader>
 
-export type RenderDocumentRequest = {
-  kind: "document"
-  type: string
-  document: unknown
-  context?: unknown
-  preview?: string | null
+type GenerateJSON = (html: string, extensions: Extensions) => unknown
+type RenderMarkdown = (markdown: string) => string | Promise<string>
+
+// Bound at build time by createParseDocument when the peers are bundled; lazy-loaded otherwise.
+type ParseDependencies = {
+  generateJSON?: GenerateJSON
+  renderMarkdown?: RenderMarkdown
+}
+
+async function resolveRenderer(
+  type: string,
+  registry: DocumentRegistry,
+): Promise<DocumentRenderer> {
+  const loader = registry[type]
+  if (!loader) throw new Error(`React email document renderer not found: ${type}`)
+
+  const renderer = typeof loader === "function" ? await loader() : loader
+  if (typeof renderer.buildExtensions !== "function") {
+    throw new Error(`React email document renderer must export a buildExtensions function: ${type}`)
+  }
+
+  return renderer
+}
+
+async function loadGenerateJSON(): Promise<GenerateJSON> {
+  try {
+    const mod = (await import(/* @vite-ignore */ "@tiptap/html")) as {
+      generateJSON?: unknown
+    }
+    if (typeof mod.generateJSON === "function") return mod.generateJSON as GenerateJSON
+  } catch (error) {
+    throw new Error(
+      `@tiptap/html and happy-dom are required to parse HTML documents; install both packages before calling parse (${error instanceof Error ? error.message : "module load failed"})`,
+    )
+  }
+
+  throw new Error(
+    "@tiptap/html is missing the expected generateJSON export; check the installed version",
+  )
+}
+
+async function loadRenderMarkdown(): Promise<RenderMarkdown> {
+  try {
+    const mod = (await import(/* @vite-ignore */ "marked")) as {
+      marked?: { parse?: (markdown: string) => string | Promise<string> }
+    }
+    const marked = mod.marked
+    if (marked && typeof marked.parse === "function") {
+      const parse = marked.parse.bind(marked)
+      return (markdown) => parse(markdown)
+    }
+  } catch (error) {
+    throw new Error(
+      `marked is required to parse Markdown documents; install it before calling parse with markdown (${error instanceof Error ? error.message : "module load failed"})`,
+    )
+  }
+
+  throw new Error("marked is missing the expected parse export; check the installed version")
+}
+
+// Both inputs converge on HTML: markdown is rendered first, then parsed like any HTML.
+async function resolveHtmlInput(
+  request: ParseDocumentRequest,
+  dependencies: ParseDependencies,
+): Promise<string> {
+  const hasHtml = request.html !== undefined
+  const hasMarkdown = request.markdown !== undefined
+  if (hasHtml === hasMarkdown) {
+    throw new Error("parse request must include exactly one of `html` or `markdown`")
+  }
+
+  if (hasMarkdown) {
+    const renderMarkdown = dependencies.renderMarkdown ?? (await loadRenderMarkdown())
+    return renderMarkdown(request.markdown as string)
+  }
+
+  return request.html as string
 }
 
 export async function composeDocument(
@@ -76,15 +153,7 @@ export async function composeDocument(
     )
   }
 
-  const loader = registry[request.type]
-  if (!loader) throw new Error(`React email document renderer not found: ${request.type}`)
-
-  const renderer = typeof loader === "function" ? await loader() : loader
-  if (typeof renderer.buildExtensions !== "function") {
-    throw new Error(
-      `React email document renderer must export a buildExtensions function: ${request.type}`,
-    )
-  }
+  const renderer = await resolveRenderer(request.type, registry)
 
   const document =
     renderer.transformDocument?.(request.document, request.context) ?? request.document
@@ -108,3 +177,28 @@ export async function composeDocument(
   const { html, text } = await composeReactEmail(params)
   return warnings.length > 0 ? { html, text, warnings } : { html, text }
 }
+
+export async function parseDocument(
+  request: ParseDocumentRequest,
+  registry: DocumentRegistry,
+  dependencies: ParseDependencies = {},
+): Promise<ParseResult> {
+  const renderer = await resolveRenderer(request.type, registry)
+  const extensions = resolveExtensions(renderer.buildExtensions(request.context))
+  const schema = getSchema(extensions)
+
+  const html = await resolveHtmlInput(request, dependencies)
+  const parseHTML = dependencies.generateJSON ?? (await loadGenerateJSON())
+  const parsed = parseHTML(html, extensions)
+  const document = schema.nodeFromJSON(parsed).toJSON()
+
+  return { document }
+}
+
+export function createParseDocument(generateJSON: GenerateJSON, renderMarkdown?: RenderMarkdown) {
+  // Omit renderMarkdown entirely when unset; exactOptionalPropertyTypes forbids passing `undefined`.
+  const dependencies: ParseDependencies =
+    renderMarkdown === undefined ? { generateJSON } : { generateJSON, renderMarkdown }
+  return (request: ParseDocumentRequest, registry: DocumentRegistry): Promise<ParseResult> =>
+    parseDocument(request, registry, dependencies)
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module"
+
 import type { ConfigEnv, Plugin, UserConfig } from "vite"
 
 export type EmailsOption =
@@ -10,8 +12,7 @@ export type EmailsOption =
 
 export type ReactEmailRailsOptions = {
   emails?: EmailsOption
-  // Editor document renderers, discovered like emails. Off by default; pass `true`
-  // to enable with defaults, or a path/options object to customize discovery.
+  // Editor document renderers, discovered like emails. Off by default.
   documents?: EmailsOption | boolean
   standalone?: boolean
   vite?: ReactEmailRailsViteOptions
@@ -60,10 +61,21 @@ const VIRTUAL_MODULE_PATTERN = /virtual:react-email-rails\/(?:server|main)$/
 
 // The dedicated build environment that emits the server-side email bundle.
 export const EMAIL_ENVIRONMENT = "email"
+// Wire contract: must match the Symbol.for(...) keys the bins read in bin/shared.mjs.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config")
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite")
+// Must match Ruby's Configuration::BUNDLE_PATH (check_version_sync.rb asserts it).
 const OUT_DIR = "tmp/react-email-rails"
 const BUNDLE_FILE = "emails.js"
+const require = createRequire(import.meta.url)
+
+// happy-dom (via @tiptap/html) pulls in `ws`, which guards optional native-addon requires behind
+// these flags. Setting them lets a standalone (noExternal) build tree-shake the uninstalled
+// bufferutil/utf-8-validate requires away; ws's pure-JS path is all the HTML parser needs.
+const WS_NATIVE_ADDON_OPT_OUT = {
+  "process.env.WS_NO_BUFFER_UTIL": "'1'",
+  "process.env.WS_NO_UTF_8_VALIDATE": "'1'",
+}
 
 function normalizeSource(
   option: EmailsOption | undefined,
@@ -101,6 +113,17 @@ function normalizeSource(
   return { path, extensions, ignore, root, globArg }
 }
 
+function optionalPeersAvailable(specifiers: string[]): boolean {
+  return specifiers.every((specifier) => {
+    try {
+      require.resolve(specifier)
+      return true
+    } catch {
+      return false
+    }
+  })
+}
+
 export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
   const emailSource = normalizeSource(options.emails, DEFAULT_EMAIL_PATH, DEFAULT_EMAIL_EXTENSIONS)
   const documentSource =
@@ -128,32 +151,32 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       filter: { id: VIRTUAL_MODULE_PATTERN },
       handler(id) {
         if (id === RESOLVED_SERVER) {
-          const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`]
+          const lines = [`import { buildRegistry, serve } from "react-email-rails/runtime"`]
+          const parserPeersAvailable =
+            documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"])
+          // Markdown parsing layers `marked` on top of the HTML parser peers.
+          const markdownPeerAvailable = parserPeersAvailable && optionalPeersAvailable(["marked"])
 
-          // Imported only here, so the editor stays out of the email build graph when off.
-          if (documentSource)
-            lines.push(`import { composeDocument } from "react-email-rails/document"`)
+          if (documentSource) {
+            lines.push(
+              parserPeersAvailable
+                ? `import { composeDocument, createParseDocument } from "react-email-rails/document"`
+                : `import { composeDocument, parseDocument } from "react-email-rails/document"`,
+            )
+            if (parserPeersAvailable) {
+              lines.push(`import { generateJSON } from "@tiptap/html"`)
+              if (markdownPeerAvailable) lines.push(`import { marked } from "marked"`)
+            }
+          }
 
           lines.push(
-            `const modules = import.meta.glob(${emailSource.globArg})`,
-            `const extensions = ${JSON.stringify(emailSource.extensions)}`,
-            `const registry = Object.create(null)`,
-            `for (const path in modules) {`,
-            `  const extension = extensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`,
-            `  registry[toComponentName(path, ${JSON.stringify(emailSource.root)}, extension)] = modules[path]`,
-            `}`,
+            `const registry = buildRegistry(import.meta.glob(${emailSource.globArg}), ${JSON.stringify(emailSource.extensions)}, ${JSON.stringify(emailSource.root)})`,
           )
 
           if (documentSource) {
             lines.push(
-              `const documentModules = import.meta.glob(${documentSource.globArg})`,
-              `const documentExtensions = ${JSON.stringify(documentSource.extensions)}`,
-              `const documentRegistry = Object.create(null)`,
-              `for (const path in documentModules) {`,
-              `  const extension = documentExtensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`,
-              `  documentRegistry[toComponentName(path, ${JSON.stringify(documentSource.root)}, extension)] = documentModules[path]`,
-              `}`,
-              `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument })`,
+              `const documentRegistry = buildRegistry(import.meta.glob(${documentSource.globArg}), ${JSON.stringify(documentSource.extensions)}, ${JSON.stringify(documentSource.root)})`,
+              `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument, parse: ${parserPeersAvailable ? `createParseDocument(generateJSON${markdownPeerAvailable ? ", (markdown) => marked.parse(markdown)" : ""})` : "parseDocument"} })`,
             )
           } else {
             lines.push(`export const run = () => serve(registry)`)
@@ -169,17 +192,15 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
     },
 
     config(_config, env: ConfigEnv) {
-      // Register a dedicated `email` build environment. The official
-      // react-email-rails-build bin opts into building it with an isolated
-      // plugin stack so host app plugins cannot break email SSR builds.
-      // The environment is a server consumer. Production standalone builds inline
-      // Node dependencies by default so Rails runtime images do not need
-      // node_modules; dev rendering keeps dependencies external for Vite's module
-      // runner.
+      // Dedicated `email` build environment: the react-email-rails-build bin builds it with an
+      // isolated plugin stack so host plugins can't break email SSR. Standalone builds inline
+      // Node deps (so Rails images need no node_modules); dev keeps them external for the runner.
       return {
         environments: {
           [EMAIL_ENVIRONMENT]: {
-            ...(standalone && env.command === "build" ? { resolve: { noExternal: true } } : {}),
+            ...(standalone && env.command === "build"
+              ? { resolve: { noExternal: true }, define: WS_NATIVE_ADDON_OPT_OUT }
+              : {}),
             build: {
               ssr: true,
               outDir: OUT_DIR,

package/src/runtime.ts

@@ -33,18 +33,28 @@ export type RenderDocumentRequest = {
   preview?: string | null
 }
 
+// Exactly one of `html` or `markdown` is set.
+export type ParseDocumentRequest = {
+  kind: "parse"
+  type: string
+  html?: string
+  markdown?: string
+  context?: unknown
+}
+
 // A document node type that rendered to nothing, with how many times it occurred.
 export type DroppedNode = { type: string; count: number }
 
-// A render result plus any non-fatal warnings (document nodes dropped because no
-// extension rendered them). Component renders never carry warnings.
+// A render result plus non-fatal warnings (dropped document nodes); component renders carry none.
 export type RenderResult = RenderedEmail & { warnings?: DroppedNode[] }
 
-// Injected by the generated server module when documents are enabled, so `serve`
-// renders documents without importing the editor module or its peer types.
+export type ParseResult = { document: unknown }
+
+// Injected by the generated server module so `serve` renders documents without importing the editor module.
 export type DocumentSupport<Registry = unknown> = {
   registry: Registry
   compose: (request: RenderDocumentRequest, registry: Registry) => Promise<RenderResult>
+  parse: (request: ParseDocumentRequest, registry: Registry) => Promise<ParseResult>
 }
 
 type ProtocolMetadata = {
@@ -62,6 +72,21 @@ export function toComponentName(globPath: string, root: string, extension: strin
   return globPath.slice(start, globPath.length - extension.length)
 }
 
+// Map glob results to a component-name registry (used for both email and document registries).
+export function buildRegistry(
+  modules: EmailRegistry,
+  extensions: string[],
+  root: string,
+): EmailRegistry {
+  const registry: EmailRegistry = Object.create(null)
+  for (const [path, loader] of Object.entries(modules)) {
+    const extension =
+      extensions.find((ext) => path.endsWith(ext)) ?? path.slice(path.lastIndexOf("."))
+    registry[toComponentName(path, root, extension)] = loader
+  }
+  return registry
+}
+
 export async function renderEmail(
   request: RenderRequest,
   registry: EmailRegistry,
@@ -83,7 +108,14 @@ function isDocumentRequest(request: unknown): request is RenderDocumentRequest {
   return (
     request !== null &&
     typeof request === "object" &&
-    (request as { kind?: unknown }).kind === "document"
+    "kind" in request &&
+    request.kind === "document"
+  )
+}
+
+function isParseRequest(request: unknown): request is ParseDocumentRequest {
+  return (
+    request !== null && typeof request === "object" && "kind" in request && request.kind === "parse"
   )
 }
 
@@ -91,17 +123,21 @@ function isHealthRequest(request: unknown): request is HealthRequest {
   return request !== null && typeof request === "object" && "health" in request
 }
 
-// Requests without a document kind are component renders, preserving the email path.
 async function renderRequest<Registry>(
-  request: RenderRequest | RenderDocumentRequest,
+  request: RenderRequest | RenderDocumentRequest | ParseDocumentRequest,
   registry: EmailRegistry,
   documents: DocumentSupport<Registry> | null,
-): Promise<RenderResult> {
+): Promise<RenderResult | ParseResult> {
   if (isDocumentRequest(request)) {
     if (!documents) throw new Error("React email document rendering is not enabled")
     return documents.compose(request, documents.registry)
   }
 
+  if (isParseRequest(request)) {
+    if (!documents) throw new Error("React email document rendering is not enabled")
+    return documents.parse(request, documents.registry)
+  }
+
   return renderEmail(request, registry)
 }
 
@@ -121,7 +157,10 @@ export async function serve<Registry = unknown>(
 
   const write = isolateStdout()
   try {
-    const request = JSON.parse(await readStdin()) as RenderRequest | RenderDocumentRequest
+    const request = JSON.parse(await readStdin()) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
     write(
       JSON.stringify({
         ...(await renderRequest(request, registry, documents)),
@@ -134,14 +173,16 @@ export async function serve<Registry = unknown>(
   }
 }
 
-// Reserve stdout for the JSON render protocol. Stray writes from email components
-// or their dependencies — including console.log, which Node routes through
-// process.stdout.write — are diverted to stderr so they cannot corrupt or desync
-// a response frame. Returns the writer to use for protocol output.
+// Reserve stdout for the JSON render protocol: stray writes (e.g. console.log, which Node
+// routes through process.stdout.write) are diverted to stderr so they can't corrupt a frame.
+// Returns the writer to use for protocol output.
 function isolateStdout(): (chunk: string) => boolean {
   const protocolWrite = process.stdout.write.bind(process.stdout)
-  process.stdout.write = ((chunk: string | Uint8Array): boolean =>
-    process.stderr.write(chunk)) as typeof process.stdout.write
+  // Forward encoding/callback (and the function-as-second-arg overload), not just chunk.
+  process.stdout.write = ((chunk, encoding, callback) =>
+    typeof encoding === "function"
+      ? process.stderr.write(chunk, encoding)
+      : process.stderr.write(chunk, encoding, callback)) as typeof process.stdout.write
   return (chunk) => protocolWrite(chunk)
 }
 
@@ -186,7 +227,11 @@ async function writePersistentResponse<Registry>(
   write: (chunk: string) => boolean,
 ): Promise<void> {
   try {
-    const request = JSON.parse(line) as RenderRequest | RenderDocumentRequest | HealthRequest
+    const request = JSON.parse(line) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
+      | HealthRequest
     if (isHealthRequest(request)) {
       write(`${JSON.stringify(okResponse())}\n`)
       return

package/src/version.ts

@@ -1,2 +1,2 @@
-export const VERSION = "0.2.0"
-export const RENDER_PROTOCOL_VERSION = 2
+export const VERSION = "0.4.0"
+export const RENDER_PROTOCOL_VERSION = 3