ironpress 1.5.2 → 1.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7511df07cf2fb2bcd059fefddd22aaf5b8f903ffda05be04f7f0fb92752d894d
-  data.tar.gz: 7e02162bdaa8acad1df3fd4822d15a46da8c3099dee2892e07f23e41e08d92d8
+  metadata.gz: '06696b437bb27adfde76adbd80dc188f172812023a436b5feca2ade84a84f0a5'
+  data.tar.gz: 939d4e115c740e813f039bbfe8d90cc845477d4ad411dcc44ed68a436b654f3d
 SHA512:
-  metadata.gz: ccd9fb149b8ac0963fb1d9f560c5f1ec9d846f8a556e18ea18389008edfc99ee0599fd2a4415a64f912d8700a5d6aeb9363b85f748f4afe184e0e6c9a995a8e2
-  data.tar.gz: 6fccbd311bfdb5812c63432d5acc93cd9a29834ecd0568eb8cbc01f171e13b6ce9912393d514ea045836b57f7005b187bc7b54204f02d6b0e8eb68e58c4735e1
+  metadata.gz: 5351e3994374da27eb84f5980a648ec59d70dae33f7f565820b5c0a73838704c1f8c424479c49242ff4920a9b7acb15cfdd3aa037ff8fc2163b530c3aa934a21
+  data.tar.gz: 781112a486eefcb602499c757865950921fb581e278d113ba9c3c95f0395708acad813682117f82508d7f5d931f21aa98d51782778ad37d401a57bd6b6b5584b

data/README.md

@@ -1,35 +1,86 @@
-# Ironpress
+# ironpress for Ruby
 
-Pure Rust HTML/CSS/Markdown to PDF converter. No browser, no system dependencies.
+Generate PDF output from HTML or Markdown with a native Rust renderer. No
+browser process or system PDF dependency is required.
 
-## Installation
+[Read the complete Ruby getting-started guide](https://gastongouron.github.io/ironpress/get-started/ruby/).
 
-```ruby
-gem install ironpress
+## Requirements
+
+- Ruby 3.0 or later
+- Linux, macOS, or Windows
+
+Releases include supported native gems plus a source gem.
+
+## Install
+
+```bash
+bundle add ironpress
 ```
 
-Or in your Gemfile:
+Or install the gem globally:
 
-```ruby
-gem "ironpress"
+```bash
+gem install ironpress
 ```
 
-## Usage
+## Create your first PDF
 
 ```ruby
 require "ironpress"
 
-# HTML to PDF
-pdf = Ironpress.html_to_pdf("<h1>Hello World</h1><p>Generated with Ironpress.</p>")
+pdf = Ironpress.html_to_pdf("<h1>Hello from Ruby</h1>")
 File.binwrite("output.pdf", pdf)
+```
 
-# Markdown to PDF
-pdf = Ironpress.markdown_to_pdf("# Hello\n\nGenerated from **Markdown**.")
-File.binwrite("output.pdf", pdf)
+The result is a binary Ruby `String`. Write it with `File.binwrite`, return it
+from a web response, or store it in your application.
+
+## Render Markdown
+
+```ruby
+pdf = Ironpress.markdown_to_pdf("# Release notes\n\nEverything shipped.")
 ```
 
-## Performance
+## Configure and reuse a converter
+
+```ruby
+converter = Ironpress::HtmlConverter.new
+  .page_size("Letter")
+  .margin_sides(36, 48, 36, 48)
+  .header("Quarterly report")
+  .footer("Page {page} of {pages}")
+
+pdf = converter.convert("<h1>Results</h1>")
+markdown_pdf = converter.convert_markdown("# Results")
+```
+
+Configuration methods return the converter, so policies compose in an idiomatic
+chain. Use `convert_to_file` or `convert_markdown_to_file` for direct output.
+
+## Local resources and fonts
+
+Local URLs are denied until a canonical boundary is configured:
+
+```ruby
+converter = Ironpress::HtmlConverter.new
+  .base_path("templates")
+  .resource_root(".")
+  .add_font("Inter", File.binread("assets/Inter.ttf"))
+```
+
+Optional fallback packs enter through `add_font_pack`. Valid names are
+`cjk-jp`, `cjk-kr`, `cjk-sc`, `cjk-tc`, and `emoji`. Rendering never downloads
+a font pack.
+
+## Limits and errors
+
+- Invalid named settings raise `ArgumentError`.
+- Conversion failures raise `RuntimeError`.
+- HTML sanitization is enabled by default.
+- The binding has no async or streaming conversion API.
+- Remote HTTP document resources are not available.
+- JavaScript and browser DOM execution are not supported.
 
-- **10-100x faster** than browser-based solutions (Puppeteer, wkhtmltopdf)
-- **~5MB** native extension, no runtime dependencies
-- Instant startup, no browser process
+See the [binding capability matrix](../README.md) for the contract shared with
+Rust, Python, browser WebAssembly, and Node.js.

data/ext/ironpress/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "ironpress-ruby"
+version = "1.5.4"
+edition = "2024"
+publish = false
+description = "Ruby bindings for the Ironpress HTML-to-PDF engine"
+license = "MIT"
+repository = "https://github.com/gastongouron/ironpress"
+
+[lib]
+name = "ironpress_ruby"
+crate-type = ["cdylib"]
+
+[dependencies]
+ironpress-core = { version = "=1.5.4", package = "ironpress" }
+magnus = "0.7"
+rb-sys = { version = "0.9", default-features = false, features = ["stable-api-compiled-fallback"] }

data/ext/ironpress/extconf.rb

@@ -1,2 +1,6 @@
+# frozen_string_literal: true
+
 require "mkmf"
-create_makefile("ironpress/ironpress")
+require "rb_sys/mkmf"
+
+create_rust_makefile("ironpress/ironpress_ruby")

data/ext/ironpress/src/lib.rs

@@ -0,0 +1,238 @@
+use std::path::Path;
+
+use magnus::{Error, RString, Ruby, class, define_module, function, method, prelude::*};
+
+fn html_to_pdf(ruby: &Ruby, html: String) -> Result<RString, Error> {
+    let pdf = ironpress_core::html_to_pdf(&html)
+        .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+    Ok(ruby.str_from_slice(&pdf))
+}
+
+fn markdown_to_pdf(ruby: &Ruby, markdown: String) -> Result<RString, Error> {
+    let pdf = ironpress_core::markdown_to_pdf(&markdown)
+        .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+    Ok(ruby.str_from_slice(&pdf))
+}
+
+#[magnus::wrap(class = "Ironpress::NativeConverter", free_immediately, size)]
+struct NativeConverter {
+    converter: ironpress_core::HtmlConverter,
+}
+
+impl NativeConverter {
+    fn new() -> Self {
+        Self {
+            converter: ironpress_core::HtmlConverter::new(),
+        }
+    }
+
+    fn configured(
+        &self,
+        configure: impl FnOnce(ironpress_core::HtmlConverter) -> ironpress_core::HtmlConverter,
+    ) -> Self {
+        Self {
+            converter: configure(self.converter.clone()),
+        }
+    }
+
+    fn page_size(ruby: &Ruby, this: &Self, name: String) -> Result<Self, Error> {
+        let size = match name.to_ascii_lowercase().as_str() {
+            "a4" => ironpress_core::PageSize::A4,
+            "letter" => ironpress_core::PageSize::LETTER,
+            "legal" => ironpress_core::PageSize::LEGAL,
+            _ => {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!("unknown page size `{name}`"),
+                ));
+            }
+        };
+        Ok(this.configured(|converter| converter.page_size(size)))
+    }
+
+    fn page_size_custom(&self, width: f64, height: f64) -> Self {
+        self.configured(|converter| {
+            converter.page_size(ironpress_core::PageSize::new(width as f32, height as f32))
+        })
+    }
+
+    fn margin(&self, points: f64) -> Self {
+        self.configured(|converter| {
+            converter.margin(ironpress_core::Margin::uniform(points as f32))
+        })
+    }
+
+    fn margin_sides(&self, top: f64, right: f64, bottom: f64, left: f64) -> Self {
+        self.configured(|converter| {
+            converter.margin(ironpress_core::Margin::new(
+                top as f32,
+                right as f32,
+                bottom as f32,
+                left as f32,
+            ))
+        })
+    }
+
+    fn compress(&self, enabled: bool) -> Self {
+        self.configured(|converter| converter.compress(enabled))
+    }
+
+    fn jpeg_quality(&self, quality: u8) -> Self {
+        self.configured(|converter| converter.jpeg_quality(quality))
+    }
+
+    fn auto_resize_images(&self, enabled: bool) -> Self {
+        self.configured(|converter| converter.auto_resize_images(enabled))
+    }
+
+    fn image_dpi(&self, dpi: f64) -> Self {
+        self.configured(|converter| converter.image_dpi(dpi as f32))
+    }
+
+    fn filter_dpi(&self, dpi: f64) -> Self {
+        self.configured(|converter| converter.filter_dpi(dpi as f32))
+    }
+
+    fn mask_dpi(&self, dpi: f64) -> Self {
+        self.configured(|converter| converter.mask_dpi(dpi as f32))
+    }
+
+    fn background_raster_dpi(&self, dpi: f64) -> Self {
+        self.configured(|converter| converter.background_raster_dpi(dpi as f32))
+    }
+
+    fn occlusion_cull(&self, enabled: bool) -> Self {
+        self.configured(|converter| converter.occlusion_cull(enabled))
+    }
+
+    fn sanitize(&self, enabled: bool) -> Self {
+        self.configured(|converter| converter.sanitize(enabled))
+    }
+
+    fn add_font(&self, name: String, data: RString) -> Self {
+        // SAFETY: `data` remains rooted for this call and is copied before returning.
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        self.configured(|converter| converter.add_font(&name, bytes))
+    }
+
+    fn add_font_pack(ruby: &Ruby, this: &Self, kind: String, data: RString) -> Result<Self, Error> {
+        let kind = kind
+            .parse::<ironpress_core::FontPackKind>()
+            .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+        // SAFETY: `data` remains rooted for this call and is copied before returning.
+        let bytes = unsafe { data.as_slice() }.to_vec();
+        let pack = ironpress_core::FontPack::parse(kind, bytes)
+            .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+        Ok(this.configured(|converter| converter.add_font_pack(pack)))
+    }
+
+    fn base_path(&self, path: String) -> Self {
+        self.configured(|converter| converter.base_path(Path::new(&path)))
+    }
+
+    fn resource_root(&self, path: String) -> Self {
+        self.configured(|converter| converter.resource_root(Path::new(&path)))
+    }
+
+    fn header(&self, text: String) -> Self {
+        self.configured(|converter| converter.header(text))
+    }
+
+    fn footer(&self, text: String) -> Self {
+        self.configured(|converter| converter.footer(text))
+    }
+
+    fn convert(ruby: &Ruby, this: &Self, html: String) -> Result<RString, Error> {
+        let pdf = this
+            .converter
+            .convert(&html)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        Ok(ruby.str_from_slice(&pdf))
+    }
+
+    fn convert_markdown(ruby: &Ruby, this: &Self, markdown: String) -> Result<RString, Error> {
+        let pdf = this
+            .converter
+            .convert_markdown(&markdown)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        Ok(ruby.str_from_slice(&pdf))
+    }
+
+    fn convert_to_file(ruby: &Ruby, this: &Self, html: String, path: String) -> Result<(), Error> {
+        let pdf = this
+            .converter
+            .convert(&html)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        std::fs::write(path, pdf)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))
+    }
+
+    fn convert_markdown_to_file(
+        ruby: &Ruby,
+        this: &Self,
+        markdown: String,
+        path: String,
+    ) -> Result<(), Error> {
+        let pdf = this
+            .converter
+            .convert_markdown(&markdown)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+        std::fs::write(path, pdf)
+            .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))
+    }
+}
+
+#[magnus::init]
+fn init(_ruby: &Ruby) -> Result<(), Error> {
+    let module = define_module("Ironpress")?;
+    module.define_singleton_method("html_to_pdf", function!(html_to_pdf, 1))?;
+    module.define_singleton_method("markdown_to_pdf", function!(markdown_to_pdf, 1))?;
+
+    let class = module.define_class("NativeConverter", class::object())?;
+    class.define_singleton_method("new", function!(NativeConverter::new, 0))?;
+    class.define_method("page_size", method!(NativeConverter::page_size, 1))?;
+    class.define_method(
+        "page_size_custom",
+        method!(NativeConverter::page_size_custom, 2),
+    )?;
+    class.define_method("margin", method!(NativeConverter::margin, 1))?;
+    class.define_method("margin_sides", method!(NativeConverter::margin_sides, 4))?;
+    class.define_method("compress", method!(NativeConverter::compress, 1))?;
+    class.define_method("jpeg_quality", method!(NativeConverter::jpeg_quality, 1))?;
+    class.define_method(
+        "auto_resize_images",
+        method!(NativeConverter::auto_resize_images, 1),
+    )?;
+    class.define_method("image_dpi", method!(NativeConverter::image_dpi, 1))?;
+    class.define_method("filter_dpi", method!(NativeConverter::filter_dpi, 1))?;
+    class.define_method("mask_dpi", method!(NativeConverter::mask_dpi, 1))?;
+    class.define_method(
+        "background_raster_dpi",
+        method!(NativeConverter::background_raster_dpi, 1),
+    )?;
+    class.define_method(
+        "occlusion_cull",
+        method!(NativeConverter::occlusion_cull, 1),
+    )?;
+    class.define_method("sanitize", method!(NativeConverter::sanitize, 1))?;
+    class.define_method("add_font", method!(NativeConverter::add_font, 2))?;
+    class.define_method("add_font_pack", method!(NativeConverter::add_font_pack, 2))?;
+    class.define_method("base_path", method!(NativeConverter::base_path, 1))?;
+    class.define_method("resource_root", method!(NativeConverter::resource_root, 1))?;
+    class.define_method("header", method!(NativeConverter::header, 1))?;
+    class.define_method("footer", method!(NativeConverter::footer, 1))?;
+    class.define_method("convert", method!(NativeConverter::convert, 1))?;
+    class.define_method(
+        "convert_markdown",
+        method!(NativeConverter::convert_markdown, 1),
+    )?;
+    class.define_method(
+        "convert_to_file",
+        method!(NativeConverter::convert_to_file, 2),
+    )?;
+    class.define_method(
+        "convert_markdown_to_file",
+        method!(NativeConverter::convert_markdown_to_file, 2),
+    )?;
+    Ok(())
+}

data/lib/ironpress/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ironpress
+  VERSION = "1.5.4"
+end

data/lib/ironpress.rb

@@ -1,7 +1,73 @@
 # frozen_string_literal: true
 
-require_relative "ironpress/ironpress"
+require "rbconfig"
+require_relative "ironpress/version"
+
+ruby_api_version = RUBY_VERSION.split(".").first(2).join(".")
+versioned_extension = File.join(__dir__, "ironpress", ruby_api_version, "ironpress_ruby")
+source_extension = File.join(__dir__, "ironpress", "ironpress_ruby")
+extension_suffix = RbConfig::CONFIG.fetch("DLEXT")
+extension = if File.file?("#{versioned_extension}.#{extension_suffix}")
+              versioned_extension
+            else
+              source_extension
+            end
+require extension
 
 module Ironpress
-  VERSION = "1.4.1"
+  # Mutable Ruby facade over immutable native converter values.
+  class HtmlConverter
+    CONFIGURATION_METHODS = %i[
+      page_size
+      page_size_custom
+      margin
+      margin_sides
+      compress
+      jpeg_quality
+      auto_resize_images
+      image_dpi
+      filter_dpi
+      mask_dpi
+      background_raster_dpi
+      occlusion_cull
+      sanitize
+      add_font
+      add_font_pack
+      base_path
+      resource_root
+      header
+      footer
+    ].freeze
+
+    def initialize
+      @native = NativeConverter.new
+    end
+
+    CONFIGURATION_METHODS.each do |name|
+      define_method(name) do |*arguments|
+        @native = @native.public_send(name, *arguments)
+        self
+      end
+    end
+
+    def convert(html)
+      @native.convert(html)
+    end
+
+    def convert_markdown(markdown)
+      @native.convert_markdown(markdown)
+    end
+
+    def convert_to_file(html, path)
+      @native.convert_to_file(html, path)
+      self
+    end
+
+    def convert_markdown_to_file(markdown, path)
+      @native.convert_markdown_to_file(markdown, path)
+      self
+    end
+  end
+
+  private_constant :NativeConverter
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ironpress
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.5.4
 platform: ruby
 authors:
 - Paul Gaston Gouron
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -24,23 +24,27 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: Convert HTML, CSS, and Markdown to PDF with no browser or system dependencies.
-  Native Rust extension for maximum performance.
+description: |-
+  Convert HTML, CSS, and Markdown to PDF with no browser or system
+  dependencies. Native Rust extension for maximum performance.
 email:
 executables: []
 extensions:
 - ext/ironpress/extconf.rb
 extra_rdoc_files: []
 files:
-- Cargo.toml
 - README.md
+- ext/ironpress/Cargo.toml
 - ext/ironpress/extconf.rb
+- ext/ironpress/src/lib.rs
 - lib/ironpress.rb
-- src/lib.rs
+- lib/ironpress/version.rb
 homepage: https://github.com/gastongouron/ironpress
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://gastongouron.github.io/ironpress/get-started/ruby/
+  source_code_uri: https://github.com/gastongouron/ironpress
 post_install_message:
 rdoc_options: []
 require_paths:

data/Cargo.toml

@@ -1,13 +0,0 @@
-[package]
-name = "ironpress-ruby"
-version = "1.5.2"
-edition = "2024"
-publish = false
-
-[lib]
-name = "ironpress_ruby"
-crate-type = ["cdylib"]
-
-[dependencies]
-ironpress-core = { path = "../..", package = "ironpress" }
-magnus = "0.7"

data/src/lib.rs

@@ -1,387 +0,0 @@
-use std::cell::RefCell;
-use std::path::Path;
-
-use magnus::{
-    Error, IntoValue, RString, Ruby, Value,
-    class, define_module, function, method,
-    prelude::*,
-    typed_data,
-};
-
-fn html_to_pdf(ruby: &Ruby, html: String) -> Result<RString, Error> {
-    let pdf = ironpress_core::html_to_pdf(&html)
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-    Ok(ruby.str_from_slice(&pdf))
-}
-
-fn markdown_to_pdf(ruby: &Ruby, markdown: String) -> Result<RString, Error> {
-    let pdf = ironpress_core::markdown_to_pdf(&markdown)
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-    Ok(ruby.str_from_slice(&pdf))
-}
-
-// ---------------------------------------------------------------------------
-// Inner state for the builder -- stored inside a RefCell so magnus method
-// receivers (&self) can mutate it.
-// ---------------------------------------------------------------------------
-
-struct ConverterInner {
-    page_size: ironpress_core::types::PageSize,
-    margin: ironpress_core::types::Margin,
-    compress: Option<bool>,
-    jpeg_quality: Option<u8>,
-    auto_resize_images: Option<bool>,
-    image_dpi: Option<f32>,
-    filter_dpi: Option<f32>,
-    mask_dpi: Option<f32>,
-    background_raster_dpi: Option<f32>,
-    occlusion_cull: Option<bool>,
-    sanitize: Option<bool>,
-    custom_fonts: Vec<(String, Vec<u8>)>,
-    base_path: Option<String>,
-    resource_root: Option<String>,
-    header: Option<String>,
-    footer: Option<String>,
-}
-
-impl Default for ConverterInner {
-    fn default() -> Self {
-        Self {
-            page_size: ironpress_core::types::PageSize::default(),
-            margin: ironpress_core::types::Margin::default(),
-            compress: None,
-            jpeg_quality: None,
-            auto_resize_images: None,
-            image_dpi: None,
-            filter_dpi: None,
-            mask_dpi: None,
-            background_raster_dpi: None,
-            occlusion_cull: None,
-            sanitize: None,
-            custom_fonts: Vec::new(),
-            base_path: None,
-            resource_root: None,
-            header: None,
-            footer: None,
-        }
-    }
-}
-
-impl ConverterInner {
-    /// Build an `ironpress_core::HtmlConverter` from the accumulated state.
-    fn build(&self) -> ironpress_core::HtmlConverter {
-        let mut c = ironpress_core::HtmlConverter::new()
-            .page_size(self.page_size)
-            .margin(self.margin);
-
-        if let Some(v) = self.compress {
-            c = c.compress(v);
-        }
-        if let Some(v) = self.jpeg_quality {
-            c = c.jpeg_quality(v);
-        }
-        if let Some(v) = self.auto_resize_images {
-            c = c.auto_resize_images(v);
-        }
-        if let Some(v) = self.image_dpi {
-            c = c.image_dpi(v);
-        }
-        if let Some(v) = self.filter_dpi {
-            c = c.filter_dpi(v);
-        }
-        if let Some(v) = self.mask_dpi {
-            c = c.mask_dpi(v);
-        }
-        if let Some(v) = self.background_raster_dpi {
-            c = c.background_raster_dpi(v);
-        }
-        if let Some(v) = self.occlusion_cull {
-            c = c.occlusion_cull(v);
-        }
-        if let Some(v) = self.sanitize {
-            c = c.sanitize(v);
-        }
-        for (name, data) in &self.custom_fonts {
-            c = c.add_font(name, data.clone());
-        }
-        if let Some(ref p) = self.base_path {
-            c = c.base_path(Path::new(p));
-        }
-        if let Some(ref p) = self.resource_root {
-            c = c.resource_root(Path::new(p));
-        }
-        if let Some(ref t) = self.header {
-            c = c.header(t.clone());
-        }
-        if let Some(ref t) = self.footer {
-            c = c.footer(t.clone());
-        }
-        c
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Ruby-visible class: Ironpress::HtmlConverter
-//
-// All setter methods mutate the receiver and return `self` so calls can be
-// chained:
-//
-//   converter = Ironpress::HtmlConverter.new
-//                 .page_size("Letter")
-//                 .margin(36.0)
-//                 .compress(true)
-//   pdf = converter.convert("<h1>Hello</h1>")
-// ---------------------------------------------------------------------------
-
-#[magnus::wrap(class = "Ironpress::HtmlConverter", free_immediately, size)]
-struct RbHtmlConverter {
-    inner: RefCell<ConverterInner>,
-}
-
-// Type alias for the typed Ruby object handle that can be both dereferenced
-// to &RbHtmlConverter and converted back to a Ruby Value.
-type RbSelf = typed_data::Obj<RbHtmlConverter>;
-
-// --- helpers ---------------------------------------------------------------
-
-fn parse_page_size(ruby: &Ruby, name: &str) -> Result<ironpress_core::types::PageSize, Error> {
-    match name.to_lowercase().as_str() {
-        "a4" => Ok(ironpress_core::types::PageSize::A4),
-        "letter" => Ok(ironpress_core::types::PageSize::LETTER),
-        "legal" => Ok(ironpress_core::types::PageSize::LEGAL),
-        _ => Err(Error::new(
-            ruby.exception_arg_error(),
-            format!("Unknown page size: {name}"),
-        )),
-    }
-}
-
-// --- methods ---------------------------------------------------------------
-
-impl RbHtmlConverter {
-    /// `Ironpress::HtmlConverter.new` -- create with defaults.
-    fn new() -> Self {
-        Self {
-            inner: RefCell::new(ConverterInner::default()),
-        }
-    }
-
-    /// `page_size(name)` -- set page size by name ("A4", "Letter", "Legal").
-    fn page_size(ruby: &Ruby, rb_self: RbSelf, name: String) -> Result<Value, Error> {
-        let size = parse_page_size(ruby, &name)?;
-        rb_self.inner.borrow_mut().page_size = size;
-        Ok(rb_self.into_value_with(ruby))
-    }
-
-    /// `margin(points)` -- set uniform margin on all sides.
-    fn margin(ruby: &Ruby, rb_self: RbSelf, points: f64) -> Value {
-        rb_self.inner.borrow_mut().margin =
-            ironpress_core::types::Margin::uniform(points as f32);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `margin_sides(top, right, bottom, left)` -- set per-side margins.
-    fn margin_sides(
-        ruby: &Ruby,
-        rb_self: RbSelf,
-        top: f64,
-        right: f64,
-        bottom: f64,
-        left: f64,
-    ) -> Value {
-        rb_self.inner.borrow_mut().margin = ironpress_core::types::Margin::new(
-            top as f32,
-            right as f32,
-            bottom as f32,
-            left as f32,
-        );
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `compress(enabled)` -- enable/disable FlateDecode compression.
-    fn compress(ruby: &Ruby, rb_self: RbSelf, enabled: bool) -> Value {
-        rb_self.inner.borrow_mut().compress = Some(enabled);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `jpeg_quality(quality)` -- JPEG quality 0-100.
-    fn jpeg_quality(ruby: &Ruby, rb_self: RbSelf, quality: u8) -> Value {
-        rb_self.inner.borrow_mut().jpeg_quality = Some(quality);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `auto_resize_images(enabled)` -- enable/disable automatic image downscaling.
-    fn auto_resize_images(ruby: &Ruby, rb_self: RbSelf, enabled: bool) -> Value {
-        rb_self.inner.borrow_mut().auto_resize_images = Some(enabled);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `image_dpi(dpi)` -- source image resolution (min 72, default 300).
-    fn image_dpi(ruby: &Ruby, rb_self: RbSelf, dpi: f64) -> Value {
-        rb_self.inner.borrow_mut().image_dpi = Some(dpi as f32);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `filter_dpi(dpi)` -- blur/filter bitmap DPI.
-    fn filter_dpi(ruby: &Ruby, rb_self: RbSelf, dpi: f64) -> Value {
-        rb_self.inner.borrow_mut().filter_dpi = Some(dpi as f32);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `mask_dpi(dpi)` -- CSS mask-image coverage DPI.
-    fn mask_dpi(ruby: &Ruby, rb_self: RbSelf, dpi: f64) -> Value {
-        rb_self.inner.borrow_mut().mask_dpi = Some(dpi as f32);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `background_raster_dpi(dpi)` -- background bitmap DPI.
-    fn background_raster_dpi(ruby: &Ruby, rb_self: RbSelf, dpi: f64) -> Value {
-        rb_self.inner.borrow_mut().background_raster_dpi = Some(dpi as f32);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `occlusion_cull(enabled)` -- enable/disable occlusion culling.
-    fn occlusion_cull(ruby: &Ruby, rb_self: RbSelf, enabled: bool) -> Value {
-        rb_self.inner.borrow_mut().occlusion_cull = Some(enabled);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `sanitize(enabled)` -- enable/disable HTML sanitization.
-    fn sanitize(ruby: &Ruby, rb_self: RbSelf, enabled: bool) -> Value {
-        rb_self.inner.borrow_mut().sanitize = Some(enabled);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `add_font(name, ttf_data)` -- register a custom TrueType font.
-    fn add_font(ruby: &Ruby, rb_self: RbSelf, name: String, ttf_data: RString) -> Value {
-        let data = unsafe { ttf_data.as_slice() }.to_vec();
-        rb_self.inner.borrow_mut().custom_fonts.push((name, data));
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `base_path(path)` -- base directory for resolving relative paths.
-    fn base_path(ruby: &Ruby, rb_self: RbSelf, path: String) -> Value {
-        rb_self.inner.borrow_mut().base_path = Some(path);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `resource_root(path)` -- authorized resource boundary directory.
-    fn resource_root(ruby: &Ruby, rb_self: RbSelf, path: String) -> Value {
-        rb_self.inner.borrow_mut().resource_root = Some(path);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `header(text)` -- header text rendered at the top of each page.
-    fn header(ruby: &Ruby, rb_self: RbSelf, text: String) -> Value {
-        rb_self.inner.borrow_mut().header = Some(text);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `footer(text)` -- footer text rendered at the bottom of each page.
-    /// Use `{page}` for current page number and `{pages}` for total count.
-    fn footer(ruby: &Ruby, rb_self: RbSelf, text: String) -> Value {
-        rb_self.inner.borrow_mut().footer = Some(text);
-        rb_self.into_value_with(ruby)
-    }
-
-    /// `convert(html)` -- convert HTML to PDF bytes.
-    fn convert(ruby: &Ruby, rb_self: RbSelf, html: String) -> Result<RString, Error> {
-        let converter = rb_self.inner.borrow().build();
-        let pdf = converter
-            .convert(&html)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        Ok(ruby.str_from_slice(&pdf))
-    }
-
-    /// `convert_markdown(markdown)` -- convert Markdown to PDF bytes.
-    fn convert_markdown(ruby: &Ruby, rb_self: RbSelf, markdown: String) -> Result<RString, Error> {
-        let converter = rb_self.inner.borrow().build();
-        let pdf = converter
-            .convert_markdown(&markdown)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        Ok(ruby.str_from_slice(&pdf))
-    }
-
-    /// `convert_to_file(html, path)` -- convert HTML and write PDF to a file.
-    fn convert_to_file(
-        ruby: &Ruby,
-        rb_self: RbSelf,
-        html: String,
-        path: String,
-    ) -> Result<Value, Error> {
-        let converter = rb_self.inner.borrow().build();
-        let pdf = converter
-            .convert(&html)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        std::fs::write(&path, &pdf)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        Ok(rb_self.into_value_with(ruby))
-    }
-
-    /// `convert_markdown_to_file(markdown, path)` -- convert Markdown and write PDF to a file.
-    fn convert_markdown_to_file(
-        ruby: &Ruby,
-        rb_self: RbSelf,
-        markdown: String,
-        path: String,
-    ) -> Result<Value, Error> {
-        let converter = rb_self.inner.borrow().build();
-        let pdf = converter
-            .convert_markdown(&markdown)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        std::fs::write(&path, &pdf)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
-        Ok(rb_self.into_value_with(ruby))
-    }
-}
-
-#[magnus::init]
-fn init(_ruby: &Ruby) -> Result<(), Error> {
-    let module = define_module("Ironpress")?;
-
-    // Module-level convenience functions (existing API).
-    module.define_singleton_method("html_to_pdf", function!(html_to_pdf, 1))?;
-    module.define_singleton_method("markdown_to_pdf", function!(markdown_to_pdf, 1))?;
-
-    // HtmlConverter class under the Ironpress module.
-    let klass = module.define_class("HtmlConverter", class::object())?;
-    klass.define_singleton_method("new", function!(RbHtmlConverter::new, 0))?;
-    klass.define_method("page_size", method!(RbHtmlConverter::page_size, 1))?;
-    klass.define_method("margin", method!(RbHtmlConverter::margin, 1))?;
-    klass.define_method("margin_sides", method!(RbHtmlConverter::margin_sides, 4))?;
-    klass.define_method("compress", method!(RbHtmlConverter::compress, 1))?;
-    klass.define_method("jpeg_quality", method!(RbHtmlConverter::jpeg_quality, 1))?;
-    klass.define_method(
-        "auto_resize_images",
-        method!(RbHtmlConverter::auto_resize_images, 1),
-    )?;
-    klass.define_method("image_dpi", method!(RbHtmlConverter::image_dpi, 1))?;
-    klass.define_method("filter_dpi", method!(RbHtmlConverter::filter_dpi, 1))?;
-    klass.define_method("mask_dpi", method!(RbHtmlConverter::mask_dpi, 1))?;
-    klass.define_method(
-        "background_raster_dpi",
-        method!(RbHtmlConverter::background_raster_dpi, 1),
-    )?;
-    klass.define_method("occlusion_cull", method!(RbHtmlConverter::occlusion_cull, 1))?;
-    klass.define_method("sanitize", method!(RbHtmlConverter::sanitize, 1))?;
-    klass.define_method("add_font", method!(RbHtmlConverter::add_font, 2))?;
-    klass.define_method("base_path", method!(RbHtmlConverter::base_path, 1))?;
-    klass.define_method("resource_root", method!(RbHtmlConverter::resource_root, 1))?;
-    klass.define_method("header", method!(RbHtmlConverter::header, 1))?;
-    klass.define_method("footer", method!(RbHtmlConverter::footer, 1))?;
-    klass.define_method("convert", method!(RbHtmlConverter::convert, 1))?;
-    klass.define_method(
-        "convert_markdown",
-        method!(RbHtmlConverter::convert_markdown, 1),
-    )?;
-    klass.define_method(
-        "convert_to_file",
-        method!(RbHtmlConverter::convert_to_file, 2),
-    )?;
-    klass.define_method(
-        "convert_markdown_to_file",
-        method!(RbHtmlConverter::convert_markdown_to_file, 2),
-    )?;
-
-    Ok(())
-}