react-email-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8de13aced1b8b88a622cdc40577ec17c80ad457cee75ea57266dc248e5355416
-  data.tar.gz: d42cacd94f77a32ccf75d72b5e8c19506549902c64617a723c6617e0bc613a58
+  metadata.gz: 1ada860a1bfdc970fd871cb2f0d4b89642e42b8641b8d11006ca66e9bf6f452a
+  data.tar.gz: 742b838451251d7b97093077ff9909e3d60441e705a841fed522d1d64df83787
 SHA512:
-  metadata.gz: 1fbbbb75215e8b4b77de4d4c15e533348e2b7195196d5b9401541596e24507b3c046ca8f74998f20b76f9fbf6d9b67d8c0ec29a86af3aaa64e0b1b70bece4c85
-  data.tar.gz: 5e7025b1552256c5d1b2fd01a911c7d941b2fd41aa6cd94ddd646fbeb79713888dd6dc13785ff71c66cadb9362877e2abe4715855630813314e7073f509ccccc
+  metadata.gz: 2d7490d1c6bccdd3d7d7eeb5fa0f0a1d6a9888e6090bf560b2d63feab8db4edec448eb7ba6ddbc34134ed9cf1cd34e4a2cb229bf41794c44faefbafe0f98adc0
+  data.tar.gz: c2a55b22219041afe9cc25f00fa5b2ef222f4d45656027c4e971b2666d90a68f02aae4894fc30f3771b3064e41b5c880febead6d79d4cecadb0cb5bd1736e3de

data/CHANGELOG.md

@@ -1,13 +1,24 @@
 # Changelog
 
+## 0.4.0
+
+- `ReactEmailRails.parse` now accepts `markdown:` as an alternative to `html:`. Markdown is converted to HTML and runs through the same extension-driven parse path, producing the same document `Hash` — handy for agent- or tool-generated content. Pass exactly one of `html:`/`markdown:`.
+- Add `marked` as an optional peer dependency, required only when calling `parse` with `markdown:`. HTML parsing and compose-only rendering do not require it.
+
+## 0.3.0
+
+- Add `ReactEmailRails.parse` to convert semantic HTML into a canonical `@react-email/editor` document using a renderer's extensions.
+- Add `@tiptap/html` and `happy-dom` as optional peer dependencies, required only when calling `parse`; compose-only document rendering does not require them.
+- Bump the render protocol to 3 (the renderer now accepts parse requests). The Ruby gem and npm package must be upgraded together, as before.
+
 ## 0.2.0
 
-- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents (Tiptap/ProseMirror JSON) to HTML and text, the server analog of the editor's client-side `composeReactEmail` export.
-- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`. It is off by default; the editor packages stay out of the email render path and build graph unless it is enabled.
-- Report document nodes that render to nothing (a node whose extension is not an email renderer) as non-fatal warnings — on the result (`rendered.warnings`) and the `render.react-email-rails` instrumentation payload (`payload[:warnings]`) — so silently dropped content is detectable.
+- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents to HTML and text.
+- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`.
+- Report document nodes that render to nothing as non-fatal warnings on the result and instrumentation payload.
 - Add `@react-email/editor` and `@tiptap/core` as optional peer dependencies (only required when rendering documents).
 - Bump the render protocol to 2 (the renderer now accepts document requests). The Ruby gem and npm package must be upgraded together, as before.
-- **Breaking:** `on_render_error` callbacks now receive a uniform `(error, **context)` shape, where `context` carries `kind:` (`"email"`/`"document"`) and either `component:` (emails) or `type:` (documents). Update `->(error, component:) { ... }` callbacks to `->(error, **context) { ... }`.
+- **Breaking:** `on_render_error` callbacks now receive `(error, **context)` with `kind:` plus `component:` for emails or `type:` for documents.
 
 ## 0.1.3
 

data/README.md

@@ -44,7 +44,6 @@ React Email Rails automatically renders both HTML and plain-text versions from t
 - Vite 7 or 8
 - React 18 or 19
 - `@react-email/render` 2.x
-- For [rendering editor documents](#editor) (optional): `@react-email/editor` 1.5+ and `@tiptap/core` 3.x
 
 > We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite with Rails.
 
@@ -311,6 +310,18 @@ Install the editor packages:
 npm i @react-email/editor @tiptap/core
 ```
 
+To also parse HTML into documents with [`parse`](#parsing-html-or-markdown-into-a-document), add `@tiptap/html` and its server DOM, `happy-dom`:
+
+```sh
+npm i @tiptap/html happy-dom
+```
+
+To parse Markdown as well, add [`marked`](https://marked.js.org) — it converts Markdown to HTML, which then runs through the same parser:
+
+```sh
+npm i marked
+```
+
 Enable the `documents` option in your Vite config:
 
 ```ts
@@ -336,7 +347,6 @@ A document doesn't carry the editor configuration it was authored with, so a hea
 import { StarterKit } from "@react-email/editor/extensions"
 import { EmailTheming } from "@react-email/editor/plugins"
 
-// Required: the Tiptap extensions the document was authored with.
 export function buildExtensions() {
   return [StarterKit, EmailTheming]
 }
@@ -362,15 +372,12 @@ export function buildExtensions(context) {
   return [StarterKit, EmailTheming]
 }
 
-// Inject a branded header after the persisted theme node, wherever it sits.
 export function transformDocument(document, context) {
   const header = {
     type: "heading",
     attrs: { level: 1 },
     content: [{ type: "text", text: context.brandName }],
   }
-  // Find globalContent and insert after it, rather than assuming a position, so
-  // the theme node is preserved.
   const themeIndex = document.content.findIndex((node) => node.type === "globalContent")
   const at = themeIndex + 1
   return {
@@ -397,9 +404,9 @@ broadcast = Broadcast.find(params[:id])
 
 rendered = ReactEmailRails.compose(
   type: "broadcast",
-  document: broadcast.body,          # Tiptap JSON, e.g. a jsonb column
+  document: broadcast.body,
   context: { brand_name: "Acme", preview_text: broadcast.subject },
-  preview: broadcast.subject,        # optional; falls back to getPreview(context)
+  preview: broadcast.subject,
 )
 
 rendered.html # => "<!DOCTYPE html>..."
@@ -408,10 +415,56 @@ rendered.text # => "ACME\n\n..."
 
 It returns the same `RenderedEmail` (`html`/`text`) as `render`, runs through the same [render modes](#render-modes), and raises `ReactEmailRails::RenderError` on failure. Documents don't go through Action Mailer — broadcasts and the like usually have their own delivery path — so deliver `rendered.html`/`rendered.text` however your app sends mail.
 
-**Keys:** `context` is key-transformed exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)). The **`document` is passed through verbatim** — its keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and are never transformed.
+**The document is a `Hash`.** You pass and store it as a plain Ruby `Hash` with string keys — what a jsonb column hands back, and what [`parse`](#parsing-html-or-markdown-into-a-document) returns. "Tiptap JSON" names the document's *shape* (and the format it's serialized to over the wire to the renderer), not the Ruby type; `compose` accepts any object that responds to `as_json`, but a `Hash` is the norm.
+
+**Keys:** the document's keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and **passed through verbatim** — never transformed. Only `context` is key-transformed, camelized exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)).
 
 `render_options` does not apply to documents; `composeReactEmail` controls its own rendering.
 
+### Parsing HTML or Markdown into a Document
+
+`ReactEmailRails.parse` converts semantic HTML into the same document `Hash` shape the editor stores, using the selected renderer's extensions. This needs the `@tiptap/html` and `happy-dom` packages (see [Setup](#setup)).
+
+```ruby
+document = ReactEmailRails.parse(
+  type: "broadcast",
+  html: params[:body_html],
+  context: { brand_name: "Acme" },
+)
+
+broadcast.update!(body: document)
+```
+
+Later, render the stored document like any other:
+
+```ruby
+rendered = ReactEmailRails.compose(type: "broadcast", document: broadcast.body)
+```
+
+`parse` returns a plain Ruby `Hash` with string keys, normalized through the renderer's schema. It uses the same [render modes](#render-modes) as `compose` and raises `ReactEmailRails::RenderError` on failure. `context` is key-transformed like component props; the HTML is sent verbatim.
+
+#### Markdown
+
+Pass `markdown:` in place of `html:` to parse Markdown — useful when the content comes from an LLM or another tool that emits Markdown more readily than HTML. It's converted to HTML with [`marked`](https://marked.js.org) and run through the same parse path, so it needs `marked` installed alongside the HTML peers (see [Setup](#setup)).
+
+```ruby
+document = ReactEmailRails.parse(
+  type: "broadcast",
+  markdown: "# Welcome\n\nThanks for signing up, **Ada**.",
+  context: { brand_name: "Acme" },
+)
+```
+
+Pass exactly one of `html:` or `markdown:` — passing both, or neither, raises `ArgumentError`.
+
+Markdown is a lower-friction *input*, not a wider one. It expresses less than HTML — headings, paragraphs, emphasis, links, lists, blockquotes, code, images, and rules — so it adds no new node types. Markdown that maps to nodes the renderer's extensions don't define (such as a GFM table without a table extension) is dropped or flattened, the same as the equivalent HTML.
+
+What this means in practice:
+
+- HTML maps to a node only when an extension defines how to parse it. Unknown elements, inline styles, and classes may be dropped or flattened.
+- Editor-only constructs such as custom email nodes and the persisted `globalContent` theme node do not round-trip from plain HTML or Markdown.
+- If you already have the document `Hash`, pass it to `compose` directly.
+
 ### Debugging Dropped Content
 
 The most common integration bug is an extension/document mismatch. A node whose type is **missing from `buildExtensions` entirely** raises `ReactEmailRails::RenderError` (it can't be parsed) — loud and safe. The quiet case is a node that *is* in the schema but whose extension does not render to email (a plain Tiptap node rather than an email one): `composeReactEmail` renders it as nothing, with no error.
@@ -510,7 +563,7 @@ end
 
 #### Error Reporting
 
-Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error and a `context` of `kind:` (`"email"` or `"document"`) plus the identifier — `component:` for emails, `type:` for documents. Accept `**context` so one handler covers both render kinds:
+Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error and a `context` of `kind:` (`"email"`, `"document"`, or `"parse"`) plus the identifier — `component:` for emails, `type:` for documents and parse requests. Accept `**context` so one handler covers every render kind:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -522,7 +575,7 @@ end
 
 #### Instrumentation
 
-Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries a `kind` (`"email"` or `"document"`), the `component` name (email) or `type` (document), and, on success, the rendered HTML size in `html_bytes`. Document renders that drop content also include `warnings` (see [Debugging Dropped Content](#debugging-dropped-content)):
+Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries a `kind` (`"email"`, `"document"`, or `"parse"`), the `component` name (email) or `type` (document and parse), and, on a successful render, the rendered HTML size in `html_bytes` (omitted for `parse`, which returns a document rather than HTML). Document renders that drop content also include `warnings` (see [Debugging Dropped Content](#debugging-dropped-content)):
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|

data/lib/generators/react_email_rails/email_generator.rb

@@ -2,11 +2,14 @@ require("rails/generators/named_base")
 require("json")
 require("open3")
 require("timeout")
+require_relative("vite_config_files")
 
 module ReactEmailRails; end
 module ReactEmailRails::Generators; end
 
 class ReactEmailRails::Generators::EmailGenerator < Rails::Generators::NamedBase
+  CONFIG_BIN = "node_modules/.bin/react-email-rails-config"
+
   source_root(File.expand_path("templates/email", __dir__))
 
   argument(:actions, type: :array, default: [], banner: "method method")
@@ -80,7 +83,7 @@ class ReactEmailRails::Generators::EmailGenerator < Rails::Generators::NamedBase
   end
 
   def component_base_path
-    File.join(emails_path, "#{file_path}_mailer")
+    File.join(emails_path, mailer_file_path)
   end
 
   def emails_path
@@ -131,47 +134,50 @@ class ReactEmailRails::Generators::EmailGenerator < Rails::Generators::NamedBase
 
   def vite_config_command
     [
-      "node_modules/.bin/react-email-rails-config",
-      "node_modules/.bin/react-email-rails-config.cmd",
+      CONFIG_BIN,
+      "#{CONFIG_BIN}.cmd",
     ].find { |path| File.exist?(File.join(destination_root, path)) }
   end
 
+  # The reactEmailRails({ ... }) plugin call, up to the option key being scanned for.
+  PLUGIN_OPENING = /reactEmailRails\s*\(\s*\{.*?/m
+
   def emails_path_from_vite_config
     source = vite_config_source
     return unless source
 
-    source[
-      /reactEmailRails\s*\(\s*\{.*?emails:\s*["']([^"']+)["']/m,
-      1,
-    ] || source[
-      /reactEmailRails\s*\(\s*\{.*?emails:\s*\{.*?path:\s*["']([^"']+)["']/m,
-      1,
-    ]
+    first_capture(
+      source,
+      /#{PLUGIN_OPENING}emails:\s*["']([^"']+)["']/m,
+      /#{PLUGIN_OPENING}emails:\s*\{.*?path:\s*["']([^"']+)["']/m,
+    )
   end
 
   def extension_from_vite_config
     source = vite_config_source
     return unless source
 
-    source[
-      /reactEmailRails\s*\(\s*\{.*?emails:\s*\{.*?extension:\s*["']([^"']+)["']/m,
-      1,
-    ] || source[
-      /reactEmailRails\s*\(\s*\{.*?emails:\s*\{.*?extension:\s*\[\s*["']([^"']+)["']/m,
-      1,
-    ]
+    first_capture(
+      source,
+      /#{PLUGIN_OPENING}emails:\s*\{.*?extension:\s*["']([^"']+)["']/m,
+      /#{PLUGIN_OPENING}emails:\s*\{.*?extension:\s*\[\s*["']([^"']+)["']/m,
+    )
+  end
+
+  # First capture-group match across an ordered list of patterns, or nil.
+  def first_capture(source, *patterns)
+    patterns.each do |pattern|
+      match = source[pattern, 1]
+      return match if match
+    end
+    nil
   end
 
   def vite_config_source
     @vite_config_source ||= begin
-      path = [
-        "vite.config.ts",
-        "vite.config.mts",
-        "vite.config.js",
-        "vite.config.mjs",
-        "vite.config.cts",
-        "vite.config.cjs",
-      ].find { |candidate| File.exist?(File.join(destination_root, candidate)) }
+      path = ReactEmailRails::Generators::VITE_CONFIG_FILES.find do |candidate|
+        File.exist?(File.join(destination_root, candidate))
+      end
 
       File.read(File.join(destination_root, path)) if path
     end

data/lib/generators/react_email_rails/install_generator.rb

@@ -1,4 +1,5 @@
 require("json")
+require_relative("vite_config_files")
 
 module ReactEmailRails; end
 module ReactEmailRails::Generators; end
@@ -21,14 +22,7 @@ class ReactEmailRails::Generators::InstallGenerator < Rails::Generators::Base
   }.freeze
 
   SUPPORTED_PACKAGE_MANAGERS = ["bun", "npm", "pnpm", "yarn"].freeze
-  VITE_CONFIG_FILES = [
-    "vite.config.ts",
-    "vite.config.mts",
-    "vite.config.js",
-    "vite.config.mjs",
-    "vite.config.cts",
-    "vite.config.cjs",
-  ].freeze
+  VITE_CONFIG_FILES = ReactEmailRails::Generators::VITE_CONFIG_FILES
 
   VITE_IMPORT = 'import { reactEmailRails } from "react-email-rails"'
 

data/lib/generators/react_email_rails/vite_config_files.rb

@@ -0,0 +1,14 @@
+module ReactEmailRails; end
+module ReactEmailRails::Generators; end
+
+module ReactEmailRails::Generators
+  # Candidate Vite config filenames in precedence order; shared by both generators.
+  VITE_CONFIG_FILES = [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.cts",
+    "vite.config.cjs",
+  ].freeze
+end

data/lib/react_email_rails/configuration.rb

@@ -1,6 +1,8 @@
 class ReactEmailRails::Configuration
+  # Must match OUT_DIR/BUNDLE_FILE in vite/src/index.ts (check_version_sync.rb asserts it).
   BUNDLE_PATH = "tmp/react-email-rails/emails.js"
   BUILD_BIN = "node_modules/.bin/react-email-rails-build"
+  CONFIG_BIN = "node_modules/.bin/react-email-rails-config"
   DEV_RENDER_BIN = "node_modules/.bin/react-email-rails-dev"
 
   DEFAULT_RENDER_TIMEOUT = 10
@@ -33,6 +35,7 @@ class ReactEmailRails::Configuration
     :transform_props,
     :on_render_error,
   )
+
   attr_reader(
     :render_mode,
     :render_timeout,
@@ -83,6 +86,8 @@ class ReactEmailRails::Configuration
     end
   end
 
+  # A callable render_options is instance_exec'd against `context` (the mailer) when given,
+  # so it can use per-mail helpers; otherwise it's called or returned as-is.
   def resolve_render_options(context = nil)
     value =
       if render_options.respond_to?(:call) && context
@@ -93,7 +98,7 @@ class ReactEmailRails::Configuration
         render_options
       end
 
-    deep_camelize_keys(value.as_json)
+    deep_transform_keys(value.as_json, KEY_TRANSFORMS.fetch(:lower_camel))
   end
 
   private
@@ -124,15 +129,4 @@ class ReactEmailRails::Configuration
       value
     end
   end
-
-  def deep_camelize_keys(value)
-    case value
-    when Array
-      value.map { |item| deep_camelize_keys(item) }
-    when Hash
-      value.transform_keys { |key| key.to_s.camelize(:lower) }.transform_values { |item| deep_camelize_keys(item) }
-    else
-      value
-    end
-  end
 end

data/lib/react_email_rails/props_resolver.rb

@@ -34,8 +34,7 @@ class ReactEmailRails::PropsResolver
   end
 
   def assign_props
-    # `react: true` infers the component name; instance vars become props only when the
-    # mailer opts in. Without it, the component renders with no props.
+    # `react: true` infers the component; instance vars become props only when the mailer opts in.
     return {} unless mailer.class.react_email_use_instance_props
 
     mailer.instance_variables.each_with_object({}) do |ivar, props|

data/lib/react_email_rails/render_modes/persistent/command_runner.rb

@@ -1,4 +1,7 @@
 class ReactEmailRails::RenderModes::Persistent::CommandRunner
+  # Eager (not lazy) so concurrent first renders can't each create separate Mutexes.
+  @mutex = Mutex.new
+
   class << self
     def capture(command, input:, timeout:, max_requests: nil)
       server_for(command).capture(input:, timeout:, max_requests:)
@@ -6,13 +9,13 @@ class ReactEmailRails::RenderModes::Persistent::CommandRunner
 
     def healthy?(command, timeout:)
       result = server_for(command).health_check(timeout:)
-      result.status.success? && ReactEmailRails::RenderProtocol.compatible_response?(JSON.parse(result.stdout))
+      ReactEmailRails::RenderProtocol.healthy_result?(result)
     rescue StandardError
       false
     end
 
     def stop_all
-      @mutex&.synchronize do
+      @mutex.synchronize do
         @servers&.each_value(&:stop)
         @servers&.clear
       end
@@ -21,18 +24,14 @@ class ReactEmailRails::RenderModes::Persistent::CommandRunner
     private
 
     def server_for(command)
-      @mutex ||= Mutex.new
-
       @mutex.synchronize do
         reset_after_fork
         @servers[command.map(&:to_s)] ||= ReactEmailRails::RenderModes::Persistent::Server.new(command)
       end
     end
 
-    # A forked child inherits the parent's Server objects and the open pipes to
-    # the parent's render processes. Sharing those pipes interleaves requests
-    # and responses across processes, so drop them (without killing the
-    # parent-owned process) and let this process spawn its own on demand.
+    # A forked child inherits the parent's Servers and their open pipes; sharing those pipes
+    # interleaves requests across processes, so drop them without killing the parent's process.
     def reset_after_fork
       return if @owner_pid == Process.pid && @servers
 

data/lib/react_email_rails/render_modes/persistent/server.rb

@@ -1,6 +1,7 @@
 class ReactEmailRails::RenderModes::Persistent::Server
   STDERR_LIMIT = 8 * 1024
 
+  # Minimal Process::Status stand-in; only #success? is ever read.
   Status = Data.define(:success) do
     def success? = success
   end
@@ -15,29 +16,13 @@ class ReactEmailRails::RenderModes::Persistent::Server
   end
 
   def capture(input:, timeout:, max_requests:)
-    @mutex.synchronize do
+    with_retry_on_broken_pipe do
       capture_once(input:, timeout:).tap { recycle_if_needed(max_requests) }
     end
-  rescue Errno::EPIPE, IOError
-    stop
-    begin
-      @mutex.synchronize do
-        capture_once(input:, timeout:).tap { recycle_if_needed(max_requests) }
-      end
-    rescue Errno::EPIPE, IOError
-      failure("render process exited before responding")
-    end
   end
 
   def health_check(timeout:)
-    @mutex.synchronize { health_check_once(timeout:) }
-  rescue Errno::EPIPE, IOError
-    stop
-    begin
-      @mutex.synchronize { health_check_once(timeout:) }
-    rescue Errno::EPIPE, IOError
-      failure("render process exited before responding")
-    end
+    with_retry_on_broken_pipe { health_check_once(timeout:) }
   end
 
   def stop
@@ -49,30 +34,46 @@ class ReactEmailRails::RenderModes::Persistent::Server
   rescue Errno::ESRCH, Errno::EPERM
     nil
   ensure
-    [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
     @stderr_reader&.kill
-    @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
-    @stdout_buffer.clear
+    release_io
   end
 
-  # Release this process's copy of an inherited child's pipes without signalling
-  # the process itself, which is still owned by the parent that started it.
+  # Release this process's copy of an inherited child's pipes without signalling the parent-owned process.
   def abandon
-    [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
-    @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
-    @stdout_buffer.clear
+    release_io
   rescue IOError
     nil
   end
 
   private
 
+  # Shared by stop (which also kills the process) and abandon (which must not).
+  def release_io
+    [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
+    @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
+    @stdout_buffer.clear
+  end
+
+  # Run under the mutex; on a broken pipe, stop and retry once (the child respawns).
+  def with_retry_on_broken_pipe(&block)
+    @mutex.synchronize(&block)
+  rescue Errno::EPIPE, IOError
+    stop
+    begin
+      @mutex.synchronize(&block)
+    rescue Errno::EPIPE, IOError
+      failure("render process exited before responding")
+    end
+  end
+
   attr_reader(:command)
 
   def capture_once(input:, timeout:)
     response = request(input, timeout:)
     return failure(response["error"].to_s.presence || "render process failed") unless response["ok"]
 
+    # Re-serialize into the same Result.stdout contract the subprocess produces, so
+    # Subprocess#run parses and validates every render uniformly.
     success(JSON.generate(
       {
         protocolVersion: response["protocolVersion"],
@@ -81,6 +82,7 @@ class ReactEmailRails::RenderModes::Persistent::Server
         body[:html] = response["html"] if response.key?("html")
         body[:text] = response["text"] if response.key?("text")
         body[:warnings] = response["warnings"] if response.key?("warnings")
+        body[:document] = response["document"] if response.key?("document")
       end,
     ))
   rescue JSON::ParserError => e

data/lib/react_email_rails/render_modes/persistent.rb

@@ -8,20 +8,18 @@ class ReactEmailRails::RenderModes::Persistent < ReactEmailRails::RenderModes::S
   private
 
   def capture(input)
-    CommandRunner.capture(
-      command,
-      input:,
-      timeout: render_timeout,
-      max_requests: render_process_max_requests,
-    )
-  rescue Timeout::Error
-    raise(render_error("render process timed out after #{render_timeout}s"))
-  rescue Errno::ENOENT
-    raise(render_error("render command not found: #{command.inspect}"))
+    with_capture_rescues do
+      CommandRunner.capture(
+        command,
+        input:,
+        timeout: render_timeout,
+        max_requests: render_process_max_requests,
+      )
+    end
   end
 
   def render_process_max_requests
-    ReactEmailRails.configuration.send(:render_process_max_requests)
+    ReactEmailRails.configuration.render_process_max_requests
   end
 end
 

data/lib/react_email_rails/render_modes/subprocess/command_runner.rb

@@ -50,7 +50,7 @@ class ReactEmailRails::RenderModes::Subprocess::CommandRunner
 
   def terminate_process(signal, pid)
     Process.kill(signal, -pid)
-  rescue Errno::ESRCH
+  rescue Errno::ESRCH, Errno::EPERM
     nil
   end
 end

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -2,17 +2,18 @@ class ReactEmailRails::RenderModes::Subprocess
   class << self
     def healthy?(command:, timeout:)
       result = CommandRunner.capture([*command, "--health"], timeout:)
-      result.status.success? && ReactEmailRails::RenderProtocol.compatible_response?(JSON.parse(result.stdout))
+      ReactEmailRails::RenderProtocol.healthy_result?(result)
     rescue StandardError
       false
     end
   end
 
-  # Payload-agnostic transport: the caller builds and serializes the payload.
-  # `label` identifies the render in error messages (component name or document type).
-  def initialize(payload:, label:)
+  # `label` names the render in error messages. `response` reads the reply as `:email`
+  # (RenderedEmail, for render/compose) or `:document` (parsed document, for parse).
+  def initialize(payload:, label:, response: :email)
     @payload = payload
     @label = label
+    @response = response
   end
 
   def render
@@ -21,15 +22,15 @@ class ReactEmailRails::RenderModes::Subprocess
 
   private
 
-  attr_reader(:payload, :label)
+  attr_reader(:payload, :label, :response)
 
   def run
     result = capture(payload_json)
     raise(render_error(error_message(result.stderr, result.status))) unless result.status.success?
 
     body = JSON.parse(result.stdout)
-    validate_response!(body)
-    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
+    validate_metadata!(body)
+    build_result(body)
   rescue JSON::ParserError => e
     raise(render_error("render process returned invalid JSON: #{e.message}"))
   rescue KeyError => e
@@ -37,8 +38,15 @@ class ReactEmailRails::RenderModes::Subprocess
   end
 
   def capture(input)
-    validate_command!
-    CommandRunner.capture(command, input:, timeout: render_timeout)
+    with_capture_rescues do
+      validate_command!
+      CommandRunner.capture(command, input:, timeout: render_timeout)
+    end
+  end
+
+  # Shared by Persistent#capture so the transport-error messages live in one place.
+  def with_capture_rescues
+    yield
   rescue Timeout::Error
     raise(render_error("render process timed out after #{render_timeout}s"))
   rescue Errno::ENOENT
@@ -75,12 +83,31 @@ class ReactEmailRails::RenderModes::Subprocess
     raise(render_error("email bundle not found at #{bundle_path.inspect}; run react-email-rails-build before rendering React emails"))
   end
 
-  def validate_response!(body)
-    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body))) unless ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+  def validate_metadata!(body)
+    return if ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+
+    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body)))
+  end
+
+  def build_result(body)
+    response == :document ? build_document(body) : build_rendered_email(body)
+  end
 
+  def build_rendered_email(body)
     raise(KeyError.new(key: "html")) unless body.key?("html")
     raise(render_error("render process returned an invalid response: html must be a string")) unless body["html"].is_a?(String)
     raise(render_error("render process returned an invalid response: text must be a string")) if body.key?("text") && !body["text"].is_a?(String)
+
+    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
+  end
+
+  def build_document(body)
+    raise(KeyError.new(key: "document")) unless body.key?("document")
+
+    document = body.fetch("document")
+    raise(render_error("parse process returned an invalid response: document must be an object")) unless document.is_a?(Hash)
+
+    document
   end
 
   def warnings_from(body)

data/lib/react_email_rails/render_protocol.rb

@@ -1,9 +1,16 @@
+require("json")
+
 module ReactEmailRails
-  RENDER_PROTOCOL_VERSION = 2
+  RENDER_PROTOCOL_VERSION = 3
 
   module RenderProtocol
     extend(self)
 
+    # Callers keep their own rescue to also cover failures obtaining the result.
+    def healthy_result?(result)
+      result.status.success? && compatible_response?(JSON.parse(result.stdout))
+    end
+
     def compatible_response?(body)
       body["ok"] == true && compatible_metadata?(body)
     end

data/lib/react_email_rails/rendered_email.rb

@@ -1,6 +1,5 @@
 module ReactEmailRails
-  # `warnings` carries non-fatal renderer warnings (e.g. document nodes dropped
-  # because no extension rendered them); empty for component renders.
+  # `warnings` are non-fatal (document nodes nothing rendered); empty for component renders.
   RenderedEmail = Data.define(:html, :text, :warnings) do
     def initialize(html:, text:, warnings: [])
       super

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/react_email_rails.rb

@@ -40,16 +40,10 @@ module ReactEmailRails
       payload = { component:, props: serialized_props(props) }
       payload[:renderOptions] = render_options if render_options.present?
 
-      instrument(kind: "email", component:) do
-        configuration.resolved_render_mode.new(payload:, label: component).render
-      end
-    rescue ReactEmailRails::RenderError => e
-      configuration.on_render_error&.call(e, kind: "email", component:)
-      raise
+      perform(payload:, label: component, kind: "email", component:)
     end
 
-    # Render an @react-email/editor document (Tiptap JSON) to HTML+text. The document
-    # is sent verbatim (its keys are structural); only context is key-transformed, like props.
+    # The document is sent verbatim (keys are structural); only context is key-transformed, like props.
     def compose(type:, document:, context: {}, preview: nil)
       payload = {
         kind: "document",
@@ -59,12 +53,19 @@ module ReactEmailRails
         preview:,
       }
 
-      instrument(kind: "document", type:) do
-        configuration.resolved_render_mode.new(payload:, label: type).render
-      end
-    rescue ReactEmailRails::RenderError => e
-      configuration.on_render_error&.call(e, kind: "document", type:)
-      raise
+      perform(payload:, label: type, kind: "document", type:)
+    end
+
+    # Parse semantic HTML or Markdown into an editor document Hash using the renderer's
+    # extensions. Pass exactly one of `html:` or `markdown:`.
+    def parse(type:, html: nil, markdown: nil, context: {})
+      payload = {
+        kind: "parse",
+        type:,
+        context: serialized_props(context),
+      }.merge(parse_source(html:, markdown:))
+
+      perform(payload:, label: type, response: :document, kind: "parse", type:)
     end
 
     def healthy?
@@ -78,15 +79,38 @@ module ReactEmailRails
 
     private
 
+    def perform(payload:, label:, response: :email, **metadata)
+      instrument(**metadata) do
+        configuration.resolved_render_mode.new(payload:, label:, response:).render
+      end
+    rescue ReactEmailRails::RenderError => e
+      configuration.on_render_error&.call(e, **metadata)
+      raise
+    end
+
+    # Markdown is converted renderer-side, not here; both inputs are sent as-is.
+    def parse_source(html:, markdown:)
+      if !html.nil? && !markdown.nil?
+        raise(ArgumentError, "ReactEmailRails.parse accepts only one of html: or markdown:")
+      end
+
+      return { html: html.to_s } unless html.nil?
+      return { markdown: markdown.to_s } unless markdown.nil?
+
+      raise(ArgumentError, "ReactEmailRails.parse requires html: or markdown:")
+    end
+
     def serialized_props(value)
       configuration.send(:serialize_props, value)
     end
 
     def instrument(**metadata)
       ActiveSupport::Notifications.instrument("render.react-email-rails", **metadata) do |payload|
-        yield.tap do |rendered|
-          payload[:html_bytes] = rendered.html.bytesize
-          payload[:warnings] = rendered.warnings if rendered.warnings.present?
+        yield.tap do |result|
+          next unless result.respond_to?(:html)
+
+          payload[:html_bytes] = result.html.bytesize
+          payload[:warnings] = result.warnings if result.warnings.present?
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Supertape
@@ -148,6 +148,7 @@ files:
 - lib/generators/react_email_rails/templates/email/mailer_test.rb.tt
 - lib/generators/react_email_rails/templates/initializer.rb
 - lib/generators/react_email_rails/templates/vite.config.ts
+- lib/generators/react_email_rails/vite_config_files.rb
 - lib/react-email-rails.rb
 - lib/react_email_rails.rb
 - lib/react_email_rails/action_mailer.rb