react-email-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52da00b9618d5b217b66af2598edf2a25fa9d0850447bfc95d8637c778837583
-  data.tar.gz: 84bcdbd09672b293b85d65bbde9779c0d0d2c2c282dd83e72cc2412d38150c6b
+  metadata.gz: 1ada860a1bfdc970fd871cb2f0d4b89642e42b8641b8d11006ca66e9bf6f452a
+  data.tar.gz: 742b838451251d7b97093077ff9909e3d60441e705a841fed522d1d64df83787
 SHA512:
-  metadata.gz: b9ce2a8643e90776bee1f37c9758fd9d853465d37b73184e0ebdeb20a87e33d9d686354b1a8256cb3bb4887221d25b7c14c9b6733d905c04e86f3fa2d1e06cc7
-  data.tar.gz: 1257c29d6639ed5a1559d23d64316bea2c6ccf075b365e816dc0bfd41cb996003e466dbabe97bc50aa9b736e2a45e81e083cd908791f91d8d94f13b239e65f67
+  metadata.gz: 2d7490d1c6bccdd3d7d7eeb5fa0f0a1d6a9888e6090bf560b2d63feab8db4edec448eb7ba6ddbc34134ed9cf1cd34e4a2cb229bf41794c44faefbafe0f98adc0
+  data.tar.gz: c2a55b22219041afe9cc25f00fa5b2ef222f4d45656027c4e971b2666d90a68f02aae4894fc30f3771b3064e41b5c880febead6d79d4cecadb0cb5bd1736e3de

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

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,12 +310,18 @@ Install the editor packages:
 npm i @react-email/editor @tiptap/core
 ```
 
-To also parse HTML into documents with [`parse`](#parsing-html-into-a-document), add `@tiptap/html` and its server DOM, `happy-dom`:
+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
@@ -342,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]
 }
@@ -368,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 {
@@ -403,9 +404,9 @@ broadcast = Broadcast.find(params[:id])
 
 rendered = ReactEmailRails.compose(
   type: "broadcast",
-  document: broadcast.body,          # a Hash in Tiptap's shape, e.g. from 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>..."
@@ -414,24 +415,24 @@ 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.
 
-**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-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.
+**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 into a Document
+### 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",                 # the same renderer type compose uses
-  html: params[:body_html],          # the HTML the caller sent
-  context: { brand_name: "Acme" },   # optional; reaches buildExtensions, like compose
+  type: "broadcast",
+  html: params[:body_html],
+  context: { brand_name: "Acme" },
 )
 
-broadcast.update!(body: document)    # persist the Hash (e.g. to a jsonb column)
+broadcast.update!(body: document)
 ```
 
 Later, render the stored document like any other:
@@ -442,10 +443,26 @@ 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.
+- 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

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"],

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,16 +2,14 @@ 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).
-  # `response` selects how the renderer's reply is interpreted: `:email` builds a
-  # RenderedEmail (render/compose), `:document` returns the parsed document (parse).
+  # `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
@@ -40,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

data/lib/react_email_rails/render_protocol.rb

@@ -1,9 +1,16 @@
+require("json")
+
 module ReactEmailRails
   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.3.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,29 +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 HTML into an editor document Hash using the renderer's extensions.
-    def parse(type:, html:, context: {})
+    # 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:,
-        html: html.to_s,
         context: serialized_props(context),
-      }
+      }.merge(parse_source(html:, markdown:))
 
-      instrument(kind: "parse", type:) do
-        configuration.resolved_render_mode.new(payload:, label: type, response: :document).render
-      end
-    rescue ReactEmailRails::RenderError => e
-      configuration.on_render_error&.call(e, kind: "parse", type:)
-      raise
+      perform(payload:, label: type, response: :document, kind: "parse", type:)
     end
 
     def healthy?
@@ -95,6 +79,27 @@ 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.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